fastmcp skill

FastMCP

Build MCP servers in Python with FastMCP, validate them locally, install them into MCP clients, and deploy them as HTTP endpoints.

When to Use

Use this skill when the task is to:

• create a new MCP server in Python
• wrap an API, database, CLI, or file-processing workflow as MCP tools
• expose resources or prompts in addition to tools
• smoke-test a server with the FastMCP CLI before wiring it into Hermes or another client
• install a server into Claude Code, Claude Desktop, Cursor, or a similar MCP client
• prepare a FastMCP server repo for HTTP deployment

Use native-mcp when the server already exists and only needs to be connected to Hermes. Use mcporter when the goal is ad-hoc CLI access to an existing MCP server instead of building one.

Prerequisites

Install FastMCP in the working environment first:

pip install fastmcp
fastmcp version

For the API template, install httpx if it is not already present:

pip install httpx

Included Files

Templates

• templates/api_wrapper.py - REST API wrapper with auth header support
• templates/database_server.py - read-only SQLite query server
• templates/file_processor.py - text-file inspection and search server

Scripts

• scripts/scaffold_fastmcp.py - copy a starter template and replace the server name placeholder

References

• references/fastmcp-cli.md - FastMCP CLI workflow, installation targets, and deployment checks

Workflow

1. Pick the Smallest Viable Server Shape

Choose the narrowest useful surface area first:

• API wrapper: start with 1-3 high-value endpoints, not the whole API
• database server: expose read-only introspection and a constrained query path
• file processor: expose deterministic operations with explicit path arguments
• prompts/resources: add only when the client needs reusable prompt templates or discoverable documents

Prefer a thin server with good names, docstrings, and schemas over a large server with vague tools.

2. Scaffold from a Template

Copy a template directly or use the scaffold helper:

python ~/.hermes/skills/mcp/fastmcp/scripts/scaffold_fastmcp.py \
  --template api_wrapper \
  --name "Acme API" \
  --output ./acme_server.py

Available templates:

python ~/.hermes/skills/mcp/fastmcp/scripts/scaffold_fastmcp.py --list

If copying manually, replace SERVERNAME__ with a real server name.

3. Implement Tools First

Start with @mcp.tool functions before adding resources or prompts.

Rules for tool design:

• Give every tool a concrete verb-based name
• Write docstrings as user-facing tool descriptions
• Keep parameters explicit and typed
• Return structured JSON-safe data where possible
• Validate unsafe inputs early
• Prefer read-only behavior by default for first versions

Good tool examples:

• get_customer
• search_tickets
• describe_table
• summarizetextfile

Weak tool examples:

• run
• process
• do_thing

4. Add Resources and Prompts Only When They Help

Add @mcp.resource when the client benefits from fetching stable read-only content such as schemas, policy docs, or generated reports.

Add @mcp.prompt when the server should provide a reusable prompt template for a known workflow.

Do not turn every document into a prompt. Prefer:

• tools for actions
• resources for data/document retrieval
• prompts for reusable LLM instructions

5. Test the Server Before Integrating It Anywhere

Use the FastMCP CLI for local validation:

fastmcp inspect acme_server.py:mcp
fastmcp list acme_server.py --json
fastmcp call acme_server.py search_resources query=router limit=5 --json

For fast iterative debugging, run the server locally:

fastmcp run acme_server.py:mcp

To test HTTP transport locally:

fastmcp run acme_server.py:mcp --transport http --host 127.0.0.1 --port 8000
fastmcp list http://127.0.0.1:8000/mcp --json
fastmcp call http://127.0.0.1:8000/mcp search_resources query=router --json

Always run at least one real fastmcp call against each new tool before claiming the server works.

6. Install into a Client When Local Validation Passes

FastMCP can register the server with supported MCP clients:

fastmcp install claude-code acme_server.py
fastmcp install claude-desktop acme_server.py
fastmcp install cursor acme_server.py -e .

Use fastmcp discover to inspect named MCP servers already configured on the machine.

When the goal is Hermes integration, either:

• configure the server in ~/.hermes/config.yaml using the native-mcp skill, or
• keep using FastMCP CLI commands during development until the interface stabilizes

7. Deploy After the Local Contract Is Stable

For managed hosting, Prefect Horizon is the path FastMCP documents most directly. Before deployment:

fastmcp inspect acme_server.py:mcp

Make sure the repo contains: