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: * [Understanding MCP Authorization, Step by Step, Part One](https://blog.christianposta.com/understanding-mcp-authorization-step-by-step/) * [Understanding MCP Authorization, Step by Step, Part Two](https://blog.christianposta.com/understanding-mcp-authorization-step-by-step-part-two/) * [Understanding MCP Authorization, Step by Step, Part Three](https://blog.christianposta.com/understanding-mcp-authorization-step-by-step-part-three/) Part 4 (late addition to the series): [MCP Authorization With Dynamic Client Registration](https://blog.christianposta.com/understanding-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 Provider | PKCE | RFC 8414 | RFC 7591 | RFC 8707 | |-------------------|------|----------|----------|----------| | **Okta** | Yes | Yes | Yes | N0 | | **Auth0** | Yes | Yes | Kinda | No | | **Keycloak** | Yes | Yes | Yes | No | | **Ping Federate** | Yes | Yes | Yes | Yes | | **ForgeRock** | Yes | Yes | Yes | Kinda | | **Google OAuth** | Yes | No | No | No | | **Microsoft Entra** | Yes | Yes | No | No | ## 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 ```bash # 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:** ```bash # 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:read, etc and aud mapper * then run the step11 client ```bash 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: ```bash 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: ```bash# Get token for admin user (full access) 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.