MCP API¶
Model Context Protocol (MCP) client support. Build MCP server toolsets and attach
them to an agent via the mcp_servers parameter of
create_deep_agent. See
MCP servers for the conceptual overview.
build_mcp_server¶
pydantic_deep.mcp.build_mcp_server(config, resolver=None, *, oauth_token_storage=None)
¶
Build a connected pydantic-ai MCP toolset from a config.
Resolves the auth secret (if any) and injects it as an HTTP header (for
bearer/header auth) or a subprocess env var (for env auth).
Wraps the toolset in a PrefixedToolset when tool_prefix is set.
For stdio servers, the subprocess receives config.env (plus any
env-kind auth var) layered on top of the MCP SDK's safe default
environment (PATH, HOME, …) — the parent process's full environment
is intentionally not inherited, so secrets like API keys are never
leaked to a third-party server. Add anything else a server needs (proxies,
NODE_EXTRA_CA_CERTS, …) explicitly via config.env.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
oauth_token_storage
|
Any | None
|
A persistent |
None
|
Raises:
| Type | Description |
|---|---|
MCPNotInstalledError
|
if the |
probe_mcp_server¶
pydantic_deep.mcp.probe_mcp_server(server, timeout=10.0)
async
¶
Connect to a built MCP server and list its tools, with a timeout.
Returns a :class:MCPProbeResult capturing success + tool names, or the
error string on failure. Never raises.
builtin_mcp_servers¶
pydantic_deep.mcp.builtin_mcp_servers()
¶
Return fresh :class:MCPServerConfig instances for the built-in servers.
All are disabled by default — the user opts in via /mcp.
auth_satisfied¶
pydantic_deep.mcp.auth_satisfied(config, resolver=None)
¶
True when the server needs no pre-stored secret, or its secret resolves.
oauth servers are always considered satisfied here — they authorize
interactively at connect time, with no token to enter up front.
MCPServerConfig¶
pydantic_deep.mcp.MCPServerConfig
dataclass
¶
Connection + auth description for a single MCP server.
A stdio server requires command; http/sse servers require url.
requires_auth
property
¶
True when a pre-stored secret must be provided before use.
oauth returns False: there's no token to enter up front — the client
runs the OAuth flow interactively at connect time.
MCPAuth¶
pydantic_deep.mcp.MCPAuth
dataclass
¶
Describes how to authenticate to an MCP server using a stored secret.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
secret_key
|
str
|
Name under which the token is stored (keystore / env var),
e.g. |
''
|
kind
|
MCPAuthKind
|
How auth is performed (see :data: |
'bearer'
|
header
|
str
|
Header name for |
'Authorization'
|
env_var
|
str | None
|
Environment variable name for |
None
|
value_template
|
str
|
Template formatted with |
'Bearer {token}'
|
instructions
|
str
|
Human-readable hint on how to obtain the token, shown in the CLI login flow. |
''
|
client_name
|
str | None
|
OAuth client name advertised during dynamic client
registration ( |
None
|
render_value(token)
¶
Format value_template with the resolved token.
MCPRegistry¶
pydantic_deep.mcp.MCPRegistry
¶
A mutable collection of MCP server configs with secret-aware building.
build_active(on_degraded=None)
¶
Build toolsets for every server that is enabled and authenticated.
Each is wrapped via :func:make_resilient so that a configured server
which turns out to be unreachable at runtime contributes no tools rather
than failing the entire agent run. on_degraded(name, reason) is
forwarded to each wrapper.
MCPProbeResult¶
pydantic_deep.mcp.MCPProbeResult
dataclass
¶
Outcome of a connection probe against an MCP server.
MCPNotInstalledError¶
pydantic_deep.mcp.MCPNotInstalledError
¶
Bases: ImportError
Raised when building an MCP server but the optional dependency is absent.