Provides HTTP transport layer for the MCP server, enabling request handling, endpoint management, and server infrastructure
Serves as the core implementation language for all MCP server functionality including tool definitions, prompt handling, and authentication
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 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 communicationJSON-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
endpointUser 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
endpointEnhanced 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 validationRole-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
Install
uv
: https://docs.astral.sh/uv/getting-started/installation/Navigate to the
http-transport-steps
directory
Running Steps with uv
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 atlocalhost:8080
)keycloak_proxy.env
(for proxy access atlocalhost:9090
)
Example usage:
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
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:
Keycloak Token Generation
To quickly get a token for testing step9/keycloak:
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.
This server cannot be installed
remote-capable server
The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.
A Model Context Protocol (MCP) server with HTTP transport that implements JWT authentication, allowing secure tool execution and prompt handling with role-based access control.
- MCP Authorization Specification Requirements
- Overview
- Step-by-Step Progression
- Step 1: Basic FastAPI Skeleton
- Step 2: Basic MCP Request Handling
- Step 3: MCP Tools and Prompts Definitions
- Step 4: MCP Tools Dispatching
- Step 5: Basic JWT Infrastructure
- Step 6: JWT Token Validation
- Step 7: OAuth 2.0 Metadata Endpoints
- Step 8: Scope-Based Authorization
- Step 9: Enhanced MCP Integration (Planned)
- JWT Token Structure
- Testing
- Usage
- Dependencies
Related MCP Servers
- AsecurityAlicenseAqualityA Model Context Protocol (MCP) server that provides JSON-RPC functionality through OpenRPC.Last updated -2440Apache 2.0
- -securityAlicense-qualityA 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 -2MIT License
- -securityFlicense-qualityA server implementation of the Model Context Protocol (MCP) that provides REST API endpoints for managing and interacting with MCP resources.Last updated -
- -securityFlicense-qualityA comprehensive Model Context Protocol (MCP) server implementing the latest MCP specification with tools, resources, prompts, and enhanced sampling capabilities that features HackerNews and GitHub API integrations for AI-powered analysis.Last updated -333