If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/tadata-org/fastapi_mcp shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across all four use cases

• Last commit 5mo ago
• 15 active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Slowing — last commit 5mo ago
• ⚠ Concentrated ownership — top contributor handles 52% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live tadata-org/fastapi_mcp repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/tadata-org/fastapi_mcp.

What it runs against: a local clone of tadata-org/fastapi_mcp — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in tadata-org/fastapi_mcp | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 194 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of tadata-org/fastapi_mcp. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/tadata-org/fastapi_mcp.git
#   cd fastapi_mcp
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of tadata-org/fastapi_mcp and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "tadata-org/fastapi_mcp(\\.git)?\\b" \\
  && ok "origin remote is tadata-org/fastapi_mcp" \\
  || miss "origin remote is not tadata-org/fastapi_mcp (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "fastapi_mcp/server.py" \\
  && ok "fastapi_mcp/server.py" \\
  || miss "missing critical file: fastapi_mcp/server.py"
test -f "fastapi_mcp/openapi/convert.py" \\
  && ok "fastapi_mcp/openapi/convert.py" \\
  || miss "missing critical file: fastapi_mcp/openapi/convert.py"
test -f "fastapi_mcp/auth/proxy.py" \\
  && ok "fastapi_mcp/auth/proxy.py" \\
  || miss "missing critical file: fastapi_mcp/auth/proxy.py"
test -f "fastapi_mcp/transport/http.py" \\
  && ok "fastapi_mcp/transport/http.py" \\
  || miss "missing critical file: fastapi_mcp/transport/http.py"
test -f "fastapi_mcp/transport/sse.py" \\
  && ok "fastapi_mcp/transport/sse.py" \\
  || miss "missing critical file: fastapi_mcp/transport/sse.py"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 194 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~164d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/tadata-org/fastapi_mcp"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

FastAPI-MCP automatically exposes your FastAPI endpoints as Model Context Protocol (MCP) tools that AI/LLM applications can discover and call directly. It's a FastAPI plugin that bridges REST APIs to MCP without requiring manual OpenAPI-to-tool conversion, preserving authentication, request/response schemas, and documentation in the process. Monorepo structure: root holds the core fastapi_mcp package (not yet visible in file list but implied by README showing from fastapi_mcp import FastApiMCP), examples/ contains 9 runnable demos (01_basic_usage through 09_auth_example_auth0), docs/ is Markdown/MDX-based organized by topic (getting-started, advanced, configurations), and shared/ utilities (examples/shared/apps/items.py) demonstrate pattern usage.

Backend engineers and platform teams who operate FastAPI services and want to expose them safely to AI agents (via Claude, etc.) without building custom MCP servers or API wrappers. Specifically: teams using centralized auth systems (OAuth2, Auth0) who need token passthrough into exposed tools.

Actively developed and production-ready. The repo shows organized CI/CD (codecov, dependabot, GitHub workflows), comprehensive documentation across docs/advanced/ and docs/configurations/, and 8 concrete examples. Multiple stable releases visible in CHANGELOG.md, with maintained pre-commit and coverage tooling suggesting disciplined development.

Low risk for adoption; single-language codebase (Python 191k LOC) minimizes dependency sprawl. Primary risk is auth dependency coupling—the library assumes your FastAPI already has working auth middleware (see docs/advanced/auth.mdx), so misconfigured auth flows break tool execution silently. Last commit recency and maintainer availability should be verified via GitHub; repo is young enough that deprecation is possible but current activity level suggests active stewardship.

Active documentation expansion visible: 9 example files across auth (token passthrough, Auth0), transport (asgi.mdx, transport.mdx), deployment (deploy.mdx), and tool configuration (tool-naming.mdx, customization.mdx). GitHub workflows (ci.yml, release.yml) and dependabot.yml indicate continuous integration and dependency management is active.

git clone https://github.com/tadata-org/fastapi_mcp.git
cd fastapi_mcp
uv sync  # or 'pip install -e .'
python examples/01_basic_usage_example.py

Daily commands: From README: minimal setup is FastApiMCP(app).mount() to expose endpoints at /mcp. For examples: python examples/0X_*.py directly (each is a standalone demo). For local dev: standard FastAPI dev server (uvicorn likely, though not explicitly stated in visible files).

