MCP Forge Python - Production-Ready MCP Server Template

A comprehensive, production-ready MCP (Model Context Protocol) server template built with Python, featuring OAuth 2.0 authentication, JWT validation, and seamless deployment options for developers building AI-powered applications.

Key Features of MCP Forge Python

MCP Protocol Implementation

• Built with the mcp[cli] Python library for full MCP protocol support
• Comprehensive tools, resources, and prompts implementation
• Configurable server initialization with name and version

Communication Transports

• Stdio Transport: Standard input/output communication for local AI clients like Claude Desktop
• HTTP Streaming: Streamable HTTP for real-time web-based communication

Built-in MCP Tools

The server includes several MCP tools registered via the router:

• hello_world: Personalized greeting functionality (requires tool:user scope in HTTP mode)
• whoami: JWT-based user information exposure from the JWT payload

Security & Middleware

• Access Logging: Configurable request logging with header redaction
• JWT Validation: Dual strategies for token authentication
  • Local validation using JWKS URI and CEL expressions
  • External proxy delegation (Istio-compatible)

OAuth 2.0 Integration (RFC 8414 & RFC 9728)

• OAuth Authorization Server: OpenID Connect configuration proxy
• Protected Resource Metadata: Complete OAuth resource discovery endpoints
• OAuth Flows: Built-in login and callback endpoints for authorization code flow

Flexible Configuration

• TOML-based configuration system with dedicated sections for:
  • Server settings (name, version, transport)
  • Middleware configuration (logging, JWT)
  • OAuth integration (authorization servers, protected resources)
  • Auth settings for OAuth flows (client credentials, redirect URIs)

Production-Ready Deployment

• Complete Docker containerization with Dockerfile
• Kubernetes Helm chart for cloud deployment
• Integration guides for Keycloak, Istio, and Hashrouter

Getting Started with MCP Forge Python

System Requirements

• Python Version: 3.11 or higher
• Package Manager: uv for dependency management (installation guide)
• Optional: just for simplified command execution (installation guide)

Installation & Setup

# Install project dependencies
uv sync

# Install the MCP server package
uv pip install -e .

# Start HTTP server with streaming support
uv run http

# Alternative: Run stdio server for local AI clients
uv run stdio

# Or use just commands
just run      # HTTP server
just run-stdio # Stdio server

Project Architecture

src/mcp_app/
├── main.py          # Application entry point and FastAPI setup
├── config.py        # Pydantic configuration models
├── context.py       # JWT context management for secure claim sharing
├── handlers/        # OAuth endpoints handlers (RFC 8414 & RFC 9728)
├── middlewares/     # Custom middlewares (JWT, access logs, CORS)
└── tools/           # MCP tools and registration router

Core Components

• main.py: Initializes FastMCP server, FastAPI app, middlewares, and OAuth endpoints
• config.py: TOML-based configuration with Pydantic models
• context.py: Async-safe JWT context sharing between middlewares and tools
• handlers/: OAuth authorization server and protected resource metadata endpoints
• middlewares/: JWT validation, access logging, and CORS handling
• tools/: MCP tool implementations and registration system

Documentation & Resources

• Development Guide - Complete guide for using this template
• Contributing Guidelines - How to contribute to the project
• Configuration Reference - Detailed configuration options
• Release Notes - Version history and changelog

License

This project is licensed under the Unlicense - a public domain dedication. See LICENSE.txt for the full license text.