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.
To send work into your agent, use the SDK from your backend or configure a provider connector and Recipe channel tools for incoming messages. Authentication explains how SDK calls carry the user identity.
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.
An MCP endpoint can link a connector with
bindings mcp connect --connector <id-or-slug>. The endpoint supplies the URL
and runtime scope, and the connector supplies authorization for the session
subject, falling back to the connector’s app connection. An endpoint with no
usable connection is left out of the session. Introspection applies the credential to outgoing requests outside the
sandbox. The connector setup guide walks through
authorization, binding, and discovery.
Provider-specific MCP defaults can also be supplied by a connection, such as
Linear’s hosted server. Use Recipe channel tools for Slack.
For Pipedream, each authorization adds an MCP endpoint for the selected runtime
whose server ID is the application slug, such as notion. Declare that server
ID in the recipe to use the application’s tools.
Use Operator in Slack when your
organization wants Operator to receive requests from a shared Slack workspace.
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 does not select tools. It only makes a declared
server reachable, and a server with no usable binding contributes no tools.
The model receives only tools allowed by both the package and the agent. If
either 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. Complete any provider consent before starting the task.
For platform connectors, use introspection connectors authorize interactively
or authorize-url to generate a customer link, then configure the endpoint
binding. See MCP tool declarations for the session 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 |
|---|---|
| Connector | Introspection uses the session subject’s connection, falling back to the connector’s app connection, and applies its credential at egress. An endpoint with no usable connection is left out of the session. The endpoint links the connector through metadata.connector_id. |
| 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. |
| Stored credential | 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. |
Choose one source for the Authorization header. A connector cannot be
combined with an authorized application or a stored Authorization header.
The endpoint host must also be allowed by the selected connector. Other
stored headers can accompany the selected authentication mode.
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.
- Control Plane API schema: The endpoint and connector REST contracts.