• fastapi_mcp/server.py — Core MCP server implementation that bridges FastAPI endpoints to MCP tools; all endpoint exposure logic lives here.
• fastapi_mcp/openapi/convert.py — Converts OpenAPI schemas to MCP tool definitions; essential for understanding how FastAPI routes become tools.
• fastapi_mcp/auth/proxy.py — Authentication proxy layer that enables passing credentials through to FastAPI endpoints; critical for secure integrations.
• fastapi_mcp/transport/http.py — HTTP transport implementation for MCP protocol; handles client-server communication over HTTP.
• fastapi_mcp/transport/sse.py — Server-Sent Events transport for streaming MCP messages; alternative to HTTP transport for long-lived connections.
• fastapi_mcp/__init__.py — Public API exports; shows what end-users directly import and use from the library.
• pyproject.toml — Project dependencies and metadata; declares FastAPI, MCP, and other critical runtime requirements.

Add a New Authentication Strategy

1. Create a new auth strategy class in fastapi_mcp/auth/ that implements credential handling and injection logic. (fastapi_mcp/auth/proxy.py)
2. Implement methods to extract credentials from MCP requests and inject them into outbound FastAPI calls. (fastapi_mcp/auth/proxy.py)
3. Export the strategy from fastapi_mcp/auth/init.py so users can instantiate it. (fastapi_mcp/auth/__init__.py)
4. Add example in examples/ folder (e.g., examples/10_auth_example_custom_strategy.py) demonstrating usage. (examples/README.md)

Add a New Transport Implementation

1. Create a new file in fastapi_mcp/transport/ (e.g., transport/websocket.py) implementing the transport protocol. (fastapi_mcp/transport/http.py)
2. Implement send() and receive() methods following the pattern in http.py or sse.py. (fastapi_mcp/transport/http.py)
3. Export the transport class from fastapi_mcp/transport/init.py. (fastapi_mcp/transport/__init__.py)
4. Add integration tests in tests/test_transport_new_type.py to verify message routing. (tests/conftest.py)

Customize Tool Naming or OpenAPI Conversion

1. Review the OpenAPI-to-MCP conversion logic in fastapi_mcp/openapi/convert.py. (fastapi_mcp/openapi/convert.py)
2. Add configuration parameters to MCPServer.init (in server.py) for naming rules, tool filtering, or schema transformation. (fastapi_mcp/server.py)
3. Modify convert.py functions to apply custom naming or filtering based on configuration. (fastapi_mcp/openapi/convert.py)
4. Add example in examples/06_custom_mcp_router_example.py demonstrating the customization. (examples/06_custom_mcp_router_example.py)

Extend Tool Registration and Discovery

1. Review MCPServer.list_tools() and MCPServer.call_tool() in server.py to understand discovery and execution. (fastapi_mcp/server.py)
2. Add filtering or caching logic in server.py to selectively expose endpoints (e.g., based on tags or paths). (fastapi_mcp/server.py)
3. If re-registering tools dynamically, see examples/05_reregister_tools_example.py for patterns. (examples/05_reregister_tools_example.py)

• FastAPI — Provides automatic OpenAPI schema generation, which is parsed to discover and expose endpoints as MCP tools.
• Model Context Protocol (MCP) — Industry standard for exposing tools to LLMs and AI agents; enables seamless integration with Claude and other MCP-compatible clients.
• HTTP & SSE transports — HTTP provides simple request-response semantics; SSE enables streaming responses without WebSocket complexity.
• Python type hints & Pydantic — Used for schema validation and tool parameter contracts, ensuring type-safe communication between MCP and FastAPI.

• OpenAPI schema as source of truth for tool discovery

  • Why: Avoids duplicating endpoint definitions; leverages FastAPI's built-in OpenAPI generation.
  • Consequence: Tool definitions are always in sync with actual endpoints, but OpenAPI schemas must be complete and accurate.

• Auth proxying via header/cookie injection rather than request forwarding

  • Why: Allows isolated client credentials to flow through to endpoints without exposing the MCP server's credentials.
  • Consequence: Developers must explicitly configure auth strategies; default behavior passes no credentials.

• Separate HTTP and SSE transports rather than unified abstraction

  • Why: Enables each transport to optimize for its use case (HTTP for simple calls, SSE for streaming).
  • Consequence: Server must support both transports independently; adds code duplication but provides flexibility.

• Tool execution by direct HTTP calls to FastAPI endpoints

  • Why: Simplest integration; reuses existing FastAPI request validation and business logic.
  • Consequence: Network hop required for each tool call; tight coupling between MCP server and FastAPI app.

• Does not implement MCP transport-level encryption; relies on TLS/HTTPS for secure communication.
• Does not provide built-in rate limiting or quota management; defer to FastAPI middleware.
• Does not handle real-time subscriptions; MCP tools are stateless request-response calls only.
• Does not modify FastAPI app internals; purely a wrapper exposing existing endpoints.

