FastAPI MCP Production Kit

A local-first FastAPI and MCP safety kit for turning internal HTTP APIs into controlled MCP tools.

Most MCP examples show how to expose a tool. This repo focuses on what teams need before agents can use those tools safely: local credentials, per-tool scopes, quota checks, audit events, web-access boundaries, fallback decisions, and a quickstart that works without paid services.

This kit helps you answer:

• Which FastAPI capabilities should become MCP tools?
• How do tool calls prove identity before doing work?
• How do different tools get different scopes?
• How do quotas and audit events work before remote deployment?
• How do web-access tools default to deny instead of arbitrary outbound access?

Ships today:

• FastAPI app factory with /healthz, tool discovery, demo token, and tool-call endpoints
• Local MCP-style tool dispatcher with three tools
• HMAC-signed local demo tokens
• Per-tool scope checks
• Deterministic in-memory quotas
• Structured audit events and JSONL fixture generation
• Default-deny web-access fixture boundary
• Provider fallback decision record helper
• Pytest coverage for auth, scopes, quotas, audit, boundaries, fallback, and tool calls
• Public boundary scan script
• Production docs map for security, scopes, audit, quotas, deployment, web access, fallback, observability, and troubleshooting

Quickstart

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e '.[dev]'
pytest
python examples/local-only-demo/demo_client.py

Run the FastAPI app:

uvicorn prodkit_mcp.app:app --reload

List available tools:

curl -s http://127.0.0.1:8000/tools

Create a demo token:

curl -s http://127.0.0.1:8000/demo/token \
  -H 'content-type: application/json' \
  -d '{"subject_id":"local-developer","scopes":["project:read","docs:search","web:fetch"]}'

Call a tool:

curl -s http://127.0.0.1:8000/tools/read_project_status \
  -H "authorization: Bearer $ACCESS_TOKEN" \
  -H 'content-type: application/json' \
  -d '{"arguments":{}}'

Generate audit fixtures:

python scripts/generate_audit_fixtures.py

Run the public boundary scan:

python scripts/scan_public_boundary.py

Tool Model

Tool	Scope	Purpose
read_project_status	project:read	Reads a synthetic project status record
search_docs_fixture	docs:search	Searches bundled documentation fixtures
fetch_allowed_page	web:fetch	Fetches only reviewed safe page fixtures

What This Is Not

This is not a hosted MCP platform, a broad server directory, a production security review, or an arbitrary web-access tool. It is a local reference kit for making MCP tool exposure easier to reason about before remote deployment.

Production Guides

• Production docs map
• Security model
• Scopes
• Audit events
• Quotas
• Deployment
• Web-access boundaries
• Provider fallback
• Observability
• Troubleshooting

Optional MCP SDK Adapter

The default quickstart uses the local dispatcher so the safety path is easy to test in CI. If you install the optional mcp extra, prodkit_mcp.mcp_server can create a FastMCP server wrapper around the same tools.

python -m pip install -e '.[mcp,dev]'

License

MIT