dev-backbone-template/SKILLS/83-fastmcp-3-patterns.md

# FastMCP 3 Patterns (Providers + Transforms)

Use this skill when you are building MCP servers in Python and want:
- composable tool sets
- per-user/per-session behavior
- auth, versioning, observability, and long-running tasks

## Mental model (FastMCP 3)
FastMCP 3 treats everything as three composable primitives:
- **Components**: what you expose (tools, resources, prompts)
- **Providers**: where components come from (decorators, files, OpenAPI, remote MCP, etc.)
- **Transforms**: how you reshape what clients see (namespace, filters, auth, versioning, visibility)

## Recommended architecture for Marc’s platform
Build a **single “Cyber MCP Gateway”** that composes providers:
- LocalProvider: core cyber tools (run hunt, parse triage, generate report)
- OpenAPIProvider: wrap stable internal APIs (ticketing, asset DB) without 1:1 endpoint exposure
- ProxyProvider/FastMCPProvider: mount sub-servers (e.g., Velociraptor tools, Intel feeds)

Then apply transforms:
- Namespace per domain: `hunt.*`, `intel.*`, `pad.*`
- Visibility per session: hide dangerous tools unless user/role allows
- VersionFilter: keep old clients working while you evolve tools

## Production must-haves
- **Tool timeouts**: never let a tool hang forever
- **Pagination**: all list tools must be bounded
- **Background tasks**: use for long hunts / ingest jobs
- **Tracing**: emit OpenTelemetry traces so you can debug agent/tool behavior

## Auth rules
- Prefer component-level auth for “dangerous” tools.
- Default stance: read-only tools visible; write/execute tools gated.

## Versioning rules
- Version your components when you change schemas or semantics.
- Keep 1 previous version callable during migrations.

## Upgrade guidance
FastMCP 3 is in beta; pin to v2 for stability in production until you’ve tested.