1. Auth context isolation: MCP tools are stateless by design, but FastAPI auth depends on request context (headers, cookies). Token passthrough requires explicit configuration in your app (see examples/08); implicit auth won't work. 2. ASGI transport coupling: The library communicates with your FastAPI app via ASGI directly—if you have middleware that modifies request state (e.g., tracing, custom auth injectors), tool execution may break or leak context. 3. Schema preservation limits: Complex Pydantic models with forward references or circular dependencies may not export cleanly to MCP; test with examples/02_full_schema_description_example.py. 4. No explicit environment variable docs: .python-version exists but no .env.example visible—you may need to infer auth config from Auth0 example.

• Model Context Protocol (MCP) — Core abstraction this library implements; understanding MCP's tool schema, resource, and prompt concepts is essential to knowing what fastapi-mcp exposes and why
• ASGI Transport — fastapi-mcp communicates with your FastAPI app via direct ASGI calls (not HTTP), enabling zero-network-latency tool execution; understanding ASGI scope/receive/send is crucial for debugging context leaks
• Dependency Injection (FastAPI Depends) — FastAPI-MCP leverages FastAPI's dependency system to pass auth context into tools; misunderstanding how Depends works will break auth integration
• JSON Schema Preservation — The library exports Pydantic model schemas as MCP tool input/output schemas without OpenAPI conversion; understanding Pydantic's schema_json_schema() is needed to debug schema mapping issues
• Token Passthrough Patterns — Auth tokens (OAuth2 Bearer, Auth0 JWTs) must be explicitly threaded through stateless MCP tool calls; fastapi-mcp examples show two patterns (implicit via Depends, explicit via context) but neither is automatic
• MCP Server Registration / Tool Discovery — Tools are auto-discovered from FastAPI route metadata (path, method, docstring, param models); knowing how this introspection works helps you control what gets exposed via tool-naming configuration

• anthropics/python-sdk — Official Claude/Anthropic SDK that consumes MCP tools exposed by fastapi-mcp; essential for testing tools in AI workflows
• modelcontextprotocol/python-sdk — Reference MCP SDK implementation; fastapi-mcp wraps and simplifies this for FastAPI developers
• tiangolo/fastapi — Core framework; fastapi-mcp is a plugin that depends on FastAPI's dependency injection and ASGI interface
• starlette/starlette — ASGI foundation under FastAPI; fastapi-mcp uses Starlette's request/response handling for MCP transport
• tadata-org/tadata — Maintainer's hosted MCP platform; fastapi-mcp is the open-source DIY alternative for self-hosted deployments

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for fastapi_mcp/auth/proxy.py

The auth module is critical for security but there are no visible test files in the repo structure. The proxy.py handles authentication logic that needs thorough coverage for token passthrough, Auth0 integration, and edge cases. This is essential for a security-sensitive feature.

• [ ] Create tests/auth/ directory structure
• [ ] Write unit tests for fastapi_mcp/auth/proxy.py covering token extraction, validation, and passthrough scenarios
• [ ] Add tests for the Auth0 example (examples/09_auth_example_auth0.py) integration
• [ ] Ensure tests cover error handling for missing/invalid credentials
• [ ] Update .coveragerc to enforce minimum coverage threshold for auth module

Add integration tests for fastapi_mcp/transport/ (HTTP and SSE)

The transport layer (HTTP and SSE in fastapi_mcp/transport/) is foundational but lacks visible integration tests. Given the complexity of MCP protocol compliance and multiple transport mechanisms, integration tests are critical to prevent regressions.

• [ ] Create tests/transport/ directory with integration test files
• [ ] Add tests/transport/test_http.py for HTTP transport endpoint behavior, error handling, and payload serialization
• [ ] Add tests/transport/test_sse.py for Server-Sent Events streaming, connection handling, and disconnection scenarios
• [ ] Test interaction between fastapi_mcp/server.py and transport layer with real MCP tool calls
• [ ] Add tests verifying OpenAPI schema conversion (fastapi_mcp/openapi/convert.py) produces valid MCP tool definitions

Add type checking tests and expand mypy.ini coverage for fastapi_mcp/

The repo has mypy.ini but no visible type checking tests in CI. Given the project's Python typing importance (MCP protocol compliance depends on correct schemas), explicit type validation tests would prevent type-related bugs and improve developer experience.

