mcpo

Dynamically discovers MCP tool definitions from connected MCP servers (via stdio, SSE, or HTTP streaming), introspects their JSON schemas, and automatically generates Pydantic models and FastAPI endpoint definitions without manual code generation or configuration. Uses a schema processing pipeline that parses MCP tool metadata, validates against JSON Schema specifications, and creates type-safe HTTP request/response models that map directly to MCP tool parameters and return types.

Abstracts three distinct MCP communication protocols (stdio, Server-Sent Events, and HTTP streaming) behind a unified connection interface, allowing a single MCPO instance to proxy multiple MCP servers regardless of their transport mechanism. Each protocol has specialized connection management: stdio spawns local processes and manages bidirectional pipes, SSE establishes persistent HTTP connections with event streaming, and streamable-http uses chunked HTTP responses. The architecture uses protocol-specific handlers that normalize all three into a common MCP message format.

Provides Dockerfile and Docker Compose templates for containerizing MCPO with MCP servers, enabling reproducible deployments across environments. Docker images include Python 3.11+, FastAPI, and all MCPO dependencies. Compose files define multi-container setups with MCPO proxy and dependent MCP servers (e.g., database-backed tools). Environment variables in Compose files map to MCPO configuration, supporting secrets management via .env files or Docker secrets.

Validates MCP tool JSON schemas against the JSON Schema specification and generates Pydantic BaseModel classes that enforce type safety and validation at runtime. Validation includes checking for required fields, type constraints, enum values, and nested object schemas. Generated Pydantic models are used for request body parsing and response serialization, ensuring that invalid requests are rejected with 422 Unprocessable Entity before reaching MCP servers. Validation errors include detailed field-level error messages.

Manages concurrent connections to multiple MCP servers using connection pools that reuse established connections across requests, reducing latency and resource overhead. Each MCP server has its own connection pool with configurable size limits and timeout settings. Pools handle connection lifecycle (creation, reuse, cleanup) transparently, including graceful shutdown during server restart or hot reload. Pools support both long-lived connections (stdio, SSE) and request-scoped connections (HTTP).

Creates isolated FastAPI sub-applications for each configured MCP server and mounts them at unique URL prefixes (e.g., /server-name/tools/*), enabling multi-server deployments with independent endpoint namespacing and OpenAPI documentation per server. Each sub-application has its own lifespan context manager for connection lifecycle management, allowing concurrent MCP server connections without cross-contamination. The main application aggregates all sub-app OpenAPI schemas into a unified documentation interface.

Implements pluggable authentication middleware that validates incoming HTTP requests against API keys or OAuth 2.0 tokens before forwarding to MCP servers. Supports header-based API key validation (e.g., Authorization: Bearer <key>) and OAuth 2.0 token introspection against configurable identity providers. Authentication is enforced at the FastAPI middleware layer, intercepting all requests before they reach endpoint handlers. Failed authentication returns 401 Unauthorized; successful validation injects user context into request scope for downstream logging and audit.

Automatically forwards HTTP headers from client requests to upstream MCP servers (e.g., custom authorization headers, tracing headers) and applies configurable CORS policies to allow cross-origin requests from specified domains. Header forwarding is selective—sensitive headers (e.g., Host, Connection) are filtered to prevent protocol violations, while custom headers are passed through. CORS policies are defined per-server or globally, controlling which origins, methods, and headers are allowed in cross-origin requests.

Reads YAML/JSON configuration files (compatible with Claude Desktop MCP server format) that define multiple MCP servers with their transport protocols, authentication credentials, and endpoint settings. Configuration schema supports nested server definitions with per-server overrides for CORS, header forwarding, and authentication. The configuration loader validates schema at startup and provides clear error messages for misconfiguration. Supports environment variable interpolation in configuration values (e.g., ${MCP_SERVER_URL}).

Monitors configuration files for changes and automatically reloads MCP server connections without restarting the entire MCPO process. Uses filesystem watchers (e.g., watchfiles library) to detect configuration file modifications, validates the new configuration, gracefully closes old MCP connections, and establishes new ones. During reload, in-flight requests are allowed to complete before connection teardown. Failed reloads log errors but do not crash the server—the previous configuration remains active.

Processes responses from MCP tool invocations, normalizes error formats into standard HTTP status codes (e.g., MCP tool errors → 400 Bad Request, timeouts → 504 Gateway Timeout), and transforms MCP response objects into JSON-serializable HTTP response bodies. Handles both successful tool responses and error cases, including partial failures in multi-step tool chains. Includes retry logic with exponential backoff for transient MCP server failures (e.g., connection timeouts).

Automatically generates OpenAPI 3.0 schemas for all exposed MCP tools and serves interactive Swagger UI and ReDoc documentation at /docs and /redoc endpoints. Documentation includes tool descriptions, parameter schemas with validation rules, example requests/responses, and authentication requirements. Each MCP server's tools are documented in separate sections with clear namespacing. Documentation is regenerated at startup and during hot reload, always reflecting current MCP tool definitions.

Provides a Typer-based CLI for starting MCPO with flexible argument passing: single MCP server mode (mcpo --command 'mcp-server-binary' --args 'arg1 arg2') or multi-server mode (mcpo --config config.yaml). CLI arguments map directly to MCP server configuration, supporting protocol selection (--server-type stdio|sse|streamable-http), custom headers (--headers 'key:value'), and authentication settings. Help text is auto-generated from Typer annotations, providing discoverable CLI options.