FastMCP
When to use this skill
Use when designing, implementing, configuring, inspecting, or evaluating Model Context Protocol (MCP) applications using the official FastMCP framework (v4.2.0+ "Mad Skills"). FastMCP provides high-level Pythonic and TypeScript abstractions for:
- Authoring MCP servers with callable tools, addressable resources, and message prompts.
- Serving and consuming Agent Skills over MCP using the SEP-2640 Skills extension (
Skill,SkillCatalogProvider,SkillsDirectoryProvider). - Dependency injection with
Annotated[T, Depends(...)]andCallArgument. - Multi-transport hosting across stdio, Server-Sent Events (SSE), and streamable HTTP.
- Command-line tool inspection and execution with
fastmcp list,fastmcp call,fastmcp discover,fastmcp dev, andfastmcp run. - In-process integration testing with
Client(server).
Route-outs
- For wrapping an external REST API without the FastMCP framework or building general Anthropic tool evaluations, use
mcp-builder. - For linting Agent Skills frontmatter, YAML boundaries, or directory layouts, use
skill-standardization. - For raw OpenTelemetry export or streaming telemetry pipelines without MCP server logic, use
agent-observability. - For evaluating LLM generation quality and RAG Triad scores, use
trulens.
Instructions
1. Offline environment preflight
Before running servers or invoking external commands, run the offline preflight helper:
python3 "$SKILL_DIR/scripts/preflight.py" --json
This checks for local fastmcp CLI availability, Python package imports (fastmcp, fastmcp_slim, mcp, pydantic), and local database/configuration presence without network requests or binary execution.
2. FastMCP server authoring
Create an MCP server exposing typed tools, resources, and prompts:
from fastmcp import FastMCP, Context
from pydantic import Field
from typing import Literal
mcp = FastMCP("Service Assistant 🚀")
@mcp.tool
def calculate_vat(
amount: float = Field(gt=0, description="Gross amount in currency"),
rate: Literal["standard", "reduced", "zero"] = "standard"
) -> dict:
"""Calculate VAT rate and total amount."""
rates = {"standard": 0.20, "reduced": 0.05, "zero": 0.0}
tax = amount * rates[rate]
return {"amount": amount, "tax": tax, "total": amount + tax}
@mcp.resource("system://metrics")
def get_metrics() -> str:
"""Return live system operational metrics."""
return "status=healthy uptime=99.98%"
@mcp.prompt("triage-issue")
def triage_prompt(issue_id: str, severity: str = "medium") -> list[dict]:
"""Generate message template for triaging an issue."""
return [
{"role": "user", "content": f"Please triage issue {issue_id} marked as severity: {severity}."}
]
if __name__ == "__main__":
mcp.run()
3. Dependency injection and context
Declare dependencies in parameter annotations with Annotated[T, Depends(...)] so types remain clean for schema generation:
from typing import Annotated
from fastmcp import FastMCP, Depends, Context
mcp = FastMCP("Secure Service")
def get_db_session():
# Yield or return managed resource
return {"connection": "active"}
@mcp.tool
async def fetch_record(
record_id: str,
db: Annotated[dict, Depends(get_db_session)],
ctx: Context
) -> dict:
"""Fetch record with database session and context logging."""
await ctx.info(f"Looking up {record_id}")
return {"id": record_id, "status": "found"}
4. Serving and consuming Agent Skills (v4.2 Mad Skills)
FastMCP 4.2 serves Agent Skills directly from the server next to the tools they describe, implementing the SEP-2640 Skills extension:
Server-side skill hosting:
from fastmcp import FastMCP, Skill
from fastmcp.skills.provider import SkillCatalogProvider, SkillsDirectoryProvider
# Single skill from local directory
deploy_skill = Skill.from_directory("skills/deploy")
# Or serve an entire directory of skills
provider = SkillsDirectoryProvider("skills")
mcp = FastMCP("DevOps Skills")
mcp.add_provider(SkillCatalogProvider([deploy_skill]))
# or: mcp.add_provider(provider)
Client-side skill discovery and consumption:
from fastmcp import Client
async with Client(mcp) as client:
# 1. List available skills
skills = await client.list_skills()
for s in skills:
print(f"Skill: {s.name} - {s.description}")
# 2. Read full verified skill and verify digests
skill = await client.read_skill("deploy")
print(f"Verified files: {len(skill.files)}")
# 3. Export skill to local directory for host use
skill.to_directory("~/.agents/skills/deploy")
Security Boundary: Hash verification verifies file bytes against the server manifest; host approval remains authoritative before executing code or injecting instructions into context.
5. Transports and security
Choose the appropriate transport for your runtime environment:
# 1. Standard I/O (default for local desktop clients like Claude Desktop)
mcp.run(transport="stdio")
# 2. Server-Sent Events (SSE) for legacy HTTP streaming
mcp.run(transport="sse", host="127.0.0.1", port=8000)
# 3. Streamable HTTP (modern production deployment)
mcp.run(transport="http", host="0.0.0.0", port=8000)
For sensitive operations:
- Use
ToolError("Friendly error message")fromfastmcp.exceptionsto return safe client-facing errors. - Enable
mask_error_details=Trueto prevent internal stack traces and database details from leaking to the model.
6. FastMCP CLI toolchain
Use the fastmcp CLI for discovery, inspection, and execution:
# 1. Discover servers configured in editors and mcp.json
fastmcp discover --json
# 2. Inspect tools, resources, and prompts on any server target
fastmcp list server.py --input-schema --output-schema
fastmcp list http://localhost:8000/mcp --skills
# 3. Invoke a tool from the command line with auto type-coercion
fastmcp call server.py calculate_vat amount=100 rate=standard --json
# 4. Interactive developer UI / live reloading
fastmcp dev server.py
# 5. Install an MCP server into local client configs
fastmcp install server.py --name "my-service"
7. In-process verification
Always write deterministic tests using FastMCP's built-in in-process Client:
import pytest
from fastmcp import Client
from my_server import mcp
@pytest.mark.asyncio
async def test_calculate_vat_in_process():
async with Client(mcp) as client:
result = await client.call_tool("calculate_vat", {"amount": 50.0, "rate": "reduced"})
assert result.content[0].text is not None
References
- Upstream Sources & Pin: FastMCP v4.2.0 commit
5e71792, repository links, and licensing. - Server Authoring & Transports: In-depth guide to tools, resources, prompts, dependency injection, and SSE/HTTP transports.
- Skills Extension & Providers: SEP-2640 Skills extension,
SkillCatalogProvider, manifest digests, and client discovery. - Client & CLI Operations: Command reference for
fastmcp list,call,discover,dev, andClientGroup. - Evaluation Scenarios: Five representative scenarios for evaluating FastMCP operations.
