Site Tools on a Hub¶
The Hub's MCP server lists every tool a site's MCP server lists, except the user and role tools, which a site refuses through the Hub. Each tool keeps its name and arguments, and takes one more argument, site, the site to run at; its description gains a sentence saying so. The Hub sends the call to that site with a statement it signs for the call, and returns the site's answer as the site sent it. The site runs the call as described in MCP Calls Through the Hub.
The Hub checks only that the person's access covers the tool. Every other check, such as zone permissions or whether the tool needs an administrator, is made by the site, against the person's Hub user there.
Every tool a site lists runs at a site, including get_instance_info, identify_session and send_report, so each of them takes site at the Hub too. Only the Hub's own tools take no site: the help tools search_help and get_code_wizard_reference, which the Hub answers itself, list_sites, and the job tools.
Finding a Site¶
site is the site's Subdomain Label, as list_sites gives it. list_sites lists the sites where the person's role holds the MCP grant, in label order, and needs only read-only access. It returns up to limit sites at a time, 100 by default and never more than the Hub's Max Page Size; when there are more, pass the nextCursor it returns as cursor.
| Member | Holds |
|---|---|
site |
The label every site tool takes as site |
displayName |
The site's name at the Hub |
siteIdentifier |
The site's identifier |
connected |
Whether the site's tunnel is connected |
takesMcpCalls |
Whether the site takes MCP calls from the Hub for this person, as far as the Hub knows |
reason |
Why not, when it does not |
The Hub judges takesMcpCalls from the site's settings as the site last reported them. A site reports them when its tunnel connects and again when they change (see MCP Calls Through the Hub).
When the person's role holds MCP at no site, list_sites returns no sites and a note saying how the grant is given: "Your role holds the MCP grant at no site at this Hub. Hub administrators hold it only through their role too: a Hub administrator gives a role the MCP grant for tags in the Site Access section of the role, on the Manage Roles page." (see Site Access Grants).
Why a Site Does Not Take Calls¶
A reason that a site setting explains names the setting and where it is at the site.
reason |
What to change |
|---|---|
| it is disabled at the Hub | Select the site on the Hub's Sites Dashboard and click Enable. |
| it has not yet told the Hub its Hub settings | Connect the site's tunnel; the site reports its settings when it connects. |
| 'Use Hub' is off at this site (System Configuration, Remote Management Hub, Hub Sign-In tab) | Turn on Use Hub at the site, with a Role Map entry (see Hub Sign-In). |
| This site's version does not take MCP calls from the Hub | Upgrade the site. |
| 'Accept MCP calls through the Hub' is off at this site (System Configuration, Remote Management Hub, Hub Sign-In tab) | Tick Accept MCP calls through the Hub at the site and click Apply (see Hub Sign-In). |
| The person has no Hub role, so no 'Role Map' entry at this site matches (System Configuration, Remote Management Hub, Hub Sign-In tab) | Give the person's Hub user a role at the Hub. |
| The Hub role '...' matches no 'Role Map' entry at this site (System Configuration, Remote Management Hub, Hub Sign-In tab) | Add a Role Map entry at the site that matches the role, or give the person a role an entry matches. |
What a Call Needs¶
The Hub sends nothing to a site, and refuses the call with the reason, unless all of these hold:
- The Hub is not in a lockdown: more sites registered than its license allows (see Licensed Site Count), or site connections blocked by failed check-ins.
- The site is enabled at the Hub.
- The person's role holds the MCP grant at the site.
- The site has reported its Hub settings, and the report says it takes MCP calls from the Hub for this person. That needs Use Hub and Accept MCP calls through the Hub on, on the site's Hub Sign-In tab, a site version that takes MCP calls from the Hub, and a Role Map entry that matches the person's Hub role.
- The site's tunnel is connected.
The site then makes its own checks and may still refuse. The Hub waits up to 60 seconds for the site's answer. When none comes, or a Hub node relaying to the site loses its connection to the site before the answer arrives, the call is reported as one that may still have run at the site, so check before trying it again.
Running a Tool Across a Tag¶
A tool that only reads and never asks the person, such as get_zone_status or get_instance_info, also takes tag in place of site. get_object and export_configuration take only site: each returns a whole object or export, which the Read Cap (bytes) does not cut, so an answer across a tag would have no limit. tag is the name of a tag at the Hub, matched ignoring case; the built-in All sites tag reaches every site (see Tags). Send site or tag, never both.
- The Hub runs the tool at each site carrying the tag, in label order, four sites at a time, with a statement of its own for each site. Each tag call has its own four workers, so one tag call never waits for another. A site that has not answered within the time its call allows, plus five seconds, is reported as failed and the call goes on.
- A site where the person's role does not hold the MCP grant is left out of the results, and nothing is sent to it. A site whose grant is removed while the call runs is reported as
not permitted. - No further sites start once the Hub's Request Timeout (seconds), less five seconds, has passed, or once the answers gathered reach the Hub's Read Cap (bytes). The answer then carries
nextSiteCursor. The first four sites of each call always run, so every call reaches at least one site. Call the tool again with the same arguments andsiteCursorset to that value to go on from the first site not reached. - A site that asks the person to confirm something is reported as refused. Run the tool at that one site instead.
The answer gives the tag's name as tag and lists each site the call came to, in order:
| Member | Holds |
|---|---|
site |
The site's label |
displayName |
The site's name at the Hub |
outcome |
done, error (the tool ran and returned an error), not permitted, refused (the Hub or the site refused the call, or no answer came) or failed |
result |
The site's whole answer, for done and error |
message |
Why the call was refused, for refused |
An answer whose first four sites alone pass the Read Cap (bytes) is cut as any other result is.
Confirmations¶
When a site asks the person to confirm an action, the Hub puts the question to the person through their AI assistant and sends the answer back to the site in a second statement (see Confirmations in Two Steps). The question waits for the Hub's Request Timeout (seconds). When the person gives no answer, the Hub sends a cancel, nothing is changed, and the call ends with confirmation_cancelled.
An assistant that cannot show a form is refused these actions at a site whose Require client confirmation is on. send_report is refused there too, through any assistant, because the Hub passes on the report's comment, name and email as the assistant sent them rather than from a form the site showed the person.
When a Call Is Refused¶
| Refusal | Code |
|---|---|
| No site has the label, the person's role does not hold the MCP grant at the site, or no tag has the name | not_found |
Both site and tag were sent, or neither |
validation_failed |
| The Hub is in a lockdown, or the site is disabled at the Hub | operation_refused |
| The site has not reported its Hub settings, or its report says it would refuse | operation_refused |
| The site is not connected, or gave no answer in time | operation_refused |
| The site runs a version that does not take MCP calls from the Hub | operation_refused |
| The site refused the statement because the person's Hub role is not mapped or their Hub user is disabled | permission_denied |
| The site refused the statement for any other reason, such as a switch that is off or a limit | operation_refused |
| The site could not run the call, or its answer could not be read | internal_error |
Each message names the site by its label and gives the reason, which names the setting to change when one is the cause, for example: "Site 'east-lab' does not take this call from the Hub: 'Use Hub' is off at this site (System Configuration, Remote Management Hub, Hub Sign-In tab). Nothing was sent." A refusal from the tool itself, once the site runs it, comes back as the site wrote it, with the codes described in MCP Tool Results and Errors.