Skip to main content
Glama

MCP Auth Server

MCP Auth Step by Step

This repository demonstrates building an MCP (Model Context Protocol) server with HTTP transport and JWT authentication, progressing through iterative steps.

This repo is a companion to the in-depth, step-by-step blog posts on "MCP Authorization". See the following:

Part 4 (late addition to the series): MCP Authorization With Dynamic Client Registration

MCP Authorization Specification Requirements

The table below shows support for OAuth RFCs required by the MCP authorization specification across major identity providers.

RFC Requirements Summary:

  • PKCE: Proof Key for Code Exchange (OAuth 2.1 requirement)
  • RFC 8414: OAuth 2.0 Authorization Server Metadata
  • RFC 7591: OAuth 2.0 Dynamic Client Registration Protocol
  • RFC 8707: Resource Indicators for OAuth 2.0
Identity ProviderPKCERFC 8414RFC 7591RFC 8707
OktaYesYesYesN0
Auth0YesYesKindaNo
KeycloakYesYesYesNo
Ping FederateYesYesYesYes
ForgeRockYesYesYesKinda
Google OAuthYesNoNoNo
Microsoft EntraYesYesNoNo

Overview

The project shows how to build a secure MCP server with:

  • FastAPI-based HTTP transport
  • JWT token authentication
  • OAuth 2.0 metadata endpoints
  • Scope-based authorization
  • Role-based access control

Step-by-Step Progression

Step 1: Basic FastAPI Skeleton

  • File: http-transport-steps/src/mcp_http/step1.py
  • What it adds: Basic FastAPI application with health endpoint
  • Key features:
    • FastAPI server setup
    • Basic health check endpoint (/health)
    • Foundation for MCP HTTP transport

Step 2: Basic MCP Request Handling

  • File: http-transport-steps/src/mcp_http/step2.py
  • What it adds: MCP protocol request/response handling
  • Key features:
    • MCP request parsing and validation
    • Basic MCP response structure
    • /mcp endpoint for MCP protocol communication
    • JSON-RPC style request handling

Step 3: MCP Tools and Prompts Definitions

  • File: http-transport-steps/src/mcp_http/step3.py
  • What it adds: MCP tools and prompts without dispatching
  • Key features:
    • Tool definitions (echo, get_time)
    • Prompt definitions (greeting, help)
    • MCP protocol compliance for tools and prompts
    • No actual tool execution yet

Step 4: MCP Tools Dispatching

  • File: http-transport-steps/src/mcp_http/step4.py
  • What it adds: Actual tool execution and prompt handling
  • Key features:
    • Tool dispatching and execution
    • Prompt retrieval and handling
    • Working MCP server with functional tools
    • Error handling for invalid requests

Step 5: Basic JWT Infrastructure

  • File: http-transport-steps/src/mcp_http/step5.py
  • What it adds: JWT public key loading and JWKS endpoint
  • Key features:
    • Public key loading from file
    • JWKS (JSON Web Key Set) endpoint (/.well-known/jwks.json)
    • External token generation script (generate_token.py)
    • JWT infrastructure foundation

Step 6: JWT Token Validation

  • File: http-transport-steps/src/mcp_http/step6.py
  • What it adds: JWT authentication middleware and enforcement
  • Key features:
    • JWT token validation middleware
    • Authentication enforcement on /mcp endpoint
    • User context extraction from tokens
    • Proper error responses for invalid/missing tokens

Step 7: OAuth 2.0 Metadata Endpoints

  • File: http-transport-steps/src/mcp_http/step7.py
  • What it adds: OAuth 2.0 metadata for protected resource and authorization server
  • Key features:
    • /.well-known/oauth-protected-resource endpoint
    • /.well-known/oauth-authorization-server endpoint
    • Enhanced health endpoint with OAuth metadata
    • OAuth metadata in MCP responses

Step 8: Scope-Based Authorization

  • File: http-transport-steps/src/mcp_http/step8.py
  • What it adds: Permission checking and role-based access control
  • Key features:
    • check_permission method for scope validation
    • Role-based access control (admin, user, guest)
    • 403 Forbidden responses for insufficient permissions
    • Scope enforcement for MCP operations

Step 9: Enhanced MCP Integration (Planned)

  • What it will add: User context in responses and authenticated tools
  • Planned features:
    • User context in MCP response headers/metadata
    • Authenticated tools with user-aware behavior
    • Enhanced MCP protocol integration
    • Personalized responses based on user identity

