fastmcp

⚠Review·Scanned 2/18/2026

This skill provides templates, examples, and agents to build FastMCP MCP servers in Python/TypeScript and to deploy them. It includes explicit shell commands (pip install fastmcp, npx wrangler deploy), environment-secret usage (API_KEY, GITHUB_CLIENT_SECRET, STORAGE_ENCRYPTION_KEY), and network endpoints (https://github.com/login/oauth/authorize, https://api.example.com).

by jezweb·v10a1f16·224.8 KB·409 installs
Scanned from main at 10a1f16 · Transparency log ↗
$ vett add jezweb/claude-skills/fastmcpReview findings below

fastmcp

Build MCP (Model Context Protocol) servers in Python with FastMCP

What This Skill Does

This skill provides production-tested patterns, templates, and error prevention for building production-ready MCP servers with FastMCP in Python. It covers:

  • Server Creation: Tools, resources, resource templates, and prompts
  • Storage Backends: Memory, Disk, Redis, DynamoDB with encrypted persistence
  • Server Lifespans: Resource management for DB connections and API clients
  • Middleware System: 8 built-in types (logging, rate limiting, caching, error handling, timing)
  • Server Composition: Modular architecture with import/mount strategies
  • Authentication: 4 patterns (Token Validation, Remote OAuth, OAuth Proxy, Full OAuth)
  • OAuth Proxy: Bridge to GitHub, Google, Azure, AWS, Discord, Facebook
  • Icons Support: Visual representations for better UX
  • API Integration: OpenAPI/Swagger auto-generation, FastAPI conversion, manual integration
  • Cloud Deployment: FastMCP Cloud requirements and common pitfalls
  • Error Prevention: 28 documented errors with solutions
  • Production Patterns: Self-contained architecture, connection pooling, caching, retry logic
  • Context Features: Elicitation, progress tracking, sampling, state management
  • Background Tasks (v2.14.0+): Long-running operations with progress tracking
  • Sampling with Tools (v2.14.1+): Agentic workflows where LLM can call tools
  • Testing: Unit and integration testing patterns
  • Client Configuration: Claude Desktop, Claude Code CLI

When to Use This Skill

Use this skill when you need to:

  • Build an MCP server to expose tools/resources/prompts to LLMs
  • Configure persistent storage for OAuth tokens or response caching
  • Set up server lifespans for database connections or API client pooling
  • Add middleware for logging, rate limiting, caching, or error handling
  • Compose modular servers with import/mount strategies
  • Implement OAuth authentication (GitHub, Google, Azure, AWS, Discord, Facebook)
  • Secure MCP servers with JWT verification or OAuth Proxy
  • Add icons to servers, tools, resources, or prompts
  • Integrate an external API with Claude (via MCP)
  • Deploy an MCP server to FastMCP Cloud
  • Convert an OpenAPI/Swagger spec to MCP
  • Convert a FastAPI app to MCP
  • Wrap a database, file system, or service for LLM access
  • Debug MCP server errors (storage, lifespan, middleware, OAuth, circular imports)
  • Test MCP servers with FastMCP Client
  • Implement elicitation (user input during execution)
  • Add progress tracking to long-running operations
  • Use sampling (LLM completions from within tools)
  • Manage server state with context

Don't use this skill if:

  • You're building an MCP client (not server)
  • You're using a different MCP framework (not FastMCP)
  • You're working in a language other than Python
  • You're building with Anthropic's TypeScript SDK for MCP

Auto-Trigger Keywords

This skill should automatically trigger when you mention:

Primary Keywords

  • fastmcp, fast mcp, FastMCP
  • MCP server, mcp server, MCP server python, python mcp server
  • model context protocol, model context protocol python
  • mcp tools, mcp resources, mcp prompts
  • mcp integration, mcp framework

Use Case Keywords

  • build mcp server, create mcp server, make mcp server
  • python mcp, mcp python, mcp with python
  • integrate api with claude, expose api to llm, api for claude
  • openapi to mcp, swagger to mcp, fastapi to mcp
  • mcp cloud, fastmcp cloud, deploy mcp
  • mcp testing, test mcp server

Storage & Persistence Keywords

  • mcp storage, fastmcp storage backends, persistent storage mcp
  • redis storage mcp, disk storage mcp, encrypted storage
  • oauth token storage, cache persistence mcp
  • py-key-value-aio, fernet encryption mcp

Middleware Keywords

  • mcp middleware, fastmcp middleware, middleware system
  • rate limiting mcp, response caching mcp, logging middleware
  • timing middleware, error handling middleware
  • middleware order, middleware hooks

Authentication Keywords

  • oauth mcp, oauth proxy mcp, jwt verification mcp
  • github oauth mcp, google oauth mcp, azure oauth mcp
  • token validation mcp, auth patterns mcp
  • consent screen, pkce mcp, token introspection

Server Composition Keywords

  • import server mcp, mount server mcp, server composition
  • modular mcp, subservers mcp, tag filtering mcp

Lifespan Keywords

  • server lifespan mcp, mcp lifespan, resource management mcp
  • database connection mcp, cleanup hooks mcp
  • asgi integration mcp, fastapi lifespan

Icons Keywords

  • mcp icons, server icons mcp, visual mcp
  • data uri icons, icon sizes mcp

Error Keywords

  • mcp server not found, no server object found
  • storage backend error, lifespan not running, middleware order error
  • oauth not persisting, consent screen missing
  • circular import fastmcp, import error mcp
  • module-level server, fastmcp cloud deployment
  • mcp async await, mcp context injection
  • resource uri scheme, invalid resource uri
  • pydantic validation mcp, mcp json serializable

Feature Keywords

  • mcp elicitation, user input during tool execution
  • mcp progress tracking, progress updates mcp
  • mcp sampling, llm from mcp tool
  • resource templates mcp, dynamic resources
  • tool transformation mcp, client handlers
  • state management mcp, context state

Integration Keywords

  • openapi integration, swagger integration, fastapi mcp
  • api wrapper mcp, database mcp, file system mcp
  • connection pooling mcp, caching mcp, retry logic mcp

Claude Integration Keywords

  • claude desktop mcp, claude code mcp
  • claude_desktop_config.json, mcp configuration
  • expose tools to claude, claude tools

Token Efficiency

  • Without skill: ~50-70k tokens, 8-15 errors
  • With skill: ~3-5k tokens, 0 errors
  • Savings: 90-95% token reduction

This is the highest token savings in the skills collection!

Errors Prevented

This skill prevents 28 common errors:

Core Server Errors (1-5)

  1. Missing server object - Module-level export for FastMCP Cloud
  2. Async/await confusion - Proper async/sync patterns
  3. Context not injected - Type hints for context parameter
  4. Resource URI syntax - Missing scheme prefixes
  5. Resource template mismatch - Parameter name alignment

Validation & Serialization (6-12)

  1. Pydantic validation errors - Type hint consistency
  2. Transport/protocol mismatch - Client/server compatibility
  3. Import errors - Editable package installation
  4. Deprecation warnings - FastMCP v2 migration
  5. Port conflicts - Address already in use
  6. Schema generation failures - Unsupported type hints
  7. JSON serialization - Non-serializable objects

Architecture & Lifecycle (13-15)

  1. Circular imports - Factory function anti-patterns
  2. Python version compatibility - Deprecated methods
  3. Import-time execution - Async resource creation

Storage & Persistence (16)

  1. Storage backend not configured - Production persistence requirements

Lifespan & Integration (17)

  1. Lifespan not passed to ASGI app - FastAPI/Starlette integration

Middleware (18-19)

  1. Middleware execution order error - Incorrect middleware ordering
  2. Circular middleware dependencies - Middleware loop errors

Server Composition (20-21)

  1. Import vs mount confusion - Static vs dynamic composition
  2. Resource prefix format mismatch - Path vs protocol formats

OAuth & Security (22-23)

  1. OAuth proxy without consent screen - Security vulnerabilities
  2. Missing JWT signing key - Production auth requirements

Icons & Breaking Changes (24-25)

  1. Icon data URI format error - Invalid data URI format
  2. Lifespan behavior change (v2.13.0) - Per-server vs per-session

v2.14.0 Migration Errors (26-28)

  1. BearerAuthProvider removed - Use OAuth patterns instead
  2. Context.get_http_request() removed - Use alternative context methods
  3. fastmcp.Image import changed - New import path required

What's Included

Templates (19)

Basic Server Templates:

  • basic-server.py - Minimal working server
  • tools-examples.py - Sync/async tools
  • resources-examples.py - Static/dynamic resources
  • prompts-examples.py - Prompt templates

Production Features:

  • storage-backends-example.py - Memory, Disk, Redis storage
  • server-lifespan-example.py - Database connection lifecycle
  • middleware-examples.py - All 8 built-in middleware types
  • server-composition-example.py - Import vs mount patterns
  • oauth-proxy-example.py - Full OAuth proxy configuration
  • authentication-patterns.py - 4 auth strategies
  • icons-example.py - Server and component icons

Integration & Testing:

  • openapi-integration.py - OpenAPI auto-generation
  • api-client-pattern.py - Manual API integration
  • client-example.py - Testing with Client
  • error-handling.py - Structured errors with retry
  • self-contained-server.py - Production pattern

Configuration:

  • .env.example - Environment variables
  • requirements.txt - Package dependencies (fastmcp>=2.14.0)
  • pyproject.toml - Package configuration

Reference Docs (11)

Error & Deployment:

  • common-errors.md - 28 errors with solutions
  • cloud-deployment.md - FastMCP Cloud guide
  • cli-commands.md - FastMCP CLI reference

Production Features:

  • storage-backends.md - Complete storage options guide
  • server-lifespans.md - Lifecycle management patterns
  • middleware-guide.md - Middleware system deep dive
  • oauth-security.md - OAuth Proxy and security features
  • performance-optimization.md - Caching and middleware strategies

Integration & Patterns:

  • integration-patterns.md - OpenAPI, FastAPI patterns
  • production-patterns.md - Self-contained architecture
  • context-features.md - Elicitation, progress, sampling, state

Scripts (3)

  • check-versions.sh - Verify package versions
  • test-server.sh - Test with FastMCP Client
  • deploy-cloud.sh - Deployment checklist

Quick Start

Install the Skill

cd /path/to/claude-skills
./scripts/install-skill.sh fastmcp

Use the Skill

Just mention "fastmcp" or "build an mcp server" in your conversation with Claude Code, and the skill will automatically load.

Example prompts:

  • "Help me build a FastMCP server"
  • "Create an MCP server that wraps this API"
  • "Convert this OpenAPI spec to an MCP server"
  • "My MCP server has a circular import error"
  • "Deploy my MCP server to FastMCP Cloud"

Production Validation

Tested With:

  • FastMCP 2.14.x (v2.14.0+ with Background Tasks and Sampling with Tools)
  • Python 3.10, 3.11, 3.12
  • Storage backends: Memory, Disk, Redis
  • Middleware: All 8 built-in types
  • OAuth Proxy: GitHub, Google authentication
  • FastMCP Cloud deployments
  • OpenAPI integrations
  • FastAPI conversions
  • Server composition (import/mount)
  • Background Tasks with Docket scheduler
  • Sampling with Tools (AnthropicSamplingHandler)

Based On:

Package Info

  • Package: fastmcp>=2.14.0
  • Python: >=3.10
  • Repository: https://github.com/jlowin/fastmcp
  • Cloud: https://fastmcp.cloud
  • Context7: /jlowin/fastmcp
  • Dependencies:
    • py-key-value-aio (storage backends)
    • cryptography (encrypted storage)
    • httpx (async HTTP)
    • pydantic (validation)
    • docket (background task scheduling, optional)

Included Agents

This skill includes 1 companion agent for common workflows:

AgentPurposeTrigger Phrases
mcp-scaffoldCreate MCP server projects"create mcp server", "scaffold fastmcp project"

Why use the agent? Context hygiene. Project scaffolding generates many files - the agent runs in isolated context and returns a clean summary of what was created.

Related Skills

  • openai-api - OpenAI API integration
  • claude-api - Claude API integration
  • cloudflare-worker-base - Deploy as Cloudflare Worker
  • google-gemini-api - Gemini API integration
  • clerk-auth - Alternative auth solution
  • better-auth - Better Auth for authentication

Skill Metadata

  • Version: 2.1.0
  • License: MIT
  • Token Savings: 90-95%
  • Errors Prevented: 28
  • Production Tested: ✅
  • Last Updated: 2026-01-03
  • Breaking Changes: v2.14.0 removes BearerAuthProvider and Context.get_http_request()

Questions or issues? Check the templates and references in this skill, or consult the official FastMCP documentation at https://github.com/jlowin/fastmcp