MCP Server Auth Template

mcp-server-auth-template

[quality] [compatibility] [release] [python] [license]

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<br/>Entra ID or generic OIDC"]    Client -->|"MCP 2026-07-28<br/>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:

[Server reference demo]

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

[Server distributed trace]

[Server distributed trace detail]

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.gitcd mcp-server-auth-templatecp .env.example .envuv sync --frozen --all-groupsuv 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/[email protected]

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

The reference settings prove boundaries; they are not production defaults.

Repository structure

src/                    resource-server implementationtests/                  unit, contract and security evidencescripts/                quality, governance and release automationdocs/                   architecture, operations, privacy and securityexamples/                deployment/reference configuration.github/workflows/      CI, compatibility and release workflows

Local editor and coding-agent state is intentionally excluded from the public repository.

Documentation

Testing and quality

uv lock --checkuv sync --frozen --all-groupsuv run pytestuv run python scripts/quality_gate.py

The quality gate is the definition of done. It covers lint, format, architecture, strict typing, tests/coverage, Bandit, dependency audit, supply-chain controls, governance and vendored contract validation.

Scope and production adoption

This repository is a reference template, not a hosted identity service. A concrete deployment must still provide TLS termination, immutable image publishing, secret delivery, provider-specific registration, network policy, capacity planning, monitoring ownership and live IdP validation. Checked-in .invalid and all-zero values are placeholders and fail production preflight.

License

MIT