{
  "schemaVersion": "1.0",
  "title": "AIP MCP inside Hermes",
  "description": "Use this reference when a Hermes role must discover or call admitted AIP capabilities through aipd Streamable HTTP MCP. The configuration gives Hermes a bounded model-facing tool surface. Native AIP identity, policy, approval, and Action li",
  "canonical": "https://getaip.org/docs/connectors/hermes-agent/reference/aip-mcp-inside-hermes",
  "route": "/docs/connectors/hermes-agent/reference/aip-mcp-inside-hermes",
  "source": "docs/connectors/hermes-agent/reference/aip-mcp-inside-hermes.md",
  "protocol": "Agent Interoperability Protocol",
  "protocolVersion": "1.0",
  "section": "Connectors",
  "documentType": "Connector",
  "language": "en",
  "downloads": {
    "md": "/docs/download/connectors/hermes-agent/reference/aip-mcp-inside-hermes.md",
    "txt": "/docs/download/connectors/hermes-agent/reference/aip-mcp-inside-hermes.txt",
    "json": "/docs/download/connectors/hermes-agent/reference/aip-mcp-inside-hermes.json",
    "pdf": "/docs/download/connectors/hermes-agent/reference/aip-mcp-inside-hermes.pdf"
  },
  "content": {
    "format": "text/markdown",
    "markdown": "---\ntitle: AIP MCP inside Hermes\ndescription: >-\n  Configure a bounded AIP MCP surface inside Hermes without confusing MCP,\n  operator, Action, Session, or delegation authority\nkind: reference\naudience: integrator\nappliesTo: \"1.x\"\nwritingStandard: \"aip-docs/1.0\"\nlastReviewedRevision: \"97be86e9efedf07ecf1783b03800f683f107fb04\"\nconnector: hermes-agent\n---\n\n# AIP MCP inside Hermes\n\nUse this reference when a Hermes role must discover or call admitted AIP\ncapabilities through `aipd` Streamable HTTP MCP. The configuration gives Hermes\na bounded model-facing tool surface. Native AIP identity, policy, approval, and\nAction lifecycle remain authoritative after the MCP call crosses the boundary.\n\nThis path is deployment configuration. The Hermes connector does not create or\nchange the Hermes MCP profile, deliver its access token, or grant the MCP\nprincipal permission to call a capability.\n\n## Keep the four execution roles separate\n\n| Role | Entry point | Authority |\n|---|---|---|\n| Direct Hermes capability | Native AIP Action routed to one fixed Hermes API route | The admitted capability and endpoint binding |\n| Hermes operator | Native AIP Action routed to `cap:hermes_agent:<endpoint_id>:operator` | The operator binding and terminal provider state |\n| First-class AIP delegation | AIP routes a child Action to `agent:hermes_operator:<endpoint_id>` | The native delegation graph and child lifecycle |\n| AIP MCP inside Hermes | Hermes calls selected tools on protected `aipd /mcp` | The authenticated MCP principal and native AIP gateway |\n\nConfiguring the fourth role does not enable the third. Enabling first-class\ndelegation does not configure the fourth. The two paths meet only when the\ndelegation connector gives Hermes one exact native child-Action call to make.\n\nAn ordinary Hermes operator can also call `aip_call`. That call creates or\nexecutes work as the Hermes MCP principal. It is not first-class delegation\nunless AIP already created the child, supplied its immutable contract, and\nroutes the child to that Hermes delegate.\n\n## Follow the authority flow\n\nThe supported inside-Hermes path is:\n\n1. A deployment-owned Hermes profile opens Streamable HTTP MCP to `aipd`.\n2. The protected MCP endpoint authenticates the profile's access token.\n3. Hermes discovers only the server-native tools selected by its allowlist.\n4. The model sees Hermes-namespaced wrappers for those tools.\n5. `aipd` converts a tool call to a native message and trusted execution\n   context.\n6. The AIP gateway authorizes, admits, and routes the resulting Action.\n7. A lifecycle facade reads or changes the native Action owned by that\n   authenticated context.\n\nThe MCP allowlist controls which tool schemas Hermes registers. It does not\nauthorize the principal, restrict every possible `capability_id` argument to\n`aip_call`, or replace capability policy. Apply both controls.\n\n## Keep each identity distinct\n\n| Identity | Created or verified by | Purpose |\n|---|---|---|\n| Hermes role/profile | Hermes deployment | Selects configuration, model, and local tool exposure |\n| MCP principal | `aipd` authentication | Owns the trusted actor and tenant context for MCP calls |\n| MCP session ID | Streamable HTTP MCP | Binds protocol version, actor, and bounded replay state |\n| Hermes transcript or `session_id` | Hermes | Retains provider conversation or structured-run context |\n| AIP Action ID | AIP caller or `aip_call` | Identifies one native unit of requested work |\n| AIP Session ID | Native AIP lifecycle | Groups native Actions when the caller explicitly uses one |\n| Delegation and child Action IDs | Native delegation runtime | Bind parent, delegate, scope, and exact child execution |\n\nAn MCP session is not an AIP Session or a Hermes transcript. Closing or\nreplacing one does not close the others. Persist the Action ID before relying\non a result that may outlive the MCP connection.\n\nUse a distinct MCP principal for every independently governed Hermes role or\ninstance. A role that only discovers and calls capabilities should not inherit\napproval-decision, audit-export, broad cross-principal read, or\n`delegation:create` authority from an external orchestrator.\n\n## Install the Hermes MCP client surface\n\nThe pinned Hermes source treats MCP support as an optional package extra. A\nminimal image intended for this path installs the checkout with `.[mcp]`.\nWithout the MCP SDK and its Streamable HTTP client module, the configured\nserver cannot connect or register tools.\n\nThe reviewed Hermes code reads `mcp_servers` from its active\n`~/.hermes/config.yaml`. A deployment may place that file under the effective\n`HERMES_HOME`, but the owning Hermes profile and filesystem permissions must\nremain explicit.\n\n## Configure the bounded server entry\n\nThe following profile uses the stable AIP facade and a token injected into the\nHermes secret scope or environment:\n\n```yaml\nmcp_servers:\n  aip:\n    url: \"https://aip.example.com/mcp\"\n    headers:\n      Authorization: \"Bearer ${AIP_MCP_TOKEN}\"\n    enabled: true\n    timeout: 300\n    connect_timeout: 15\n    skip_preflight: true\n    supports_parallel_tool_calls: false\n    tools:\n      include:\n        - aip_capabilities\n        - aip_call\n        - aip_action_status\n        - aip_action_result\n        - aip_action_events\n        - aip_action_cancel\n      resources: false\n      prompts: false\n```\n\nUse the private service URL only inside a controlled network. Use the public\nHTTPS resource URL when Hermes crosses a trust boundary. The global MCP guide\nowns the supported protocol versions and protected-resource configuration.\n\n### Server-entry fields\n\n| Field | Reviewed behavior | Deployment decision |\n|---|---|---|\n| `url` | Selects HTTP; the default non-SSE path is Streamable HTTP | Point to the exact protected `/mcp` resource |\n| `headers` | Adds configured headers after secret interpolation | Inject a role-specific token; never put it in an Action |\n| `auth: oauth` | Selects Hermes OAuth 2.1 PKCE handling | Use instead of a static header when the identity service supports it |\n| `enabled` | `false` skips connection and registration | Keep disabled until identity and policy are ready |\n| `timeout` | Per-tool call; default is 300 seconds | Keep within the AIP and provider deadline design |\n| `connect_timeout` | Initial connection; default is 60 seconds | Use an explicit operational bound such as 15 seconds |\n| `skip_preflight` | Skips the HTTP content-type probe | Enable only for a verified POST-capable MCP endpoint |\n| `supports_parallel_tool_calls` | Opt-in; default is `false` | Keep false for governed state-changing work |\n| `tools.include` | Original server-native name whitelist | List only the facade tools the role needs |\n| `tools.resources` | Controls resource utility wrappers | Keep false when the role needs tools only |\n| `tools.prompts` | Controls prompt utility wrappers | Keep false when the role needs tools only |\n\n`tools.include` takes precedence if both `include` and `exclude` are present.\nAn empty or mismatched include list can leave the server connected with no\nuseful registered tools.\n\nHermes recursively replaces `${VAR}` and `${env:VAR}` in string values. It\nfirst uses the active profile's secret scope and then the process environment.\nAn unset value remains a literal placeholder. Treat that state as a failed\ndeployment check; do not assume an unresolved token becomes empty or safe.\n\nFor `auth: oauth`, complete the deployment-specific authorization bootstrap\nand token storage before starting an unattended role. Do not configure both an\nunreviewed static Authorization header and OAuth for the same identity.\n\n## Use original names in the allowlist\n\nThe allowlist contains names advertised by `aipd`. Hermes then registers each\nselected tool under a namespaced model-facing name.\n\n| Server-native allowlist name | Hermes registered name when server is `aip` | Purpose |\n|---|---|---|\n| `aip_capabilities` | `mcp__aip__aip_capabilities` | Discover visible native capabilities and contracts |\n| `aip_call` | `mcp__aip__aip_call` | Create or execute a native Action |\n| `aip_action_status` | `mcp__aip__aip_action_status` | Read current Action state |\n| `aip_action_result` | `mcp__aip__aip_action_result` | Read the authoritative durable result |\n| `aip_action_events` | `mcp__aip__aip_action_events` | Read bounded event and chunk history |\n| `aip_action_cancel` | `mcp__aip__aip_action_cancel` | Request native Action cancellation |\n\nDo not put the `mcp__aip__` form in `tools.include`. That name exists only\nafter Hermes converts the discovered schema. Hermes sanitizes non-alphanumeric\ncharacters in the server and tool components, so keep the logical server name\nstable.\n\nGenerated per-capability MCP tools may change with the admitted local catalog\nand can disappear when a fleet catalog owns discovery. Use the stable\n`aip_capabilities` and `aip_call` pair for native capability identity.\n\n## Bound what `aip_call` can target\n\nThe tool allowlist admits one generic `aip_call` schema. Its arguments still\ncontain a `capability_id`. Therefore, tool filtering alone does not stop a\nHermes role from asking for another visible capability.\n\nBind the MCP principal to one tenant and apply AIP authorization and policy for\nthe smallest allowed capability set. In particular, prevent a role from\ncalling its own Hermes operator capability or another route that returns to\nthe same model loop unless the topology has an explicit bounded recursion\ndesign.\n\nDiscovery is not authorization. A capability returned by\n`aip_capabilities` can still be rejected at invocation, approval, connector\nadmission, or provider execution.\n\n## Preserve native Action identity\n\nFor an ordinary call, `aip_call` accepts a native `capability_id`, input, and\noptional Action fields. If `action_id` is omitted, the facade creates a new\nnative ID. Persist the returned ID before retrying or switching to lifecycle\ntools.\n\nFor first-class delegation, omission is not allowed. The Hermes operator\nreceives an exact `aip_call` argument object whose fields describe the child\nAction already created by AIP. The call must preserve:\n\n- `action_id`;\n- `capability_id` and input;\n- mode, idempotency key, and timeout;\n- conversation and memory context;\n- delegation chain and federation context;\n- callback, observability, compliance, approval, and transaction context.\n\nThe connector removes model-selected identity because the MCP transport must\nsupply the authenticated principal. After Hermes completes, the result\nresolver compares the native child contract, trusted owner, tenant, queue, and\nlifecycle result. A replacement Action ID or model-written result fails that\nverification.\n\n## Exclude recursive delegation\n\nDo not expose `aip_delegate` to the ordinary model-facing Hermes tool set. The\nexternal AIP runtime owns the original parent, child ID, delegate, scope,\ndepth, cycle checks, approval, and durable outbox.\n\nGiving the same model an unrestricted delegation-creation tool can start a new\ndelegation graph instead of continuing the one it received. It can also route\nwork back into the same operator. The reviewed profile excludes this tool and\ndoes not grant `delegation:create` to the normal internal operator identity.\n\nIf a separate broker is designed to create delegation, isolate its principal,\npropagate and validate the original chain, enforce depth and cycle bounds, and\nkeep that broker out of the ordinary Hermes model tool surface.\n\n## Keep calls sequential unless proved otherwise\n\n`supports_parallel_tool_calls: false` keeps the server out of Hermes's\nparallel-safe MCP set. This reduces concurrent model-issued calls from the\nsame role, but it is not an exactly-once guarantee.\n\nA network failure can occur after `aipd` accepted an Action. For a mutation,\nreuse the same Action ID or required idempotency key only according to the\nnative capability contract. Query `aip_action_status` or\n`aip_action_result` before issuing another call. Never infer that a timeout\nmeans the provider did nothing.\n\n## Protect credentials and returned data\n\n- Store the MCP token in the Hermes profile's secret scope, environment, or an\n  equivalent deployment secret, not in source or Action input.\n- Use one token and principal per independently governed Hermes role.\n- Give the principal only the transport and native operation scopes it needs.\n- Keep endpoint, issuer, audience, expiry, tenant, and scope checks at `aipd`.\n- Keep `ssl_verify` enabled and use a trusted CA at network boundaries.\n- Do not give Hermes database or system-of-record credentials merely to prove\n  an AIP-mediated workflow.\n- Treat MCP tool output as application data. Apply the capability's declared\n  classification and redaction rules before adding it to a transcript.\n\nThe current Hermes Streamable HTTP client strips Authorization when a redirect\ncrosses origin. The deployment should still use the final MCP URL and avoid\nrelying on redirects as a routing mechanism.\n\n## Verify configuration and discovery\n\nThe pinned Hermes CLI exposes two useful static-to-connection checks:\n\n```sh\nhermes mcp list\nhermes mcp test aip\n```\n\n`hermes mcp list` reports configured servers and selected-tool count. It does\nnot connect. `hermes mcp test aip` resolves the profile, attempts MCP\ninitialization, and lists discovered server-native tools. It does not prove\nthat the principal can invoke every listed capability or that a connector is\nqualified.\n\nAfter changing a running Hermes profile, `/reload-mcp` reconnects configured\nservers, rebuilds the registered tool set, and invalidates the provider prompt\ncache. Treat that as an operational change and confirm that the next execution\nreceives the intended schemas.\n\nRetain evidence that:\n\n1. the effective profile belongs to the intended Hermes role;\n2. the URL is the intended protected `aipd` MCP resource;\n3. the token resolves without appearing in logs or retained output;\n4. authentication resolves the expected principal and tenant;\n5. exactly the six original stable facade names are discovered;\n6. Hermes registers the corresponding six `mcp__aip__...` names;\n7. resources, prompts, generated tools, and `aip_delegate` are absent;\n8. a permitted read succeeds and a forbidden capability fails closed;\n9. an accepted Action can be found by the same stable Action ID;\n10. a timeout is reconciled through lifecycle reads rather than blind replay;\n11. a delegated child rejects changed identity, contract, or result authority;\n12. restart or reload preserves the intended least-privilege surface.\n\nThese checks qualify only the recorded profile, token, `aipd`, connector\ncatalog, Hermes artifact, and time window.\n\n## Resolve failures by boundary\n\n| Symptom | Boundary | Safe response |\n|---|---|---|\n| Hermes reports no MCP SDK | Image/package | Install the pinned Hermes `mcp` extra and rebuild the exact artifact |\n| Server is configured but absent | Profile or `enabled` | Confirm the active profile path and that `enabled` is true |\n| Preflight reports a non-MCP page | URL or proxy | Point to `/mcp`; bypass preflight only after verifying POST behavior |\n| `401 Unauthorized` | MCP authentication | Check token resolution, issuer, audience, expiry, and required transport scopes |\n| Connection works but selected tools are missing | Discovery or filter | Compare original names with `tools.include` and the effective catalog |\n| Model requests an unknown single-underscore name | Hermes namespace | Use the registered `mcp__aip__<tool>` name; keep original names in the allowlist |\n| A listed capability is denied | Native AIP authorization | Keep the denial; correct principal policy rather than widening the tool set |\n| Call times out after submission | Action lifecycle | Query by Action ID; do not repeat an unsafe mutation blindly |\n| Delegated result reports an integrity mismatch | Delegation contract | Fail closed and retain the supplied and observed native records |\n| The same Hermes role invokes itself | Capability policy | Disable the route, preserve current Actions, and remove the recursive target |\n| OAuth works interactively but not at startup | Token bootstrap | Establish the role's approved token flow before unattended startup |\n| Reload changes the visible tool surface | Hermes registry | Reconcile config, discovered names, and the owning execution context |\n\nDo not solve an AIP policy denial by exposing more MCP tools or granting a\nbroad orchestrator token to Hermes. Do not solve an MCP transport failure by\nbypassing native Action identity or calling the provider directly.\n\n## Evidence boundary\n\nThe reviewed sources define the profile, tool projection, stable facade, and\ndelegated-result checks. They do not prove that a particular Hermes artifact\nconnected, that an identity provider issued the intended token, that a model\nused the correct tool, or that a provider completed an Action.\n\nRecord exact AIP and Hermes revisions, image digests, profile hash, endpoint,\nprincipal, tenant, allowlist, policy revision, and retained Action evidence\nbefore making an interoperability or readiness claim.\n\n## Related documentation\n\n- [Use AIP through MCP](../../../guides/use-aip-through-mcp.md)\n- [Hermes operator and delegation capability](../capabilities/operator-and-delegation.md)\n- [Hermes authentication and endpoints](../getting-started/authentication-and-endpoints.md)\n- [Identity and trust](../../../concepts/identity-and-trust.md)\n- [Delegation](../../../concepts/delegation.md)\n- [Errors and recovery](../../../reference/errors.md)\n",
    "text": "AIP MCP inside Hermes\n\nUse this reference when a Hermes role must discover or call admitted AIP\ncapabilities through aipd Streamable HTTP MCP. The configuration gives Hermes\na bounded model-facing tool surface. Native AIP identity, policy, approval, and\nAction lifecycle remain authoritative after the MCP call crosses the boundary.\n\nThis path is deployment configuration. The Hermes connector does not create or\nchange the Hermes MCP profile, deliver its access token, or grant the MCP\nprincipal permission to call a capability.\n\nKeep the four execution roles separate\n\n| Role | Entry point | Authority |\n\n| Direct Hermes capability | Native AIP Action routed to one fixed Hermes API route | The admitted capability and endpoint binding |\n| Hermes operator | Native AIP Action routed to cap:hermesagent::operator | The operator binding and terminal provider state |\n| First-class AIP delegation | AIP routes a child Action to agent:hermesoperator: | The native delegation graph and child lifecycle |\n| AIP MCP inside Hermes | Hermes calls selected tools on protected aipd /mcp | The authenticated MCP principal and native AIP gateway |\n\nConfiguring the fourth role does not enable the third. Enabling first-class\ndelegation does not configure the fourth. The two paths meet only when the\ndelegation connector gives Hermes one exact native child-Action call to make.\n\nAn ordinary Hermes operator can also call aipcall. That call creates or\nexecutes work as the Hermes MCP principal. It is not first-class delegation\nunless AIP already created the child, supplied its immutable contract, and\nroutes the child to that Hermes delegate.\n\nFollow the authority flow\n\nThe supported inside-Hermes path is:\n1. A deployment-owned Hermes profile opens Streamable HTTP MCP to aipd.\n2. The protected MCP endpoint authenticates the profile's access token.\n3. Hermes discovers only the server-native tools selected by its allowlist.\n4. The model sees Hermes-namespaced wrappers for those tools.\n5. aipd converts a tool call to a native message and trusted execution\n   context.\n6. The AIP gateway authorizes, admits, and routes the resulting Action.\n7. A lifecycle facade reads or changes the native Action owned by that\n   authenticated context.\n\nThe MCP allowlist controls which tool schemas Hermes registers. It does not\nauthorize the principal, restrict every possible capabilityid argument to\naipcall, or replace capability policy. Apply both controls.\n\nKeep each identity distinct\n\n| Identity | Created or verified by | Purpose |\n\n| Hermes role/profile | Hermes deployment | Selects configuration, model, and local tool exposure |\n| MCP principal | aipd authentication | Owns the trusted actor and tenant context for MCP calls |\n| MCP session ID | Streamable HTTP MCP | Binds protocol version, actor, and bounded replay state |\n| Hermes transcript or sessionid | Hermes | Retains provider conversation or structured-run context |\n| AIP Action ID | AIP caller or aipcall | Identifies one native unit of requested work |\n| AIP Session ID | Native AIP lifecycle | Groups native Actions when the caller explicitly uses one |\n| Delegation and child Action IDs | Native delegation runtime | Bind parent, delegate, scope, and exact child execution |\n\nAn MCP session is not an AIP Session or a Hermes transcript. Closing or\nreplacing one does not close the others. Persist the Action ID before relying\non a result that may outlive the MCP connection.\n\nUse a distinct MCP principal for every independently governed Hermes role or\ninstance. A role that only discovers and calls capabilities should not inherit\napproval-decision, audit-export, broad cross-principal read, or\ndelegation:create authority from an external orchestrator.\n\nInstall the Hermes MCP client surface\n\nThe pinned Hermes source treats MCP support as an optional package extra. A\nminimal image intended for this path installs the checkout with .[mcp].\nWithout the MCP SDK and its Streamable HTTP client module, the configured\nserver cannot connect or register tools.\n\nThe reviewed Hermes code reads mcpservers from its active\n/.hermes/config.yaml. A deployment may place that file under the effective\nHERMESHOME, but the owning Hermes profile and filesystem permissions must\nremain explicit.\n\nConfigure the bounded server entry\n\nThe following profile uses the stable AIP facade and a token injected into the\nHermes secret scope or environment:\n\nmcpservers:\n  aip:\n    url: \"https://aip.example.com/mcp\"\n    headers:\n      Authorization: \"Bearer ${AIPMCPTOKEN}\"\n    enabled: true\n    timeout: 300\n    connecttimeout: 15\n    skippreflight: true\n    supportsparalleltoolcalls: false\n    tools:\n      include:\n• aipcapabilities\n• aipcall\n• aipactionstatus\n• aipactionresult\n• aipactionevents\n• aipactioncancel\n      resources: false\n      prompts: false\n\nUse the private service URL only inside a controlled network. Use the public\nHTTPS resource URL when Hermes crosses a trust boundary. The global MCP guide\nowns the supported protocol versions and protected-resource configuration.\n\nServer-entry fields\n\n| Field | Reviewed behavior | Deployment decision |\n\n| url | Selects HTTP; the default non-SSE path is Streamable HTTP | Point to the exact protected /mcp resource |\n| headers | Adds configured headers after secret interpolation | Inject a role-specific token; never put it in an Action |\n| auth: oauth | Selects Hermes OAuth 2.1 PKCE handling | Use instead of a static header when the identity service supports it |\n| enabled | false skips connection and registration | Keep disabled until identity and policy are ready |\n| timeout | Per-tool call; default is 300 seconds | Keep within the AIP and provider deadline design |\n| connecttimeout | Initial connection; default is 60 seconds | Use an explicit operational bound such as 15 seconds |\n| skippreflight | Skips the HTTP content-type probe | Enable only for a verified POST-capable MCP endpoint |\n| supportsparalleltoolcalls | Opt-in; default is false | Keep false for governed state-changing work |\n| tools.include | Original server-native name whitelist | List only the facade tools the role needs |\n| tools.resources | Controls resource utility wrappers | Keep false when the role needs tools only |\n| tools.prompts | Controls prompt utility wrappers | Keep false when the role needs tools only |\n\ntools.include takes precedence if both include and exclude are present.\nAn empty or mismatched include list can leave the server connected with no\nuseful registered tools.\n\nHermes recursively replaces ${VAR} and ${env:VAR} in string values. It\nfirst uses the active profile's secret scope and then the process environment.\nAn unset value remains a literal placeholder. Treat that state as a failed\ndeployment check; do not assume an unresolved token becomes empty or safe.\n\nFor auth: oauth, complete the deployment-specific authorization bootstrap\nand token storage before starting an unattended role. Do not configure both an\nunreviewed static Authorization header and OAuth for the same identity.\n\nUse original names in the allowlist\n\nThe allowlist contains names advertised by aipd. Hermes then registers each\nselected tool under a namespaced model-facing name.\n\n| Server-native allowlist name | Hermes registered name when server is aip | Purpose |\n\n| aipcapabilities | mcpaipaipcapabilities | Discover visible native capabilities and contracts |\n| aipcall | mcpaipaipcall | Create or execute a native Action |\n| aipactionstatus | mcpaipaipactionstatus | Read current Action state |\n| aipactionresult | mcpaipaipactionresult | Read the authoritative durable result |\n| aipactionevents | mcpaipaipactionevents | Read bounded event and chunk history |\n| aipactioncancel | mcpaipaipactioncancel | Request native Action cancellation |\n\nDo not put the mcpaip form in tools.include. That name exists only\nafter Hermes converts the discovered schema. Hermes sanitizes non-alphanumeric\ncharacters in the server and tool components, so keep the logical server name\nstable.\n\nGenerated per-capability MCP tools may change with the admitted local catalog\nand can disappear when a fleet catalog owns discovery. Use the stable\naipcapabilities and aipcall pair for native capability identity.\n\nBound what aipcall can target\n\nThe tool allowlist admits one generic aipcall schema. Its arguments still\ncontain a capabilityid. Therefore, tool filtering alone does not stop a\nHermes role from asking for another visible capability.\n\nBind the MCP principal to one tenant and apply AIP authorization and policy for\nthe smallest allowed capability set. In particular, prevent a role from\ncalling its own Hermes operator capability or another route that returns to\nthe same model loop unless the topology has an explicit bounded recursion\ndesign.\n\nDiscovery is not authorization. A capability returned by\naipcapabilities can still be rejected at invocation, approval, connector\nadmission, or provider execution.\n\nPreserve native Action identity\n\nFor an ordinary call, aipcall accepts a native capabilityid, input, and\noptional Action fields. If actionid is omitted, the facade creates a new\nnative ID. Persist the returned ID before retrying or switching to lifecycle\ntools.\n\nFor first-class delegation, omission is not allowed. The Hermes operator\nreceives an exact aipcall argument object whose fields describe the child\nAction already created by AIP. The call must preserve:\n• actionid;\n• capabilityid and input;\n• mode, idempotency key, and timeout;\n• conversation and memory context;\n• delegation chain and federation context;\n• callback, observability, compliance, approval, and transaction context.\n\nThe connector removes model-selected identity because the MCP transport must\nsupply the authenticated principal. After Hermes completes, the result\nresolver compares the native child contract, trusted owner, tenant, queue, and\nlifecycle result. A replacement Action ID or model-written result fails that\nverification.\n\nExclude recursive delegation\n\nDo not expose aipdelegate to the ordinary model-facing Hermes tool set. The\nexternal AIP runtime owns the original parent, child ID, delegate, scope,\ndepth, cycle checks, approval, and durable outbox.\n\nGiving the same model an unrestricted delegation-creation tool can start a new\ndelegation graph instead of continuing the one it received. It can also route\nwork back into the same operator. The reviewed profile excludes this tool and\ndoes not grant delegation:create to the normal internal operator identity.\n\nIf a separate broker is designed to create delegation, isolate its principal,\npropagate and validate the original chain, enforce depth and cycle bounds, and\nkeep that broker out of the ordinary Hermes model tool surface.\n\nKeep calls sequential unless proved otherwise\n\nsupportsparalleltoolcalls: false keeps the server out of Hermes's\nparallel-safe MCP set. This reduces concurrent model-issued calls from the\nsame role, but it is not an exactly-once guarantee.\n\nA network failure can occur after aipd accepted an Action. For a mutation,\nreuse the same Action ID or required idempotency key only according to the\nnative capability contract. Query aipactionstatus or\naipactionresult before issuing another call. Never infer that a timeout\nmeans the provider did nothing.\n\nProtect credentials and returned data\n• Store the MCP token in the Hermes profile's secret scope, environment, or an\n  equivalent deployment secret, not in source or Action input.\n• Use one token and principal per independently governed Hermes role.\n• Give the principal only the transport and native operation scopes it needs.\n• Keep endpoint, issuer, audience, expiry, tenant, and scope checks at aipd.\n• Keep sslverify enabled and use a trusted CA at network boundaries.\n• Do not give Hermes database or system-of-record credentials merely to prove\n  an AIP-mediated workflow.\n• Treat MCP tool output as application data. Apply the capability's declared\n  classification and redaction rules before adding it to a transcript.\n\nThe current Hermes Streamable HTTP client strips Authorization when a redirect\ncrosses origin. The deployment should still use the final MCP URL and avoid\nrelying on redirects as a routing mechanism.\n\nVerify configuration and discovery\n\nThe pinned Hermes CLI exposes two useful static-to-connection checks:\n\nhermes mcp list\nhermes mcp test aip\n\nhermes mcp list reports configured servers and selected-tool count. It does\nnot connect. hermes mcp test aip resolves the profile, attempts MCP\ninitialization, and lists discovered server-native tools. It does not prove\nthat the principal can invoke every listed capability or that a connector is\nqualified.\n\nAfter changing a running Hermes profile, /reload-mcp reconnects configured\nservers, rebuilds the registered tool set, and invalidates the provider prompt\ncache. Treat that as an operational change and confirm that the next execution\nreceives the intended schemas.\n\nRetain evidence that:\n1. the effective profile belongs to the intended Hermes role;\n2. the URL is the intended protected aipd MCP resource;\n3. the token resolves without appearing in logs or retained output;\n4. authentication resolves the expected principal and tenant;\n5. exactly the six original stable facade names are discovered;\n6. Hermes registers the corresponding six mcpaip... names;\n7. resources, prompts, generated tools, and aipdelegate are absent;\n8. a permitted read succeeds and a forbidden capability fails closed;\n9. an accepted Action can be found by the same stable Action ID;\n10. a timeout is reconciled through lifecycle reads rather than blind replay;\n11. a delegated child rejects changed identity, contract, or result authority;\n12. restart or reload preserves the intended least-privilege surface.\n\nThese checks qualify only the recorded profile, token, aipd, connector\ncatalog, Hermes artifact, and time window.\n\nResolve failures by boundary\n\n| Symptom | Boundary | Safe response |\n\n| Hermes reports no MCP SDK | Image/package | Install the pinned Hermes mcp extra and rebuild the exact artifact |\n| Server is configured but absent | Profile or enabled | Confirm the active profile path and that enabled is true |\n| Preflight reports a non-MCP page | URL or proxy | Point to /mcp; bypass preflight only after verifying POST behavior |\n| 401 Unauthorized | MCP authentication | Check token resolution, issuer, audience, expiry, and required transport scopes |\n| Connection works but selected tools are missing | Discovery or filter | Compare original names with tools.include and the effective catalog |\n| Model requests an unknown single-underscore name | Hermes namespace | Use the registered mcpaip name; keep original names in the allowlist |\n| A listed capability is denied | Native AIP authorization | Keep the denial; correct principal policy rather than widening the tool set |\n| Call times out after submission | Action lifecycle | Query by Action ID; do not repeat an unsafe mutation blindly |\n| Delegated result reports an integrity mismatch | Delegation contract | Fail closed and retain the supplied and observed native records |\n| The same Hermes role invokes itself | Capability policy | Disable the route, preserve current Actions, and remove the recursive target |\n| OAuth works interactively but not at startup | Token bootstrap | Establish the role's approved token flow before unattended startup |\n| Reload changes the visible tool surface | Hermes registry | Reconcile config, discovered names, and the owning execution context |\n\nDo not solve an AIP policy denial by exposing more MCP tools or granting a\nbroad orchestrator token to Hermes. Do not solve an MCP transport failure by\nbypassing native Action identity or calling the provider directly.\n\nEvidence boundary\n\nThe reviewed sources define the profile, tool projection, stable facade, and\ndelegated-result checks. They do not prove that a particular Hermes artifact\nconnected, that an identity provider issued the intended token, that a model\nused the correct tool, or that a provider completed an Action.\n\nRecord exact AIP and Hermes revisions, image digests, profile hash, endpoint,\nprincipal, tenant, allowlist, policy revision, and retained Action evidence\nbefore making an interoperability or readiness claim.\n\nRelated documentation\n• Use AIP through MCP (../../../guides/use-aip-through-mcp.md)\n• Hermes operator and delegation capability (../capabilities/operator-and-delegation.md)\n• Hermes authentication and endpoints (../getting-started/authentication-and-endpoints.md)\n• Identity and trust (../../../concepts/identity-and-trust.md)\n• Delegation (../../../concepts/delegation.md)\n• Errors and recovery (../../../reference/errors.md)\n"
  },
  "integrity": {
    "algorithm": "sha256",
    "sourceDigest": "e5a57f7cc71473a4b76ec3da4b4d3b7d60db5bca1696a884de62c18816354cb0"
  }
}