mcp-server-auth-template

# mcp-server-auth-template

[![quality](https://github.com/brunovicco/mcp-server-auth-template/actions/workflows/quality.yml/badge.svg)](https://github.com/brunovicco/mcp-server-auth-template/actions/workflows/quality.yml)
[![compatibility](https://github.com/brunovicco/mcp-server-auth-template/actions/workflows/compatibility.yml/badge.svg)](https://github.com/brunovicco/mcp-server-auth-template/actions/workflows/compatibility.yml)
[![release](https://img.shields.io/github/v/release/brunovicco/mcp-server-auth-template)](https://github.com/brunovicco/mcp-server-auth-template/releases)
![python](https://img.shields.io/badge/python-3.13%20%7C%203.14-blue.svg)
[![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

*[Leia em português](README.pt-BR.md)*

> 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`](https://github.com/brunovicco/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](docs/AUTHORIZATION_IMPLEMENTER_REPORT.md).

## Architecture

```mermaid
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](docs/ARCHITECTURE.md).

## 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:

```bash
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:

```bash
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](docs/VERIFICATION.md) for the exact evidence boundary.

### Visual proof

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

![Server reference demo](docs/assets/server-reference-demo.gif)

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

![Server distributed trace](docs/assets/server-observability-trace.png)

![Server distributed trace detail](docs/assets/server-observability-trace-detail.png)

## Authentication profiles

| Profile | Intended use | Key behavior |
| --- | --- | --- |
| Entra delegated | Interactive enterprise users | Validates `scp`, tenant/application identifiers, issuer, audience and subject |
| Entra application | Provider-specific app-only deployments | Requires explicit `idtyp=app`; keeps `roles` separate from delegated scopes |
| Generic OIDC delegated | Standards-based interactive clients | Validates issuer/audience/signature/expiry and OAuth scopes |
| Generic OIDC client credentials | Unattended services in the deterministic pair profile | Accepts pre-registered machine tokens and progressive OAuth scopes |

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`](https://docs.astral.sh/uv/getting-started/installation/).

```bash
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`.

| Endpoint | Purpose | Authentication |
| --- | --- | --- |
| `/mcp` | MCP Streamable HTTP | Bearer token |
| `/.well-known/oauth-protected-resource` | Authorization-server discovery metadata | Public |
| `/livez` | Process liveness | Public, minimal response |
| `/readyz` | MCP lifespan readiness | Public, minimal response |

For production-style execution:

```bash
uv run python -m mcp_server_auth_template.entrypoints.serve
```

See [Production operations](docs/OPERATIONS.md) 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](docs/REGISTRY.md) and the
[Authorization Implementer Report](docs/AUTHORIZATION_IMPLEMENTER_REPORT.md).

## 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](docs/adr/0027-explicit-token-resource-validation.md));
- principal-dependent discovery results are never shareable across authorization contexts
  ([ADR-0028](docs/adr/0028-mcp-cache-hint-security-policy.md));
- 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](docs/PRIVACY.md) and the architecture decisions under
[`docs/adr/`](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