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
• ✅ 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 

... [View full README on GitHub](https://github.com/brunovicco/mcp-server-auth-template#readme)