Module●Since v0.1
mcp_auth
OAuth login flow and token storage for MCP servers.
Note: mcp.shared.auth.OAuthToken is a pydantic model whose default
repr includes the access and refresh token strings verbatim. Never
log one via %r, str(), f-string interpolation, or
logger.exception/exc_info on an exception that wraps one — the
tokens will land in stdout, log files, and error-reporting
pipelines. Pass only structural facts ("refreshed token for
server X") rather than the token itself.
Attributes
Functions
functionfunctionfunctionfunctionfunctionfunctionfunction
resolve_mcp_server_env
Resolve ${VAR} references in one MCP server's supported fields.
Interpolates the command, url, args, env, and headers
fields (see _interpolate_env for the reference syntax); every other
field is copied through verbatim. The input is not mutated.
resolve_headers
Resolve environment-variable references in MCP header values.
This compatibility wrapper preserves the original public helper while delegating interpolation and validation to the shared MCP config resolver.
build_oauth_provider
Construct an OAuthClientProvider for an MCP server.
format_login_failure
Return a token-safe single-line summary of an OAuth-login exception.
OAuth handshakes commonly surface as ExceptionGroup (anyio task
groups) or as MCP-SDK errors whose args/repr may include an
OAuthToken. Never call str()/repr() on the raw exception for
display or logging — instead, prefer a known-safe nested
MCPReauthRequiredError message, fall back to the messages of our
own loopback-related exception types, and degrade to a class-name
chain for anything else.
find_reauth_required
Find an MCPReauthRequiredError anywhere inside exc's tree.
Walks exceptions (for ExceptionGroup), then __cause__ and
__context__, tracking visited nodes to terminate on cyclic chains.
find_oauth_challenge
Return the resource_metadata URL of a 401 OAuth challenge in exc.
Per the MCP authorization spec (RFC 9728), a server requiring OAuth
answers an unauthenticated request with HTTP 401 plus a Bearer
WWW-Authenticate challenge pointing at its protected-resource metadata.
The MCP client surfaces that as an httpx.HTTPStatusError. Walks
exceptions (for ExceptionGroup), then __cause__/__context__,
tracking visited nodes to terminate on cyclic chains.
login
Drive OAuth login for server_name, persisting tokens on success.
Classes
classclassclassclass
OAuthInteraction
User-facing OAuth interaction surface shared by CLI and TUI.
McpServerSpec
Parsed MCP server config entry.
All keys are optional at the type level because mcpServers entries
are validated shape-first by _validate_server_config rather than by
the type system. This TypedDict documents the accepted shape for
readers and static checkers — validate the fields at use sites before
relying on them.
FileTokenStorage
File-backed TokenStorage under ~/.deepagents/.state/mcp-tokens/.
MCPReauthRequiredError
Raised when an MCP server needs interactive re-authentication.