This release is a pre-release and may not be stable for production use.
Agent-DID × Model Context Protocol (MCP) Integration
Design: ADR-008 (D-12c, D-12d)
Agent-DID for MCP clients and servers that use the Streamable HTTP transport, built on the official mcp Python SDK (2.x). An agent authenticates to an MCP authorization server with a JWT client assertion signed by its DID key, and can sign every MCP request so the server learns which agent DID sent it.
This package works alongside MCP authorization (OAuth 2.1), not instead of it. It is aligned with the MCP authorization specification and its OAuth Client Credentials extension; it is not verified against an MCP conformance suite.
What it provides
| Piece | Side | What it does |
|---|---|---|
create_agent_did_oauth_provider(...) |
client | The mcp SDK's PrivateKeyJWTOAuthProvider (client credentials, private_key_jwt, RFC 7523) with a fresh DID client assertion per token request (agent_did_sdk.create_client_assertion) |
agent_did_assertion_provider(...) |
client | The assertion_provider callback alone, for your own provider setup |
AgentDidMcpAuth |
client | An httpx2.Auth that signs each request to the MCP server's origin with an Agent-DID HTTP Message Signature (RFC-001 §6.5), optionally with a capability (§6.7), after an inner auth (the OAuth provider) has added its token. Requests to other origins (the authorization server) are not signed |
AgentDidSignatureMiddleware |
server | An ASGI middleware for any app (for example MCPServer.streamable_http_app()): verifies the signature, or the capability invocation, of each request under protected_paths and answers 401 (403 for capability_required, 413 for body_too_large) with the reason |
get_agent_did_principal(ctx) |
server | In a tool handler: the verified AgentDidPrincipal (did, key_id, controllers, capability_id, allowed_action…) |
client_metadata_routes(...) |
client's web host | Starlette routes that serve a Client ID Metadata Document (CIMD) and a JWKS built from the DID document |
Installation
Requires Python 3.11+ (the mcp 2.x SDK depends on httpx2, which needs 3.11).
cd sdk-python && python -m pip install -e ".[dev]"
cd ../integrations/mcp && python -m pip install -e ".[dev]"
Server: verify the calling agent
from mcp.server.mcpserver import Context, MCPServer
from agent_did_mcp import AgentDidSignatureMiddleware, get_agent_did_principal
server = MCPServer("files")
@server.tool()
def whoami(ctx: Context) -> str:
principal = get_agent_did_principal(ctx)
return principal.did if principal else "anonymous"
app = AgentDidSignatureMiddleware(
server.streamable_http_app(),
agent_identity=identity, # an AgentIdentity whose client resolves DIDs
public_base_url="https://mcp.example.com", # the origin clients sign for (behind a proxy)
allowed_dids=["did:webvh:…:agents:caller"], # or allowed_controllers=[...]
)
A valid signature proves which DID sent the request, not what it may do: restrict senders with allowed_dids / allowed_controllers, or require a capability (root_controllers={"https://mcp.example.com/mcp": [owner_did]}, require_capability=True). The middleware reads at most max_body_bytes (1 MiB) of each body to check Content-Digest. Bearer tokens are still checked by the MCP server's own authorization.
Client: OAuth token plus signed requests
import httpx2
from mcp.client.session import ClientSession
from mcp.client.streamable_http import streamable_http_client
from agent_did_mcp import AgentDidMcpAuth, create_agent_did_oauth_provider
oauth = create_agent_did_oauth_provider(
server_url="https://mcp.example.com/mcp",
client_id="https://agent.example.com/oauth/client.json", # CIMD URL, or a pre-registered id
issuer="https://auth.example.com", # the authorization server's issuer
verification_method_id=f"{did}#key-1", # an `authentication` key
agent_private_key=private_key_hex, # or signer=<KMS / HSM AgentSigner>
storage=token_storage,
)
auth = AgentDidMcpAuth(
agent_identity=identity,
server_url="https://mcp.example.com/mcp",
agent_did=did,
verification_method_id=f"{did}#key-1", # an `assertionMethod` key
agent_private_key=private_key_hex,
inner=oauth,
)
async with httpx2.AsyncClient(auth=auth) as http_client:
async with streamable_http_client("https://mcp.example.com/mcp", http_client=http_client) as streams:
async with ClientSession(streams[0], streams[1]) as session:
await session.initialize()
await session.call_tool("whoami", {})
The authorization server must know the client's keys. With CIMD it fetches the client_id URL: serve it with client_metadata_routes(client_id=..., client_name=..., did_document=lambda: runtime.document, jwks_path="/oauth/jwks.json"), and serve it again after a key rotation (authorization servers cache it). An authorization server that knows Agent-DID can instead check the assertion against the DID document with AgentDidClient.verify_client_assertion.
With a capability, pass capability= (a capability whose controller is the agent DID) and a capabilityInvocation key as verification_method_id.
Example
python -m examples.mcp_signed_tool_call
A real mcp client calls a tool on a real MCPServer in process; the tool answers with the caller's verified DID.
Limits
- Streamable HTTP only: stdio has no HTTP request to sign.
- Python only; a TypeScript MCP integration is planned after 1.0 (ADR-008).
- The middleware verifies requests; it does not sign responses.
- No claim of conformance with the MCP specification: the tests run the official
mcpSDK client and server in process.
Tests
python -m pytest tests -q # from integrations/mcp
npm run test:mcp # from the repository root
Metadata
Release files for agent-did-mcp 1.0.0rc5
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| agent_did_mcp-1.0.0rc5.tar.gz | 14.6 kB | With provenance | Details for agent_did_mcp-1.0.0rc5.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| agent_did_mcp-1.0.0rc5-py3-none-any.whl | Python 3 | none | any | Details for agent_did_mcp-1.0.0rc5-py3-none-any.whl |
Total release size: 25.9 kB
Release files / agent_did_mcp-1.0.0rc5.tar.gz
| Download URL | agent_did_mcp-1.0.0rc5.tar.gz |
|---|---|
| Size | 14.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
1b9758169f08363175170c52aa631ff6a8ba63cc0c77be467a625f3228ac85da
|
|
BLAKE2b-256 checksum How to use checksums |
7866fca639cbcafdd4fdc7af7493677ec48bc1b3e7418cf63aa7438538658827
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.
Transparency logRelease files / agent_did_mcp-1.0.0rc5-py3-none-any.whl
| Download URL | agent_did_mcp-1.0.0rc5-py3-none-any.whl |
|---|---|
| Size | 11.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
e1b7700600f4618edbec51c952c9888c7fe8dfa1b823f6390d69a53901d4e8e4
|
|
BLAKE2b-256 checksum How to use checksums |
547b324a37b4de29a7f1bc7e2f29b059729245d5610254c703a83718741d6901
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.
Transparency logSecurity for agent-did-mcp 1.0.0rc5
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for agent_did_mcp-1.0.0rc5.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.