MCP Authorization: CIMD, Issuer Binding, PKCE, and Step-Up
A remote MCP request is stateless, but its authorization is not anonymous. Bind every credential to the issuer that created it and every token to the resource that receives it.
Learning Objectives
- Discover authorization servers through protected-resource metadata.
- Prefer Client ID Metadata Documents over deprecated Dynamic Client Registration.
- Declare the correct
application_typewhen a DCR compatibility path is unavoidable. - Validate authorization response
issand isolate credentials by issuer. - Use PKCE, resource indicators, audience validation, and incremental scopes.
- Send authorized MCP 2026-07-28 requests without protocol sessions.
The Problem
A remote MCP server may read private records, write external systems, or trigger costly work. Authentication tells it who presented a credential. Authorization must also answer:
- Which authorization server issued the credential?
- Which MCP resource is the token for?
- Which client and redirect URI completed the flow?
- Which operations did the user approve?
- Does this exact request still fit that approval?
The 2026-07-28 authorization profile hardens client enrollment and issuer handling. It prefers Client ID Metadata Documents, deprecates Dynamic Client Registration, requires the right application_type on DCR, validates RFC 9207 issuer responses, and forbids credential reuse across issuers.
These rules complement the stateless core. They do not restore a core handshake or Mcp-Session-Id.
The Concept
Know the three roles
- MCP client: sends requests on behalf of a resource owner.
- MCP resource server: accepts the access token and serves the MCP endpoint.
- Authorization server: authenticates the resource owner, collects consent, and issues tokens.
The resource server and authorization server can be operated together, but keep their identifiers and validation responsibilities separate.
Authorization applies to HTTP
The MCP authorization specification applies to HTTP-based transports. A local stdio server runs under the process and operating-system trust boundary. Do not add a fake browser OAuth flow to stdio merely for symmetry.
For remote Streamable HTTP, send the bearer token in the Authorization header on every request. Never place it in the URL.
Start with protected-resource metadata
The resource server publishes RFC 9728 metadata:
{
"resource": "https://notes.example.com/mcp",
"authorization_servers": ["https://auth.example.com"],
"scopes_supported": ["notes:delete", "notes:read", "notes:write"]
}The client starts from the MCP resource URL, fetches this document, selects an advertised authorization server, and then fetches that server's OAuth or OpenID Connect metadata.
Preserve the resource path when constructing the RFC 9728 well-known URL. For the resource https://notes.example.com/mcpthis lesson uses https://notes.example.com/.well-known/oauth-protected-resource/mcp. Dropping the /mcp suffix can select metadata for a different protected resource on the same origin.
Do not guess the authorization server from a hostname. Do not follow an issuer discovered from an unvalidated error body. Keep a policy for which issuers the client is willing to trust.
Verify authorization server metadata
The metadata should expose endpoints and supported controls:
{
"issuer": "https://auth.example.com",
"authorization_endpoint": "https://auth.example.com/authorize",
"token_endpoint": "https://auth.example.com/token",
"code_challenge_methods_supported": ["S256"],
"authorization_response_iss_parameter_supported": true,
"client_id_metadata_document_supported": true
}Require S256 for PKCE. Record the exact issuer string. That exact value becomes the key for registration and token storage.
Follow the registration priority
Use pre-registered client information when the client already has an explicit relationship with the selected issuer. Otherwise prefer Client ID Metadata Documents when the authorization server advertises support. Use DCR only as the deprecated compatibility fallback, then prompt for client information if none of those mechanisms is available.
Prefer Client ID Metadata Documents
A Client ID Metadata Document gives the authorization server an HTTPS URL that is both the client identifier and the location of its metadata:
{
"client_id": "https://client.example.com/oauth/metadata.json",
"client_name": "Notes desktop client",
"application_type": "native",
"redirect_uris": ["http://127.0.0.1:8765/callback"],
"grant_types": ["authorization_code"],
"response_types": ["code"]
}The authorization server fetches and validates the document. The client_id must be an HTTPS URL with a path, and the value inside the document must equal that URL exactly. The required document fields are client_idclient_nameand redirect_uris. application_type appears in this example but is not a CIMD requirement. Its new mandatory use is specifically the DCR path.
Treat fetching the document as an SSRF-sensitive operation. Resolve and validate the destination, reject loopback, private, link-local, and otherwise disallowed addresses, re-check after redirects and DNS changes, limit redirects, bytes, and time, require JSON, and cache only according to validated HTTP cache controls. Treat client_name and other display fields as untrusted text.
CIMD removes the need to mint a fresh dynamic identifier for every first contact. It does not remove redirect URI validation, issuer policy, or user consent.
DCR is a compatibility path
Dynamic Client Registration remains available for older authorization servers, but it is deprecated for new MCP implementations.
When using DCR, declare application_type:
{
"client_name": "Notes desktop client",
"application_type": "native",
"redirect_uris": ["http://127.0.0.1:8765/callback"],
"grant_types": ["authorization_code"],
"response_types": ["code"]
}- Desktop, mobile, command-line, and loopback clients use
native. - Remotely hosted browser applications use
weband remote HTTPS redirects.
Omitting the field can default to web in an OpenID Connect registration implementation and make a legitimate loopback redirect fail.
Keep DCR code behind an explicit fallback decision. Do not silently fall back after an arbitrary CIMD validation failure. That could turn a security failure into a weaker enrollment path.
Bind credentials to the issuer
Store issuer-minted enrollment material under the exact issuer:
issuer_credentials[issuer] = pre_registered_or_dcr_client
tokens[(issuer, resource)] = access_tokenIf protected-resource discovery changes from https://auth-one.example to https://auth-two.examplere-evaluate trust. Never send the first issuer's client secret, DCR client id, registration access token, refresh token, or access token to the second. Pre-registered and DCR clients must use credentials issued for the new issuer.
A CIMD client id is different because it is a self-hosted HTTPS URL, not a credential minted by an authorization server. The same CIMD URL is portable: a new trusted issuer fetches and validates the document without DCR re-registration. Authorization responses and tokens are still validated and stored under the new issuer.
Authorization code with PKCE
The interactive flow is:
- Generate a high-entropy
code_verifier. - Derive the S256
code_challenge. - Send the authorization request with exact
client_idredirect_uriscopecode_challengeandresource. - Receive an authorization response containing
codeand, when provided,iss. - Validate
issagainst the exact recorded issuer before using any response field. - Exchange the code with
code_verifierthe same redirect URI, and the sameresource. - Store the resulting token under
(issuer, resource).
The resource parameter from RFC 8707 appears in both authorization and token requests. It identifies the canonical MCP server URI.
Validate iss exactly
RFC 9207 prevents an authorization response from one issuer being confused with a response from another.
When iss is present, compare it to the recorded issuer without case folding, trailing-slash changes, default-port removal, or percent-encoding normalization. On mismatch, do not act on the code or even display attacker-controlled error details from that response.
An authorization server that includes iss advertises authorization_response_iss_parameter_supported: true. Current clients still validate a present iss even when that advertisement is missing.
Validate audience at the MCP server
The resource server accepts only tokens issued for itself:
token.issuer == configured_authorization_server
token.audience == canonical_mcp_resourceInvalid, expired, wrong-issuer, or wrong-audience tokens receive 401. The MCP server must not accept or transit a token meant for another service.
Request the smallest current scope
Start with the scope needed now. If a later tool requires more, the server returns 403 with an authoritative scope challenge:
WWW-Authenticate: Bearer error="insufficient_scope",
scope="notes:delete",
resource_metadata="https://notes.example.com/.well-known/oauth-protected-resource/mcp"The client explains the new permission, obtains consent, performs a new authorization flow with the combined scope set, and retries the MCP request with a new JSON-RPC id.
Do not assume the challenged scope is a subset of scopes_supported. The challenge is authoritative for the current operation.
Authorization and the stateless MCP wire
An authorized tool call still carries the complete current request envelope:
POST /mcp
Authorization: Bearer <access-token>
MCP-Protocol-Version: 2026-07-28
Mcp-Method: tools/call
Mcp-Name: notes.delete{
"jsonrpc": "2.0",
"id": 12,
"method": "tools/call",
"params": {
"name": "notes.delete",
"arguments": {"id": "note-7"},
"_meta": {
"io.modelcontextprotocol/protocolVersion": "2026-07-28",
"io.modelcontextprotocol/clientCapabilities": {},
"io.modelcontextprotocol/clientInfo": {
"name": "oauth-lesson-client",
"version": "1.0.0"
}
}
}
}The token authorizes the principal. The request metadata negotiates protocol behavior. Neither substitutes for the other.
Validate the wire in a fixed order: JSON-RPC and metadata types, header and body equality, then protocol support. A routing or version-header mismatch returns HTTP 400 with -32020. If header and body agree on an unsupported version, return HTTP 400 with -32022 and data exactly {"supported":["2026-07-28"],"requested":"<actual>"}. An unknown method returns HTTP 404 with -32601.
Every request error, including 401 invalid token and 403 insufficient scope, is a JSON-RPC error envelope with the original request id. Structured recovery information belongs in optional error data; WWW-Authenticate remains an HTTP response header. A notification has no idso it receives no JSON-RPC body. An accepted HTTP notification returns 202 with an empty body.
The server implements server/discover and advertises tools, so it also implements the mandatory tools/list method. Its tool descriptors have stable names, descriptions, and object-root inputSchema values. The list is deterministic and returns resultTypeserver identity metadata, a bounded ttlMsand cacheScope. Discovery and a user-independent tool list can be available before authorization. Apply normal policy and private caching if either varies by principal.
No token passthrough
An MCP server must not forward the client's MCP access token to a downstream API. Obtain a separate downstream token with the right audience or use an explicit token-exchange design. Audience validation only works when services refuse tokens minted for someone else.
Refresh tokens
Refresh tokens are optional. When issued, store them confidentially and key them by issuer and resource. Do not assume they exist. Rotate them when the authorization server supports rotation and detect reuse of invalidated values.
Build It
code/main.py is an in-process protocol and authorization simulator. It implements protected-resource discovery, authorization server metadata, CIMD enrollment, version-gated DCR fallback, application type checks, PKCE, issuer validation, resource-bound tokens, scope step-up, server/discovertools/listand a stateless tool request.
The model receives parsed request bodies and routing headers. It is not a complete HTTP adapter and does not parse Content-Type or Accept. Connect it to Lesson 09's Streamable HTTP adapter, which requires Content-Type: application/json and an Accept value containing both application/json and text/event-stream.
Run it:
cd phases/13-tools-and-protocols/16-mcp-security-oauth-2-1
python3 code/main.py
python3 -m unittest discover code/tests -vThe output shows discovery first, CIMD enrollment, an ordinary read, two separate scope step-ups, and issuer-keyed credential storage.
Use It
Map the simulator objects to production components:
ResourceServer.protected_resource_metadatabecomes the RFC 9728 endpoint.AuthorizationServer.metadatabecomes RFC 8414 or OpenID Connect discovery.Client.enrollbecomes CIMD resolution plus an explicit DCR compatibility branch.- Issuer-minted client credentials and
tokens_by_issuer_resourcebecome encrypted records. A CIMD URL may remain portable while its authorization results remain issuer-bound. ResourceServer.handlebecomes middleware that validates current MCP headers, token, and tool scope before dispatch while keeping every request error in a matching JSON-RPC envelope.
Ship It
This lesson ships outputs/skill-oauth-scope-planner.md. It now designs enrollment priority, issuer-bound credential storage, application type, PKCE, resource indicators, scope challenges, and the current stateless request boundary.
Exercises
- Add refresh-token rotation and reject reuse of the previous refresh token.
- Add an issuer allowlist. On issuer change, reuse only a portable CIMD URL; refuse all prior issuer-minted credentials and tokens.
- Add an expiry to authorization codes and confirm a late exchange fails.
- Build a web client variant with a remote HTTPS redirect and compare its DCR metadata to the native client.
- Add a second resource under the same issuer. Confirm its access token cannot be used at the first resource.
Key Terms
| Term | Meaning |
|---|---|
| Protected-resource metadata | RFC 9728 document that identifies the resource and authorization servers |
| CIMD | HTTPS metadata document whose URL is the OAuth client identifier |
| DCR | Deprecated dynamic client enrollment retained for compatibility |
application_type | native or webused to validate redirect URI rules |
| PKCE | Verifier and S256 challenge that protect an intercepted authorization code |
iss | RFC 9207 authorization response issuer identifier |
| Resource indicator | RFC 8707 parameter that binds a token request to an MCP resource |
| Audience | Resource for which a token is valid |
| Step-up | New consent and token issuance for an additional current-operation scope |
| Issuer-bound credentials | Registration and token records isolated by exact authorization server issuer |
Further Reading
Check what you learned
6 questions. Answer each one to see why.
Which mechanism is preferred for new MCP OAuth client enrollment in 2026-07-28?
The full code
Every file for this lesson. Copy it, run it, then change it.
"""Phase 13 Lesson 16: MCP 2026-07-28 authorization simulator.
Companion to ../docs/en.md. Implements an in-process protocol model with
protected-resource discovery, CIMD-first enrollment, deprecated DCR fallback,
PKCE, issuer validation, resource-bound tokens, scope step-up, discovery, and
tools/list. Lesson 09 supplies the complete Streamable HTTP adapter.
"""
from __future__ import annotations
import base64
import binascii
import hashlib
import secrets
import threading
import time
from dataclasses import dataclass, field
from typing import Any
from urllib.parse import urlparse
PROTOCOL_VERSION = "2026-07-28"
PROTOCOL_META = "io.modelcontextprotocol/protocolVersion"
CLIENT_CAPABILITIES_META = "io.modelcontextprotocol/clientCapabilities"
CLIENT_INFO_META = "io.modelcontextprotocol/clientInfo"
SERVER_INFO_META = "io.modelcontextprotocol/serverInfo"
RESOURCE = "https://notes.example.com/mcp"
RESOURCE_METADATA_URI = "https://notes.example.com/.well-known/oauth-protected-resource/mcp"
ISSUER = "https://auth.example.com"
CLIENT_METADATA_URL = "https://client.example.com/oauth/metadata.json"
SERVER_INFO = {"name": "notes-server", "version": "2.0.0"}
BASE64_SENTINEL_PREFIX = "=?base64?"
BASE64_SENTINEL_SUFFIX = "?="
FORBIDDEN_CIMD_SECRET_FIELDS = {
"client_secret",
"client_secret_expires_at",
"private_key",
"private_key_jwk",
"private_key_pem",
}
PRIVATE_JWK_FIELDS = {"d", "p", "q", "dp", "dq", "qi", "oth", "k"}
TOOL_DESCRIPTORS = [
{
"name": "notes.create",
"description": "Create a note.",
"inputSchema": {
"type": "object",
"properties": {"title": {"type": "string"}},
"required": ["title"],
},
},
{
"name": "notes.delete",
"description": "Delete a note by identifier.",
"inputSchema": {
"type": "object",
"properties": {"id": {"type": "string"}},
"required": ["id"],
},
},
{
"name": "notes.list",
"description": "List notes visible to the principal.",
"inputSchema": {"type": "object", "properties": {}},
},
]
@dataclass(frozen=True)
class Token:
value: str
issuer: str
audience: str
subject: str
client_id: str
scopes: frozenset[str]
expires_at: float
@dataclass(frozen=True)
class ProtocolError(Exception):
code: int
message: str
data: dict[str, Any] | None = None
http_status: int = 400
headers: dict[str, str] | None = None
def pkce_pair() -> tuple[str, str]:
verifier = secrets.token_urlsafe(32)
digest = hashlib.sha256(verifier.encode()).digest()
challenge = base64.urlsafe_b64encode(digest).rstrip(b"=").decode()
return verifier, challenge
def request_meta() -> dict[str, Any]:
return {
PROTOCOL_META: PROTOCOL_VERSION,
CLIENT_CAPABILITIES_META: {},
CLIENT_INFO_META: {"name": "oauth-lesson-client", "version": "1.0.0"},
}
def encode_mcp_header_value(value: str) -> str:
is_safe = (
value.isascii()
and value == value.strip()
and all(0x20 <= ord(character) <= 0x7E for character in value)
and not (
value.startswith(BASE64_SENTINEL_PREFIX)
and value.endswith(BASE64_SENTINEL_SUFFIX)
)
)
if is_safe:
return value
payload = base64.b64encode(value.encode("utf-8")).decode("ascii")
return f"{BASE64_SENTINEL_PREFIX}{payload}{BASE64_SENTINEL_SUFFIX}"
def decode_mcp_header_value(value: Any) -> str:
if not isinstance(value, str):
raise ProtocolError(-32020, "Mcp-Name header is missing or malformed")
if value.startswith(BASE64_SENTINEL_PREFIX) and value.endswith(BASE64_SENTINEL_SUFFIX):
payload = value[len(BASE64_SENTINEL_PREFIX):-len(BASE64_SENTINEL_SUFFIX)]
try:
return base64.b64decode(payload, validate=True).decode("utf-8")
except (binascii.Error, UnicodeDecodeError, ValueError) as exc:
raise ProtocolError(-32020, "Mcp-Name header has invalid Base64 encoding") from exc
if (
not value.isascii()
or value != value.strip()
or any(not 0x20 <= ord(character) <= 0x7E for character in value)
):
raise ProtocolError(-32020, "Mcp-Name header is not safely encoded")
return value
def make_mcp_request(request_id: int, tool: str, arguments: dict[str, Any] | None = None):
params = {"name": tool, "arguments": dict(arguments or {}), "_meta": request_meta()}
body = {"jsonrpc": "2.0", "id": request_id, "method": "tools/call", "params": params}
headers = {
"MCP-Protocol-Version": PROTOCOL_VERSION,
"Mcp-Method": "tools/call",
"Mcp-Name": encode_mcp_header_value(tool),
}
return body, headers
def make_discover_request(request_id: int = 0):
body = {
"jsonrpc": "2.0",
"id": request_id,
"method": "server/discover",
"params": {"_meta": request_meta()},
}
headers = {
"MCP-Protocol-Version": PROTOCOL_VERSION,
"Mcp-Method": "server/discover",
}
return body, headers
def make_tools_list_request(request_id: int = 0):
body = {
"jsonrpc": "2.0",
"id": request_id,
"method": "tools/list",
"params": {"_meta": request_meta()},
}
headers = {
"MCP-Protocol-Version": PROTOCOL_VERSION,
"Mcp-Method": "tools/list",
}
return body, headers
@dataclass
class AuthorizationServer:
issuer: str = ISSUER
supports_cimd: bool = True
supports_dcr: bool = True
clients: dict[str, dict[str, Any]] = field(default_factory=dict)
pending_codes: dict[str, dict[str, Any]] = field(default_factory=dict)
_pending_codes_lock: threading.Lock = field(
default_factory=threading.Lock,
init=False,
repr=False,
)
def metadata(self) -> dict[str, Any]:
metadata = {
"issuer": self.issuer,
"authorization_endpoint": f"{self.issuer}/authorize",
"token_endpoint": f"{self.issuer}/token",
"code_challenge_methods_supported": ["S256"],
"authorization_response_iss_parameter_supported": True,
"client_id_metadata_document_supported": self.supports_cimd,
}
if self.supports_dcr:
metadata["registration_endpoint"] = f"{self.issuer}/register"
return metadata
@staticmethod
def _validate_application(metadata: dict[str, Any], *, require_application_type: bool) -> None:
application_type = metadata.get("application_type")
if require_application_type and application_type not in {"native", "web"}:
raise ValueError("application_type must be native or web")
if application_type is not None and application_type not in {"native", "web"}:
raise ValueError("application_type must be native or web")
redirect_uris = metadata.get("redirect_uris")
if not isinstance(redirect_uris, list) or not redirect_uris:
raise ValueError("redirect_uris is required")
parsed_redirects = []
for redirect_uri in redirect_uris:
if (
not isinstance(redirect_uri, str)
or not redirect_uri
or redirect_uri != redirect_uri.strip()
or any(character.isspace() for character in redirect_uri)
):
raise ValueError(
"redirect_uris entries must be non-empty absolute URIs without fragments"
)
try:
parsed = urlparse(redirect_uri)
hostname = parsed.hostname
except ValueError as exc:
raise ValueError(
"redirect_uris entries must be non-empty absolute URIs without fragments"
) from exc
if (
not parsed.scheme
or parsed.fragment
or (
parsed.scheme in {"http", "https"}
and (not parsed.netloc or hostname is None)
)
):
raise ValueError(
"redirect_uris entries must be non-empty absolute URIs without fragments"
)
parsed_redirects.append(parsed)
if application_type == "web":
for parsed in parsed_redirects:
if parsed.scheme != "https" or parsed.hostname in {"localhost", "127.0.0.1"}:
raise ValueError("web redirect URIs must use remote HTTPS")
def enroll_cimd(self, metadata_url: str, document: dict[str, Any]) -> str:
if not self.supports_cimd:
raise ValueError("CIMD is not supported")
parsed = urlparse(metadata_url)
if parsed.scheme != "https" or not parsed.netloc or parsed.path in {"", "/"}:
raise ValueError("CIMD client_id must be an HTTPS URL with a path")
if parsed.username is not None or parsed.password is not None:
raise ValueError("CIMD client_id must not contain userinfo")
if parsed.fragment:
raise ValueError("CIMD client_id must not contain a fragment")
if any(segment in {".", ".."} for segment in parsed.path.split("/")):
raise ValueError("CIMD client_id must not contain dot path segments")
if document.get("client_id") != metadata_url:
raise ValueError("CIMD client_id must equal its metadata URL")
if not isinstance(document.get("client_name"), str) or not document["client_name"]:
raise ValueError("client_name is required")
auth_method = document.get("token_endpoint_auth_method")
if auth_method is not None and not isinstance(auth_method, str):
raise ValueError("token_endpoint_auth_method must be a string")
if isinstance(auth_method, str) and auth_method.startswith("client_secret"):
raise ValueError("CIMD must not use shared-secret client authentication")
forbidden_fields = FORBIDDEN_CIMD_SECRET_FIELDS.intersection(document)
if forbidden_fields:
raise ValueError("CIMD must not contain client secrets or private keys")
jwks = document.get("jwks")
if isinstance(jwks, dict):
keys = jwks.get("keys", [])
if isinstance(keys, list) and any(
isinstance(key, dict) and PRIVATE_JWK_FIELDS.intersection(key)
for key in keys
):
raise ValueError("CIMD jwks must contain public keys only")
self._validate_application(document, require_application_type=False)
self.clients[metadata_url] = {**document, "enrollment": "cimd"}
return metadata_url
def dynamic_register(self, metadata: dict[str, Any]) -> str:
if not self.supports_dcr:
raise ValueError("DCR is not supported")
self._validate_application(metadata, require_application_type=True)
client_id = f"dcr_{secrets.token_hex(6)}"
self.clients[client_id] = {**metadata, "enrollment": "dcr-compatibility"}
return client_id
def authorize(
self,
*,
client_id: str,
redirect_uri: str,
subject: str,
scopes: set[str],
challenge: str,
resource: str,
) -> dict[str, str]:
client = self.clients.get(client_id)
if client is None or redirect_uri not in client["redirect_uris"]:
raise ValueError("unknown client or redirect URI")
code = f"code_{secrets.token_hex(8)}"
self.pending_codes[code] = {
"client_id": client_id,
"redirect_uri": redirect_uri,
"subject": subject,
"scopes": frozenset(scopes),
"challenge": challenge,
"resource": resource,
"expires_at": time.time() + 300,
}
return {"code": code, "iss": self.issuer}
def exchange(
self,
*,
code: str,
client_id: str,
verifier: str,
redirect_uri: str,
resource: str,
) -> Token:
with self._pending_codes_lock:
record = self.pending_codes.get(code)
if record is None:
raise ValueError("invalid authorization code")
if record["expires_at"] <= time.time():
self.pending_codes.pop(code, None)
raise ValueError("invalid authorization code")
if record["client_id"] != client_id:
raise ValueError("client_id mismatch")
if record["redirect_uri"] != redirect_uri:
raise ValueError("redirect_uri mismatch")
if record["resource"] != resource:
raise ValueError("resource mismatch")
challenge = base64.urlsafe_b64encode(
hashlib.sha256(verifier.encode()).digest()
).rstrip(b"=").decode()
if not secrets.compare_digest(challenge, record["challenge"]):
raise ValueError("PKCE mismatch")
self.pending_codes.pop(code)
return Token(
value=f"tok_{secrets.token_hex(12)}",
issuer=self.issuer,
audience=resource,
subject=record["subject"],
client_id=record["client_id"],
scopes=record["scopes"],
expires_at=time.time() + 3600,
)
@dataclass
class ResourceServer:
resource: str = RESOURCE
issuer: str = ISSUER
scopes: dict[str, str] = field(default_factory=lambda: {
"notes.list": "notes:read",
"notes.create": "notes:write",
"notes.delete": "notes:delete",
})
def protected_resource_metadata(self) -> dict[str, Any]:
return {
"resource": self.resource,
"authorization_servers": [self.issuer],
"scopes_supported": sorted(set(self.scopes.values())),
}
@staticmethod
def _success(request_id: Any, result: dict[str, Any]) -> dict[str, Any]:
payload = dict(result)
payload.setdefault("resultType", "complete")
payload.setdefault("_meta", {})[SERVER_INFO_META] = SERVER_INFO
return {"jsonrpc": "2.0", "id": request_id, "result": payload}
@staticmethod
def _error(request_id: Any, error: ProtocolError) -> dict[str, Any]:
payload: dict[str, Any] = {"code": error.code, "message": error.message}
if error.data is not None:
payload["data"] = error.data
return {"jsonrpc": "2.0", "id": request_id, "error": payload}
@staticmethod
def _validate_wire(body: dict[str, Any], headers: dict[str, str]) -> dict[str, Any]:
if body.get("jsonrpc") != "2.0":
raise ProtocolError(-32600, "Invalid Request")
method = body.get("method")
params = body.get("params")
if not isinstance(method, str) or not isinstance(params, dict):
raise ProtocolError(-32600, "Invalid Request")
meta = params.get("_meta") if isinstance(params, dict) else None
if not isinstance(meta, dict):
raise ProtocolError(-32602, "params._meta must be an object")
requested_version = meta.get(PROTOCOL_META)
if not isinstance(requested_version, str):
raise ProtocolError(-32602, "protocolVersion must be a string")
if not isinstance(meta.get(CLIENT_CAPABILITIES_META), dict):
raise ProtocolError(-32602, "clientCapabilities must be an object")
if headers.get("MCP-Protocol-Version") != requested_version:
raise ProtocolError(-32020, "MCP-Protocol-Version header mismatch")
if headers.get("Mcp-Method") != method:
raise ProtocolError(-32020, "Mcp-Method header mismatch")
if method in {"tools/call", "resources/read", "prompts/get"}:
expected_name = params.get("name") or params.get("uri")
supplied_name = decode_mcp_header_value(headers.get("Mcp-Name"))
if supplied_name != expected_name:
raise ProtocolError(-32020, "Mcp-Name header mismatch")
if requested_version != PROTOCOL_VERSION:
raise ProtocolError(
-32022,
"Unsupported protocol version",
{"supported": [PROTOCOL_VERSION], "requested": requested_version},
)
return params
def discover(
self,
body: dict[str, Any],
headers: dict[str, str],
*,
http_method: str = "POST",
) -> tuple[int, dict[str, Any] | None, dict[str, str]]:
return self.handle(body, headers, None, http_method=http_method)
def call(
self,
body: dict[str, Any],
headers: dict[str, str],
token: Token | None,
*,
http_method: str = "POST",
) -> tuple[int, dict[str, Any] | None, dict[str, str]]:
return self.handle(body, headers, token, http_method=http_method)
def handle(
self,
body: dict[str, Any],
headers: dict[str, str],
token: Token | None = None,
*,
http_method: str = "POST",
) -> tuple[int, dict[str, Any] | None, dict[str, str]]:
is_notification = "id" not in body
try:
if http_method != "POST":
raise ProtocolError(-32600, "HTTP method not allowed", http_status=405)
params = self._validate_wire(body, headers)
method = body["method"]
if method == "server/discover":
result = {
"supportedVersions": [PROTOCOL_VERSION],
"capabilities": {"tools": {"listChanged": False}},
"ttlMs": 60_000,
"cacheScope": "public",
}
elif method == "tools/list":
result = {
"tools": sorted(TOOL_DESCRIPTORS, key=lambda tool: tool["name"]),
"ttlMs": 60_000,
"cacheScope": "public",
}
elif method == "tools/call":
challenge_base = f'Bearer resource_metadata="{RESOURCE_METADATA_URI}"'
challenge_headers = {"WWW-Authenticate": challenge_base}
if token is None or token.expires_at < time.time():
raise ProtocolError(
-32001,
"Unauthorized",
{"reason": "invalid_token"},
401,
challenge_headers,
)
if token.issuer != self.issuer or token.audience != self.resource:
raise ProtocolError(
-32001,
"Unauthorized",
{"reason": "invalid_token"},
401,
challenge_headers,
)
required = self.scopes.get(params.get("name"))
if required is None:
raise ProtocolError(
-32602,
"Unknown tool",
{"name": params.get("name")},
404,
)
if required not in token.scopes:
challenge = f'{challenge_base}, error="insufficient_scope", scope="{required}"'
raise ProtocolError(
-32003,
"Insufficient scope",
{"requiredScope": required},
403,
{"WWW-Authenticate": challenge},
)
result = {
"content": [{
"type": "text",
"text": f"{params['name']} allowed for {token.subject}",
}],
"isError": False,
}
else:
raise ProtocolError(-32601, "Method not found", http_status=404)
if is_notification:
return 202, None, {}
return 200, self._success(body["id"], result), {}
except ProtocolError as error:
if is_notification:
return error.http_status, None, dict(error.headers or {})
return (
error.http_status,
self._error(body.get("id"), error),
dict(error.headers or {}),
)
class Client:
def __init__(self, *, subject: str = "alice", application_type: str = "native") -> None:
self.subject = subject
self.application_type = application_type
self.redirect_uri = "http://127.0.0.1:8765/callback" if application_type == "native" else "https://client.example.com/callback"
self.client_ids_by_issuer: dict[str, str] = {}
self.tokens_by_issuer_resource: dict[tuple[str, str], Token] = {}
self.next_request_id = 1
def _client_document(self) -> dict[str, Any]:
return {
"client_id": CLIENT_METADATA_URL,
"client_name": "OAuth lesson client",
"application_type": self.application_type,
"redirect_uris": [self.redirect_uri],
"grant_types": ["authorization_code"],
"response_types": ["code"],
}
def enroll(self, auth: AuthorizationServer) -> str:
metadata = auth.metadata()
if metadata.get("issuer") != auth.issuer:
raise ValueError("authorization metadata issuer mismatch")
if metadata.get("client_id_metadata_document_supported"):
client_id = auth.enroll_cimd(CLIENT_METADATA_URL, self._client_document())
elif metadata.get("registration_endpoint"):
fallback = self._client_document()
fallback.pop("client_id")
client_id = auth.dynamic_register(fallback)
else:
raise ValueError("authorization server offers no supported client enrollment")
self.client_ids_by_issuer[auth.issuer] = client_id
return client_id
def authorize(self, auth: AuthorizationServer, resource: str, scopes: set[str]) -> Token:
client_id = self.client_ids_by_issuer.get(auth.issuer)
if client_id is None:
client_id = self.enroll(auth)
verifier, challenge = pkce_pair()
response = auth.authorize(
client_id=client_id,
redirect_uri=self.redirect_uri,
subject=self.subject,
scopes=scopes,
challenge=challenge,
resource=resource,
)
if response.get("iss") != auth.issuer:
raise ValueError("authorization response issuer mismatch")
token = auth.exchange(
code=response["code"],
client_id=client_id,
verifier=verifier,
redirect_uri=self.redirect_uri,
resource=resource,
)
self.tokens_by_issuer_resource[(auth.issuer, resource)] = token
return token
def call_with_step_up(
self,
tool: str,
server: ResourceServer,
auth: AuthorizationServer,
) -> tuple[int, dict[str, Any] | None, dict[str, str]]:
if server.issuer != auth.issuer:
raise ValueError("protected resource selected a different issuer")
key = (auth.issuer, server.resource)
token = self.tokens_by_issuer_resource.get(key)
if token is None:
token = self.authorize(auth, server.resource, {"notes:read"})
body, headers = make_mcp_request(self.next_request_id, tool)
self.next_request_id += 1
status, response, response_headers = server.call(body, headers, token)
if status == 403 and response is not None and response.get("error", {}).get("code") == -32003:
required = response_headers["WWW-Authenticate"].split('scope="', 1)[1].split('"', 1)[0]
token = self.authorize(auth, server.resource, set(token.scopes) | {required})
body, headers = make_mcp_request(self.next_request_id, tool)
self.next_request_id += 1
status, response, response_headers = server.call(body, headers, token)
return status, response, response_headers
def demo() -> None:
auth = AuthorizationServer()
server = ResourceServer()
client = Client()
discover_body, discover_headers = make_discover_request()
_, discovery, _ = server.discover(discover_body, discover_headers)
print("server discovery:", discovery["result"] if discovery else None)
list_body, list_headers = make_tools_list_request()
_, listing, _ = server.handle(list_body, list_headers)
print("tools:", [tool["name"] for tool in listing["result"]["tools"]] if listing else None)
print("protected resource metadata:", server.protected_resource_metadata())
print("CIMD client_id:", client.enroll(auth))
for tool in ("notes.list", "notes.create", "notes.delete"):
status, response, _ = client.call_with_step_up(tool, server, auth)
print(tool, status, response.get("result", {}).get("content") if response else None)
print("effective client ids by issuer:", sorted(client.client_ids_by_issuer))
if __name__ == "__main__":
demo()