# FastAPI MCP Production Kit

![Python](https://img.shields.io/badge/python-3.11%2B-blue)
![FastAPI](https://img.shields.io/badge/FastAPI-MCP%20safety-009688)
![License: MIT](https://img.shields.io/badge/license-MIT-green)

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

```bash
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:

```bash
uvicorn prodkit_mcp.app:app --reload
```

List available tools:

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

Create a demo token:

```bash
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:

```bash
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:

```bash
python scripts/generate_audit_fixtures.py
```

Run the public boundary scan:

```bash
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](production/README.md)
- [Security model](production/security-model.md)
- [Scopes](production/scopes.md)
- [Audit events](production/audit-events.md)
- [Quotas](production/quotas.md)
- [Deployment](production/deployment.md)
- [Web-access boundaries](production/web-access-boundaries.md)
- [Provider fallback](production/provider-fallback.md)
- [Observability](production/observability.md)
- [Troubleshooting](production/troubleshooting.md)

## 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.

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

## License

MIT