fastapi_mcp

Automatically introspects a FastAPI application's OpenAPI schema and converts endpoint definitions into MCP tool schemas without information loss. Uses the convert_openapi_to_mcp_tools() function to parse OpenAPI 3.0 specifications, extracting parameter definitions, request/response schemas, and endpoint documentation, then maps them to MCP tool definitions with preserved type information and validation rules. This enables LLMs to understand and invoke FastAPI endpoints as structured tools with full schema awareness.

Executes MCP tool calls by translating them directly to FastAPI endpoint invocations via ASGI transport, bypassing HTTP overhead entirely. The Tool Execution layer (fastapi_mcp/execute.py) intercepts MCP tool calls, reconstructs request context (headers, cookies, authentication), and invokes the FastAPI application's ASGI interface directly, allowing the endpoint to execute with full access to FastAPI's dependency injection, middleware, and validation stack. This zero-copy architecture eliminates serialization/deserialization cycles and network latency.

Translates FastAPI errors and exceptions into MCP-compliant error responses, ensuring that endpoint failures are properly communicated to MCP clients. The error handling layer catches FastAPI exceptions (validation errors, HTTP exceptions, unhandled errors), transforms them into MCP error format, and provides detailed error information for debugging. This includes handling of HTTP status codes, error messages, and stack traces, with configurable verbosity for production vs development environments.

Handles MCP protocol version negotiation and feature compatibility with different MCP client implementations (Claude, Cursor, Windsurf, etc.). The server advertises supported MCP protocol versions and capabilities, allowing clients to negotiate compatible protocol features. This enables the same MCP server to work with multiple client implementations that may support different MCP protocol versions or optional features, with graceful degradation for unsupported features.

Manages persistent HTTP sessions across multiple MCP tool calls using the FastApiHttpSessionManager class, enabling stateful interactions where context (authentication, cookies, request state) persists across tool invocations. The session manager maintains client-specific state, forwards authentication headers and cookies to FastAPI endpoints, and handles session lifecycle (creation, reuse, cleanup). This enables LLM agents to maintain authenticated sessions across multiple tool calls without re-authenticating for each invocation.

Supports both modern HTTP transport (recommended for streaming and performance) and legacy Server-Sent Events (SSE) transport for backward compatibility with older MCP clients. The transport layer (fastapi_mcp/transport/) abstracts the underlying protocol, allowing the same MCP server to serve both HTTP and SSE clients simultaneously. HTTP transport enables efficient streaming of large responses and supports modern MCP client features, while SSE transport maintains compatibility with clients that only support the legacy protocol.

Provides declarative authentication configuration (AuthConfig type) that integrates with FastAPI's security schemes, supporting OAuth 2.1, JWT, and custom authentication handlers. The library forwards authentication context from MCP clients to FastAPI endpoints, allowing endpoints to access authenticated user information via FastAPI's Depends() injection. Authentication is configured at the MCP server level and automatically applied to all exposed endpoints, with support for custom auth validators and token forwarding.

Allows selective exposure of FastAPI endpoints as MCP tools through filtering configuration, enabling developers to exclude sensitive endpoints, internal utilities, or endpoints not suitable for LLM invocation. Filtering can be applied by endpoint path, method, tags, or custom predicates, giving fine-grained control over which endpoints become MCP tools. This prevents accidental exposure of administrative endpoints or endpoints with side effects unsuitable for autonomous LLM execution.

Allows customization of how FastAPI endpoint responses are formatted and presented to MCP clients through response schema configuration. Developers can define custom response schemas, transform endpoint outputs, or customize error formatting to match MCP expectations. This enables adaptation of FastAPI responses (which may be optimized for HTTP clients) to MCP tool output requirements, including handling of streaming responses, large payloads, and error conditions.

Supports two deployment architectures: same-app deployment where the MCP server and FastAPI application run in the same Python process (using ASGI transport for zero-copy execution), and separate-app deployment where the MCP server runs in a separate process and communicates with FastAPI via HTTP. The deployment pattern is transparent to the MCP client — both patterns expose the same MCP interface. This flexibility enables optimization for different deployment environments (single-process for latency, separate-process for isolation).

Supports dynamic registration of FastAPI routes at runtime, enabling MCP servers to discover and expose newly added endpoints without restart. The library can re-introspect the FastAPI OpenAPI schema at runtime to detect new endpoints, allowing for dynamic API expansion. This is useful for applications that add routes programmatically or for systems where endpoints are registered by plugins or extensions after server initialization.

Provides configurable HTTP client settings for separate-app deployments where the MCP server communicates with FastAPI via HTTP. Configuration includes connection pooling, timeout settings, SSL/TLS verification, proxy support, and custom headers. The HTTP client is optimized for tool execution (connection reuse, keepalive) and supports both synchronous and asynchronous request patterns. This enables tuning of network behavior for different deployment environments (cloud, on-premise, edge).