# MCP Server Auth Template

> MCP Server Auth Template is an open-source MCP server for security. Reference OAuth 2.1 resource server for remote MCP with Entra ID or generic OIDC. It runs as a hosted remote server, so there is nothing to install locally.

- **Kind:** MCP server
- **Pricing:** Open source
- **Platforms:** API, self-hosted, CLI
- **Repository:** https://github.com/brunovicco/mcp-server-auth-template
- **MCP Registry name:** io.github.brunovicco/mcp-server-auth-template
- **Categories:** [security](https://ai-powered.com/categories/security)
- **Listing updated:** 2026-11-18

## About

The README frames this as a starting point for the authorization layer of a remote MCP server, rather than for the tools themselves. It covers token validation against exact issuer and audience rules, fail-closed behaviour, and per-principal filtering of tool listings, using Microsoft Entra ID or any generic OIDC provider selected by an environment variable.

The repository ships a small example server with a whoami tool and a health tool that demonstrates a scope step-up challenge. It runs as a Streamable HTTP service, published as a GHCR container image and listed in the Official MCP Registry. Metadata-only OpenTelemetry tracing is included, with sensitive OAuth and MCP values kept out of telemetry.

The README positions it for developers who need to expose MCP tools without weakening identity and authorization boundaries. It is a reference implementation rather than a hosted identity service, and it expects teams to add TLS, secret management and provider registration before production use.

## Features

- **Entra and OIDC adapters:** Switches between Microsoft Entra ID and generic OIDC authorization servers through a single provider setting.
- **Exact token validation:** Checks issuer, signature, expiry, algorithm and audience, and rejects wrong-audience tokens with a 401.
- **Progressive scope challenges:** Returns a 403 insufficient_scope before dispatch when a tool needs a scope the caller lacks.
- **Protected resource metadata:** Publishes RFC 9728 metadata so clients can discover the authorization server.
- **Per-principal tool listing:** Filters tools/list by caller and keeps protected tools hidden from anonymous discovery.
- **Metadata-only tracing:** Emits OpenTelemetry spans carrying W3C trace context while excluding credentials and MCP payloads.

## Good for

- Adding OAuth 2.1 protection to a remote MCP server before exposing it beyond localhost
- Requiring Entra ID delegated scopes for MCP tools used by enterprise staff
- Enforcing per-tool scope step-up for sensitive operations in an MCP server
- Checking a team's MCP authorization design against a working reference implementation

## Install

### Claude Code (Terminal)

```sh
claude mcp add mcp-server-auth-template --env MCP_SERVER_RESOURCE_SERVER_URL='<MCP_SERVER_RESOURCE_SERVER_URL>' --env MCP_SERVER_AUTH_PROVIDER='<MCP_SERVER_AUTH_PROVIDER>' -- docker run -i --rm -e MCP_SERVER_RESOURCE_SERVER_URL -e MCP_SERVER_AUTH_PROVIDER ghcr.io/brunovicco/mcp-server-auth-template:v0.7.0
```

### Claude Desktop (claude_desktop_config.json)

```json
{
  "mcpServers": {
    "mcp-server-auth-template": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "MCP_SERVER_RESOURCE_SERVER_URL",
        "-e",
        "MCP_SERVER_AUTH_PROVIDER",
        "ghcr.io/brunovicco/mcp-server-auth-template:v0.7.0"
      ],
      "env": {
        "MCP_SERVER_RESOURCE_SERVER_URL": "<MCP_SERVER_RESOURCE_SERVER_URL>",
        "MCP_SERVER_AUTH_PROVIDER": "<MCP_SERVER_AUTH_PROVIDER>"
      }
    }
  }
}
```

### Cursor (~/.cursor/mcp.json)

```json
{
  "mcpServers": {
    "mcp-server-auth-template": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "MCP_SERVER_RESOURCE_SERVER_URL",
        "-e",
        "MCP_SERVER_AUTH_PROVIDER",
        "ghcr.io/brunovicco/mcp-server-auth-template:v0.7.0"
      ],
      "env": {
        "MCP_SERVER_RESOURCE_SERVER_URL": "<MCP_SERVER_RESOURCE_SERVER_URL>",
        "MCP_SERVER_AUTH_PROVIDER": "<MCP_SERVER_AUTH_PROVIDER>"
      }
    }
  }
}
```

### VS Code (.vscode/mcp.json)

```json
{
  "servers": {
    "mcp-server-auth-template": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "MCP_SERVER_RESOURCE_SERVER_URL",
        "-e",
        "MCP_SERVER_AUTH_PROVIDER",
        "ghcr.io/brunovicco/mcp-server-auth-template:v0.7.0"
      ],
      "env": {
        "MCP_SERVER_RESOURCE_SERVER_URL": "<MCP_SERVER_RESOURCE_SERVER_URL>",
        "MCP_SERVER_AUTH_PROVIDER": "<MCP_SERVER_AUTH_PROVIDER>"
      }
    }
  }
}
```

### Windsurf (~/.codeium/windsurf/mcp_config.json)

```json
{
  "mcpServers": {
    "mcp-server-auth-template": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "MCP_SERVER_RESOURCE_SERVER_URL",
        "-e",
        "MCP_SERVER_AUTH_PROVIDER",
        "ghcr.io/brunovicco/mcp-server-auth-template:v0.7.0"
      ],
      "env": {
        "MCP_SERVER_RESOURCE_SERVER_URL": "<MCP_SERVER_RESOURCE_SERVER_URL>",
        "MCP_SERVER_AUTH_PROVIDER": "<MCP_SERVER_AUTH_PROVIDER>"
      }
    }
  }
}
```

### Other clients (your client's MCP settings (most use this shape))

```json
{
  "mcpServers": {
    "mcp-server-auth-template": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "MCP_SERVER_RESOURCE_SERVER_URL",
        "-e",
        "MCP_SERVER_AUTH_PROVIDER",
        "ghcr.io/brunovicco/mcp-server-auth-template:v0.7.0"
      ],
      "env": {
        "MCP_SERVER_RESOURCE_SERVER_URL": "<MCP_SERVER_RESOURCE_SERVER_URL>",
        "MCP_SERVER_AUTH_PROVIDER": "<MCP_SERVER_AUTH_PROVIDER>"
      }
    }
  }
}
```

## Tools

- `whoami`: Returns the verified caller identity.
- `health`: Requires the mcp:tools:health scope and demonstrates a 403 insufficient_scope challenge.

## FAQ

### Which authorization providers are supported?

The README describes Microsoft Entra ID and generic OIDC, selected with the MCP_SERVER_AUTH_PROVIDER setting.

### Does it ship production-ready tools?

No. The README says the example whoami and health tools are reference tools and that domain tools need their own authorization policies.

### How is the server run?

The README gives a uv-based quick start with uvicorn, a production entrypoint, and a published GHCR container image tagged v0.7.0.

### Is MCP Server Auth Template free?

Yes. MCP Server Auth Template is open source, so you can use and self-host it for free.

### How do I add MCP Server Auth Template to Claude Code?

Run this command in your terminal: claude mcp add mcp-server-auth-template --env MCP_SERVER_RESOURCE_SERVER_URL='<MCP_SERVER_RESOURCE_SERVER_URL>' --env MCP_SERVER_AUTH_PROVIDER='<MCP_SERVER_AUTH_PROVIDER>' -- docker run -i --rm -e MCP_SERVER_RESOURCE_SERVER_URL -e MCP_SERVER_AUTH_PROVIDER ghcr.io/brunovicco/mcp-server-auth-template:v0.7.0

### What are the best alternatives to MCP Server Auth Template?

The closest alternatives to MCP Server Auth Template are mcp-agent-template, Security Mcp, MCP OAuth client-interop conformance, Toolmesh and Tempr MCP Connector.

## Where this comes from

- Description: written from the project's README and its MCP Registry entry.
- Install steps: from the official MCP Registry entry.

## Alternatives

- [mcp-agent-template](https://ai-powered.com/mcp/mcp-agent-template): mcp-agent-template is an open-source MCP server for security.
- [Security Mcp](https://ai-powered.com/mcp/security-mcp-2): Security Mcp is a freemium MCP server for security.
- [MCP OAuth client-interop conformance](https://ai-powered.com/mcp/mcp-oauth-client-interop-conformance): MCP OAuth client-interop conformance is an MCP server for developer tools.
- [Toolmesh](https://ai-powered.com/mcp/toolmesh): Toolmesh is an MCP server for developer tools.
- [Tempr MCP Connector](https://ai-powered.com/mcp/tempr-mcp-connector): Tempr MCP Connector is an MCP server for developer tools.
- [Speakeasy Platform MCP](https://ai-powered.com/mcp/speakeasy-platform-mcp): Speakeasy Platform MCP is a paid MCP server for security.

---
Source: https://ai-powered.com/mcp/mcp-server-auth-template
