MCP and federation
Introspection uses the Model Context Protocol when an agent calls an external MCP server as a tool. An endpoint that uses authorized application authentication can also send the task identity to a partner server. The partner server decides whether to trust an identity provided by the caller or require an identity verified through federation.
In both cases, the agent sends a request to another system. To let another system send work to your agent, use your own backend with the SDK and the identity model in Authentication.
Let an agent call an MCP server
An agent can call an external MCP server as a set of tools. To make a server
available, configure an mcp endpoint binding. The
binding specifies the server address and authentication method. The agent can
then call the server’s tools like its other tools.
The runtime reads each server’s tool list when a task starts. The task uses that list until it ends. If you attach an endpoint or change its server address, the change applies to the next task. Recipe version changes work the same way.
A connector can also provide an MCP server. For a connector, the server address and credential come from a customer’s authorized connection instead of a binding that you configure. Introspection adds the credential to the outgoing request, so it never enters the sandbox. The tool selection rules below also apply to MCP servers provided by connectors.
Which tools an agent gets
The recipe package’s pi.mcp block limits the tools available to every agent in
the package. Each agent’s mcp: setting selects tools within that package
limit. The endpoint binding can place another limit on the tools.
The model receives only tools allowed by all three settings. If any setting
denies a tool, the model does not receive it. See
MCP tool declarations for the include and exclude rules and for
the checks run by introspection check.
Use the mcp command in a session
When an agent sets mode: cli in its mcp: block, the session receives one
mcp command instead of registering each MCP tool with Pi. The command can use
only the servers and tools selected by the recipe and the agent. It is available
at .pi/bin/mcp on the session’s PATH.
The command rejects servers added during the session, configuration overrides, and transport flags. OAuth cannot open a browser from a task. Cached credentials work, but you must authorize a server before the task if the server requires interactive consent. See MCP tool declarations for the command reference and limits.
The runtime does not add MCP instructions or notices to the agent’s prompt.
If an agent should use MCP tools, add the instructions to SYSTEM.md or the
agent’s system_instructions. The agent can run mcp --help to inspect the
command.
Carrying the task identity
When an agent calls a partner’s MCP server for a user, Introspection adds a JSON Web Token (JWT) to the request as it leaves the task environment. The token contains a temporary task identity. Introspection signs the token, and the token never enters the sandbox.
The JWT records how Introspection established the user’s identity.
identity_assertion means that Introspection verified the user through the
application’s configured identity provider. identity_attribution means that
an authenticated API key or service account supplied the user identity. See
Attribution and assertion are different trust levels
for the policy that a receiving server should apply to each type.
The MCP server verifies the JWT signature using the application’s published JSON Web Key Set (JWKS). It also checks the issuer, audience, expiration time, subject, token type, and task ID. A valid signature proves that Introspection issued the token, but it does not prove that an identity supplied by a caller was verified through federation.
Give the partner verification details
Each application publishes its own verification keys under the application’s client ID. Use the client ID from the application record rather than the application UUID. Give the receiving system the following values:
issuer https://<control-plane-host>/v1/applications/<client-id>
JWKS https://<control-plane-host>/v1/applications/<client-id>/.well-known/jwks.jsonIf the partner supports OpenID discovery, you only need to provide the issuer.
The issuer path serves an OpenID discovery document at
/.well-known/openid-configuration. The document includes the issuer and
jwks_uri values.
When you rotate an application key, Introspection publishes the new key with a
new kid at the existing JWKS URL. A partner that reads keys from the URL can
use the new key without a configuration change. If a partner stores an
individual key instead, update the partner before removing the old key.
The assertion proves the subject’s identity. The receiving system still decides what the subject can read or change. Page context and prompt metadata do not grant access.
Authentication modes for an MCP endpoint
An mcp endpoint can use any of the following authentication modes. The mode
does not depend on the protocol used by the endpoint.
| Mode | What it does |
|---|---|
| Authorized application | Introspection adds a signed task identity to the call. The endpoint decides whether to accept identities verified through federation, identities supplied by the caller, or both. |
| Bearer token | Introspection adds the same shared token to every call, such as a bot token. The call does not include a user identity. |
| Unauthenticated | Introspection adds no credential and permits outgoing requests only to allowed hosts. |
See Authentication and identity for the authentication methods and trust levels that produce each identity type.
Related
- MCP tool declarations: The tool policy and
mcpcommand reference. - Bindings: Where
mcpendpoints and their credentials are stored. - Connectors: MCP servers that use credentials from a customer’s authorized provider account.
- Authentication and identity: API keys, service accounts, federation, and identity trust levels.
- SDK authentication: How to configure the related token flows.
- API reference: The REST endpoints for MCP and identity features.