MCP Server Auth Template

mcp-server-auth-template

*Leia em português*

A production-oriented OAuth 2.1 resource-server reference for remote MCP: Microsoft Entra ID and

generic OIDC, exact token/resource validation, fail-closed authorization, progressive scope

challenges, stateless MCP 2026-07-28, and metadata-only OpenTelemetry evidence.

Use this repository when the hard part is not "how do I expose an MCP tool?" but how do I expose it without weakening identity, authorization, transport, and observability boundaries. The server pairs with mcp-client-auth-template for an executable end-to-end reference using synthetic identities and no production credentials.

What this repository proves

The paired executable path validates real resource-server behavior rather than configuration claims:

• ✅ RFC 9728 Protected Resource Metadata is published by the resource server
• ✅ RFC 8707 resource binding becomes an exact JWT audience boundary
• ✅ issuer, signature, expiry, algorithm/key compatibility and caller type fail closed
• ✅ delegated scopes and Entra application roles remain distinct authorization concepts
• ✅ 403 insufficient_scope is returned before dispatch for progressive authorization
• ✅ wrong-audience tokens are rejected with 401, with an explicit token-resource policy that does not depend on MCP SDK defaults
• ✅ tools/list is filtered per principal and carries only bounded private cache hints
• ✅ protected tools stay hidden from anonymous catalog discovery
• ✅ MCP 2026-07-28 stays stateless and does not mint Mcp-Session-Id
• ✅ generic OIDC and Microsoft Entra ID share one application boundary without provider leakage
• ✅ W3C trace context reaches the server while OAuth/MCP sensitive values stay out of telemetry
• ✅ release artifacts, container evidence, SBOMs and provenance are validated by executable gates

For a requirement-by-requirement view of the paired OAuth/MCP behavior, including explicit evidence gaps and discussion topics for the MCP Authorization Interest Group / Tool Scopes Working Group, see the Authorization Implementer Report.

Architecture

flowchart LR

Client["MCP client"] -->|"OAuth 2.1 / OIDC"| AS["Authorization server Entra ID or generic OIDC"] Client -->|"MCP 2026-07-28 resource-bound bearer"| Admission["Transport admission"] Admission --> AuthN["Token verification"] AuthN --> AuthZ["Tool authorization"] AuthZ --> Tools["MCP tools"] Server["This resource server"] --- Admission

Server -->|"OIDC discovery + cached JWKS"| AS Server -.->|"W3C trace context + OTLP"| Collector["OpenTelemetry Collector"] Collector --> Tempo["Tempo"] Tempo --> Grafana["Grafana"]

The authorization server owns login, consent, client registration and token issuance. This repository owns the protected resource: transport admission, metadata publication, access-token verification, request-scoped principal construction, tool authorization and dispatch.

For layer boundaries and the detailed authorization sequence, see Architecture.

5-minute verification

The companion client owns the executable cross-repository reference flow. With both repositories cloned as siblings, verify this server directly from source:

cd ../mcp-client-auth-template

./scripts/run_reference_demo.sh \ --server-root ../mcp-server-auth-template

The flow starts the real server from this checkout plus a deterministic local OIDC provider and proves CIMD-first Authorization Code + PKCE, authenticated whoami, bounded scope step-up, wrong-audience rejection and stateless MCP behavior.

For the observable published-image proof:

cd ../mcp-client-auth-template

./scripts/run_observability_demo.sh --keep

The observable flow verifies one distributed trace across client and server, positive Collector receipt, Tempo retrieval, Grafana provisioning and telemetry privacy assertions.

See Verification guide for the exact evidence boundary.

Visual proof

The terminal proof below is captured from the source-level paired reference flow:

The trace screenshots are captured from a successful observable run and focus on mcp-server-auth-template spans:

Authentication profiles

Set MCP_SERVER_AUTH_PROVIDER=entra or generic to switch adapters. The example whoami tool returns the verified caller identity; health requires the additional mcp:tools:health scope and demonstrates a pre-dispatch 403 insufficient_scope challenge.

Quick start

Prerequisites: Python 3.13 or 3.14 and uv.

git clone https://github.com/brunovicco/mcp-server-auth-template.git