JWT Token Structure

The JWT tokens include:

  • User ID: Unique identifier for the user
  • Scopes: Permissions (e.g., mcp:read, mcp:tools, mcp:prompts)
  • Roles: User roles (e.g., admin, user, guest)
  • Expiration: Token validity period

Testing

Each step includes a corresponding test script (test_stepX.sh) that validates:

  • Basic functionality
  • JWT authentication (steps 5+)
  • Authorization (steps 6+)
  • OAuth metadata (steps 7+)
  • Access control (steps 8+)

Usage

Prerequisites

  1. Install uv: https://docs.astral.sh/uv/getting-started/installation/
  2. Navigate to the http-transport-steps directory

Running Steps with uv

# Run any step using uv run uv run step1 uv run step2 uv run step3 # ... etc

Running Step 10 with Environment Configuration

Step 10 supports environment-based configuration for Keycloak and MCP server URLs. You can specify an env file (not .env) using the --env flag, or let it default to keycloak_direct.env.

Two example env files are provided:

  • keycloak_direct.env (for direct Keycloak access at localhost:8080)
  • keycloak_proxy.env (for proxy access at localhost:9090)

Example usage:

# Run step 10 with a specific env file (e.g., proxy) uv run step10 --env keycloak_proxy.env

If the env file or environment variables are missing, the server will fall back to sensible defaults (localhost:8080, etc).

Notes for running step11

  • you will need to run step10 mcp server
  • you will have to allow anonymous client registration:
  • add trusted hosts (check keycloak logs for the right IP)
  • for trusted host policy, you don't need matching on URI
  • allowable scopes for mcp, etc and aud mapper
  • then run the step11 client
uv run step11

To run with mcp-inspector

  • you'll need to run agentgateway with config.yaml
  • uv run step10 --env keycloak_proxy.env
  • run mcp-inspector UI (note, some of the auth stuff is broken, at the moment, use this: https://github.com/christian-posta/mcp-inspector/tree/ceposta-patches)
  • then follow the step by step auth flow

mcp scopes issue: https://github.com/modelcontextprotocol/inspector/issues/587

Token Generation

For steps 5-8 that require JWT authentication, you can generate tokens using the generate_token.py script:

uv run python generate_token.py --username alice --scopes mcp:read,mcp:tools uv run python generate_token.py --username bob --scopes mcp:read,mcp:prompts uv run python generate_token.py --username admin --scopes mcp:read,mcp:tools,mcp:prompts uv run python generate_token.py --username guest --scopes ""

Keycloak Token Generation

To quickly get a token for testing step9/keycloak:

curl -X POST "http://localhost:8080/realms/mcp-realm/protocol/openid-connect/token" \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "grant_type=password" \ -d "client_id=mcp-test-client" \ -d "username=mcp-admin" \ -d "password=admin123" \ -d "scope=openid profile email mcp:read mcp:tools mcp:prompts" | jq -r '.access_token'

The script will output a JWT token that can be used in the Authorization: Bearer <token> header for authenticated requests.

Dependencies

  • FastAPI
  • PyJWT
  • cryptography
  • uvicorn

The project uses uv for dependency management with pyproject.toml configuration.

Related MCP Servers

  • A
    security
    A
    license
    A
    quality
    A Model Context Protocol (MCP) server that provides JSON-RPC functionality through OpenRPC.
    Last updated -
    2
    7
    33
    JavaScript
    Apache 2.0
    • Apple
  • -
    security
    A
    license
    -
    quality
    This server implements the Model Context Protocol (MCP) to handle asynchronous tasks with real-time status tracking, robust error handling, and automatic resource management.
    Last updated -
    2
    1
    JavaScript
    MIT License
  • -
    security
    A
    license
    -
    quality
    A Model Context Protocol server that enables seamless execution of commands, Python code, web content fetching, and reusable task management with secure credentials handling.
    Last updated -
    2
    Python
    MIT License
    • Apple
  • -
    security
    F
    license
    -
    quality
    A server implementation of the Model Context Protocol (MCP) that provides REST API endpoints for managing and interacting with MCP resources.
    Last updated -
    Python

View all related MCP servers

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/christian-posta/mcp-auth-step-by-step'

If you have feedback or need assistance with the MCP directory API, please join our Discord server