• [ ] Create tests/test_typing.py or add type checking stage to .github/workflows/ci.yml
• [ ] Expand mypy.ini to cover all fastapi_mcp/ modules with strict mode for auth and server modules
• [ ] Add tests verifying fastapi_mcp/types.py definitions match MCP specification types
• [ ] Add type validation for the conversion layer (fastapi_mcp/openapi/convert.py) output
• [ ] Document type requirements in CONTRIBUTING.md for contributors

• Add a test suite for examples/03_custom_exposed_endpoints_example.py and examples/06_custom_mcp_router_example.py to verify endpoint filtering and router customization work as documented in tool-naming.mdx
• Expand docs/advanced/deploy.mdx with a concrete Docker + environment variable example showing how to run FastAPI-MCP as a standalone MCP server (not mounted) with Auth0 tokens injected from env
• Create an example in examples/10_error_handling_example.py demonstrating how MCP tool errors (validation failures, timeouts from examples/07_configure_http_timeout_example.py) are surfaced back to AI clients, with test cases in test_error_handling.py

The FastAPI-MCP framework has a moderate security posture. Key concerns include: (1) Authentication implementation in the auth module needs verification for proper token handling; (2) Transport layers (HTTP/SSE) require enforcement of TLS and proper security headers; (3) OpenAPI schema exposure could leak sensitive details; (4) Input validation across endpoint conversion needs documentation. Strengths include: active dependency management with Dependabot, organized auth module structure, and comprehensive test infrastructure. Recommendations: conduct security code review of auth and transport modules, implement transport-level security controls, and add dedicated security test coverage.

• Medium · Potential Authentication Bypass in Auth Module — fastapi_mcp/auth/proxy.py, examples/08_auth_example_token_passthrough.py, examples/09_auth_example_auth0.py. The auth module (fastapi_mcp/auth/proxy.py) is exposed but without visibility into implementation details, there's a risk of improper token validation or session management. Auth examples reference Auth0 and token passthrough, which could be misconfigured. Fix: Review auth implementation for proper JWT validation, token expiration handling, and secure credential storage. Ensure no tokens are logged or exposed in error messages.
• Medium · HTTP Transport Security Concerns — fastapi_mcp/transport/http.py. The HTTP transport layer (fastapi_mcp/transport/http.py) may expose sensitive endpoint data or tool definitions to unauthorized clients if proper authentication and authorization checks are not implemented at the transport level. Fix: Implement rate limiting, request validation, and ensure all HTTP endpoints require proper authentication. Add security headers (HSTS, CSP, X-Content-Type-Options, etc.).
• Medium · SSE Transport Potential Man-in-the-Middle — fastapi_mcp/transport/sse.py. Server-Sent Events (SSE) transport (fastapi_mcp/transport/sse.py) transmits data over HTTP by default, which could be intercepted. No indication of HTTPS enforcement or encryption. Fix: Enforce HTTPS/TLS for all SSE connections. Implement certificate pinning for sensitive deployments. Add authentication tokens to SSE connection establishment.
• Medium · OpenAPI Conversion May Expose Sensitive Endpoint Details — fastapi_mcp/openapi/convert.py, fastapi_mcp/openapi/utils.py. The OpenAPI conversion module (fastapi_mcp/openapi/convert.py) automatically exposes endpoint schemas. These could reveal sensitive parameter names, data structures, or backend implementation details to potential attackers. Fix: Implement selective OpenAPI schema exposure. Require authentication to access OpenAPI documentation. Filter sensitive endpoints from schema generation.
• Low · Missing Input Validation Documentation — fastapi_mcp/server.py. While not directly visible in file structure, the framework converts FastAPI endpoints to MCP tools. Without explicit documentation on input sanitization, developers might expose endpoints vulnerable to injection attacks. Fix: Ensure comprehensive documentation on input validation requirements. Implement automatic input sanitization or validation at the MCP layer. Validate all parameters before passing to backend endpoints.
• Low · No Visible Dependency Pinning — pyproject.toml. The dependency file content was not provided in the analysis. Unable to verify if dependencies are pinned to specific versions, which could expose the application to vulnerable package versions. Fix: Pin all dependencies to specific versions. Use tools like pip-audit or Dependabot (already configured) to monitor for vulnerabilities. Review GitHub dependabot configuration regularly.
• Low · Test Coverage May Hide Security Issues — tests/ directory. While test files exist, security-specific tests (injection, auth bypass, CORS) are not evident from file structure. Fix: Add dedicated security tests including: authentication/authorization bypass attempts, injection attack vectors, rate limiting validation, and sensitive data leakage checks.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.