cd mcp-server-auth-template cp .env.example .env uv sync --frozen --all-groups uv run uvicorn mcp_server_auth_template.entrypoints.mcp_server:create_app --factory --reload

Configure either the Entra or generic-OIDC block in .env, then point an MCP client at http://localhost:8000/mcp.

For production-style execution:

uv run python -m mcp_server_auth_template.entrypoints.serve

See Production operations before exposing the service outside loopback.

Official MCP Registry

The server is published in the Official MCP Registry as:

io.github.brunovicco/mcp-server-auth-template@0.7.0

server.json describes the public GHCR image as an OCI package using the real streamable-http transport; it does not claim a hosted remotes endpoint. Publication is gated by the secure release pipeline and a dedicated Registry workflow that validates the immutable image, ownership metadata, and persisted Registry responses before publication.

See Official MCP Registry and the Authorization Implementer Report.

Security properties

The implementation is deliberately fail closed:

• exact issuer and audience validation, bounded clock checks, algorithm/key compatibility and cached JWKS refresh;
• an explicit validate_token_resource=False policy: provider audiences (Entra API client ID, api:// identifiers) are enforced by the token verifier, never by SDK URL string equality (ADR-0027);
• principal-dependent discovery results are never shareable across authorization contexts (ADR-0028);
• hardened discovery/JWKS egress against unsafe schemes, redirects, compression, oversized bodies, private/reserved destinations, mixed DNS answers and DNS rebinding;
• Host, Origin, header, envelope, body-size and concurrency admission before authentication and tool dispatch;
• delegated and application identities remain distinct; extension negotiation never grants authorization by itself;
• bearer tokens and decoded claims remain request-local and are never logged or persisted;
• tracing excludes credentials, arbitrary headers and URLs, MCP arguments/results, bodies, baggage and exception text.

This is a transparent reference implementation, not a security certification. Read Privacy and data handling and the architecture decisions under docs/adr/ before adapting the boundary.

MCP 2026-07-28

Baseline: MCP specification 2026-07-28 and MCP Python SDK >=2.2,<3.

The paired templates exercise the modern stateless profile as executable behavior:

• server/discover and per-request _meta carry protocol version, client identity and capabilities without the legacy initialize / initialized handshake;
• modern requests use MCP-Protocol-Version, Mcp-Method and Mcp-Name;
• responses do not mint Mcp-Session-Id;
• Protected Resource Metadata drives authorization-server discovery;
• RFC 8707 resource binds the access token audience exactly;
• server/discover and tools/list carry SEP-2549 cache hints (ttlMs=30000, cacheScope=private);
• runtime 403 insufficient_scope preserves prior grants and permits only one bounded replay of the undispatched operation;
• machine-to-machine access is opt-in through io.modelcontextprotocol/oauth-client-credentials.

See Compatibility and the companion client's cross-repository E2E evidence.

Observability

a2a-otel-kit continues W3C trace context at the MCP ASGI boundary. Export remains network-silent unless A2A_OTEL_ENABLED=true and a complete OTLP traces endpoint are configured. Spans are metadata-only and sit inside hardened HTTP admission but outside authentication and tool dispatch.

See LLM and application observability.

Engineering evidence

• deterministic quality gate covering lint, format, strict Mypy, architecture, tests/coverage, Bandit, dependency audit, supply-chain controls, governance and vendored contract validation;
• SHA-pinned GitHub Actions with read-only permissions by default and isolated release authorities;
• CycloneDX source/runtime inventories, complete vulnerability evidence and fail-closed exception policy;
• allowlisted byte-reproducible Python release artifacts with SHA-256 manifests and GitHub build provenance;
• policy-approved GHCR publication with immutable digest, provenance and SBOM attestations;
• Python 3.13/3.14 against MCP SDK 2.2.0 and latest compatible 2.x, with MCP SDK deprecation warnings promoted to test failures so MCP 3 breakage surfaces early;
• offline JWT fixtures using local keys and synthetic identities;
• ADRs documenting security, protocol, operations, compatibility, observability and supply-chain decisions.

Demo vs production

| Loopback/local reference networking | TLS-protected servic