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 documentation, then maps them to MCP tool format with preserved validation rules and type information. This enables LLMs to understand and invoke FastAPI endpoints as native tools.

Translates MCP tool calls directly to FastAPI endpoint invocations using ASGI transport, bypassing HTTP overhead by communicating directly with the FastAPI application instance. The Tool Execution layer (fastapi_mcp/execute.py) reconstructs HTTP requests from MCP tool parameters, invokes the FastAPI ASGI app directly, and streams responses back without serialization/deserialization cycles. This approach preserves middleware execution, dependency injection, and authentication context.

Propagates HTTP error responses and status codes from FastAPI endpoints back to MCP clients, preserving error semantics and enabling LLMs to understand and handle failures appropriately. When a FastAPI endpoint returns an error status code (4xx, 5xx), the MCP server translates this into an MCP error response with the original status code and error message. This enables LLMs to distinguish between different error types (validation errors, authentication failures, server errors) and respond accordingly.

Manages the complete MCP server lifecycle including initialization, transport mounting, and shutdown. The FastApiMCP class orchestrates server startup, mounts the selected transport (HTTP or SSE), and handles graceful shutdown. The server can be mounted on a FastAPI application (same-app deployment) or run as a standalone process (separate-app deployment). Lifecycle management includes resource cleanup, session termination, and proper transport shutdown.

Preserves FastAPI's dependency injection system and middleware execution when invoking endpoints through MCP tools. The ASGI-based tool execution layer reconstructs the full FastAPI request context, enabling dependencies (database connections, authentication, logging) and middleware (CORS, compression, custom handlers) to execute normally. This ensures that MCP-invoked endpoints behave identically to HTTP-invoked endpoints, with all side effects and validations intact.

Manages persistent HTTP client sessions across multiple MCP tool calls using the FastApiHttpSessionManager class, enabling stateful interactions with FastAPI endpoints. Maintains session state (cookies, headers, authentication tokens) across tool invocations, allowing LLMs to authenticate once and execute multiple authenticated requests without re-authentication. Sessions are keyed by client identifier and support concurrent multi-turn conversations.

Filters FastAPI endpoints before converting them to MCP tools using configurable inclusion/exclusion patterns, path prefixes, and tag-based filtering. Allows developers to selectively expose only specific endpoints as MCP tools while keeping internal or sensitive endpoints hidden. Filtering is applied during schema conversion, preventing unwanted endpoints from appearing in the MCP tool registry.

Forwards authentication credentials from MCP clients to FastAPI endpoints using configurable authentication strategies including OAuth 2.1, JWT tokens, API keys, and custom authentication handlers. The AuthConfig class encapsulates authentication metadata, and the HTTPRequestInfo type carries request context (headers, cookies) through the tool execution pipeline. Supports both bearer token forwarding and header-based authentication, preserving the original FastAPI authentication requirements.

Supports both modern HTTP transport (recommended for streaming responses) and legacy Server-Sent Events (SSE) transport for backward compatibility with older MCP clients. HTTP transport enables streaming tool responses and supports concurrent requests, while SSE transport provides fallback compatibility for clients that don't support HTTP. Transport selection is configurable at initialization, and both transports share the same tool execution pipeline.

Supports two deployment architectures: same-app deployment (MCP server and FastAPI app in the same process using ASGI transport for zero-copy execution) and separate-app deployment (MCP server in separate process using HTTP transport to invoke remote FastAPI endpoints). Deployment pattern is selected at initialization and determines whether ASGI or HTTP transport is used. This flexibility enables both high-performance co-located deployments and distributed architectures.

Allows customization of how FastAPI endpoint responses are mapped to MCP tool output schemas through response schema configuration. Developers can define custom output schemas, specify which response fields to expose, and control how complex response types are serialized for MCP clients. This enables fine-grained control over what information is returned to LLMs while hiding internal response details.

Supports dynamic route registration where FastAPI endpoints can be added or modified at runtime, and the MCP server can discover and expose these new endpoints without restart. The library introspects the FastAPI OpenAPI schema at initialization and can be reconfigured to pick up new routes. This enables applications with dynamic endpoint generation (e.g., plugin systems, multi-tenant APIs) to automatically expose new endpoints as MCP tools.

Provides configurable HTTP client settings for separate-app deployments, including custom headers, timeout configuration, SSL/TLS settings, and proxy support. The HTTP client configuration is applied to all requests made from the MCP server to the remote FastAPI endpoint, enabling fine-grained control over connection behavior, security, and performance characteristics.