Skip to main content
Pre-release

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 mcp SDK 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)

Source distribution for agent-did-mcp 1.0.0rc5
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)

Table of built distributions (wheels) for agent-did-mcp 1.0.0rc5
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

A 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.

Release history Release notifications | RSS feed

This release
Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page