fastmcp

1---2name: fastmcp3description: Build, test, and deploy Python MCP servers.4version: 1.0.05author: Hermes Agent6license: MIT7platforms: [linux, macos, windows]8metadata:9  hermes:10    tags: [MCP, FastMCP, Python, Tools, Resources, Prompts, Deployment]11    homepage: https://gofastmcp.com12    related_skills: [hermes-agent, mcporter]13prerequisites:14  commands: [python]15---16 17# FastMCP18 19Build MCP servers in Python with FastMCP, validate them locally, install them into MCP clients, and deploy them as HTTP endpoints.20 21## When to Use22 23Use this skill when the task is to:24 25- create a new MCP server in Python26- wrap an API, database, CLI, or file-processing workflow as MCP tools27- expose resources or prompts in addition to tools28- smoke-test a server with the FastMCP CLI before wiring it into Hermes or another client29- install a server into Claude Code, Claude Desktop, Cursor, or a similar MCP client30- prepare a FastMCP server repo for HTTP deployment31 32Use `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.33 34## Prerequisites35 36Install FastMCP in the working environment first:37 38```bash39pip install fastmcp40fastmcp version41```42 43For the API template, install `httpx` if it is not already present:44 45```bash46pip install httpx47```48 49## Included Files50 51### Templates52 53- `templates/api_wrapper.py` - REST API wrapper with auth header support54- `templates/database_server.py` - read-only SQLite query server55- `templates/file_processor.py` - text-file inspection and search server56 57### Scripts58 59- `scripts/scaffold_fastmcp.py` - copy a starter template and replace the server name placeholder60 61### References62 63- `references/fastmcp-cli.md` - FastMCP CLI workflow, installation targets, and deployment checks64 65## Workflow66 67### 1. Pick the Smallest Viable Server Shape68 69Choose the narrowest useful surface area first:70 71- API wrapper: start with 1-3 high-value endpoints, not the whole API72- database server: expose read-only introspection and a constrained query path73- file processor: expose deterministic operations with explicit path arguments74- prompts/resources: add only when the client needs reusable prompt templates or discoverable documents75 76Prefer a thin server with good names, docstrings, and schemas over a large server with vague tools.77 78### 2. Scaffold from a Template79 80Copy a template directly or use the scaffold helper:81 82```bash83python ~/.hermes/skills/mcp/fastmcp/scripts/scaffold_fastmcp.py \84  --template api_wrapper \85  --name "Acme API" \86  --output ./acme_server.py87```88 89Available templates:90 91```bash92python ~/.hermes/skills/mcp/fastmcp/scripts/scaffold_fastmcp.py --list93```94 95If copying manually, replace `__SERVER_NAME__` with a real server name.96 97### 3. Implement Tools First98 99Start with `@mcp.tool` functions before adding resources or prompts.100 101Rules for tool design:102 103- Give every tool a concrete verb-based name104- Write docstrings as user-facing tool descriptions105- Keep parameters explicit and typed106- Return structured JSON-safe data where possible107- Validate unsafe inputs early108- Prefer read-only behavior by default for first versions109 110Good tool examples:111 112- `get_customer`113- `search_tickets`114- `describe_table`115- `summarize_text_file`116 117Weak tool examples:118 119- `run`120- `process`121- `do_thing`122 123### 4. Add Resources and Prompts Only When They Help124 125Add `@mcp.resource` when the client benefits from fetching stable read-only content such as schemas, policy docs, or generated reports.126 127Add `@mcp.prompt` when the server should provide a reusable prompt template for a known workflow.128 129Do not turn every document into a prompt. Prefer:130 131- tools for actions132- resources for data/document retrieval133- prompts for reusable LLM instructions134 135### 5. Test the Server Before Integrating It Anywhere136 137Use the FastMCP CLI for local validation:138 139```bash140fastmcp inspect acme_server.py:mcp141fastmcp list acme_server.py --json142fastmcp call acme_server.py search_resources query=router limit=5 --json143```144 145For fast iterative debugging, run the server locally:146 147```bash148fastmcp run acme_server.py:mcp149```150 151To test HTTP transport locally:152 153```bash154fastmcp run acme_server.py:mcp --transport http --host 127.0.0.1 --port 8000155fastmcp list http://127.0.0.1:8000/mcp --json156fastmcp call http://127.0.0.1:8000/mcp search_resources query=router --json157```158 159Always run at least one real `fastmcp call` against each new tool before claiming the server works.160 161### 6. Install into a Client When Local Validation Passes162 163FastMCP can register the server with supported MCP clients:164 165```bash166fastmcp install claude-code acme_server.py167fastmcp install claude-desktop acme_server.py168fastmcp install cursor acme_server.py -e .169```170 171Use `fastmcp discover` to inspect named MCP servers already configured on the machine.172 173When the goal is Hermes integration, either:174 175- configure the server in `~/.hermes/config.yaml` using the `native-mcp` skill, or176- keep using FastMCP CLI commands during development until the interface stabilizes177 178### 7. Deploy After the Local Contract Is Stable179 180For managed hosting, Prefect Horizon is the path FastMCP documents most directly. Before deployment:181 182```bash183fastmcp inspect acme_server.py:mcp184```185 186Make sure the repo contains:187 188- a Python file with the FastMCP server object189- `requirements.txt` or `pyproject.toml`190- any environment-variable documentation needed for deployment191 192For generic HTTP hosting, validate the HTTP transport locally first, then deploy on any Python-compatible platform that can expose the server port.193 194## Common Patterns195 196### API Wrapper Pattern197 198Use when exposing a REST or HTTP API as MCP tools.199 200Recommended first slice:201 202- one read path203- one list/search path204- optional health check205 206Implementation notes:207 208- keep auth in environment variables, not hardcoded209- centralize request logic in one helper210- surface API errors with concise context211- normalize inconsistent upstream payloads before returning them212 213Start from `templates/api_wrapper.py`.214 215### Database Pattern216 217Use when exposing safe query and inspection capabilities.218 219Recommended first slice:220 221- `list_tables`222- `describe_table`223- one constrained read query tool224 225Implementation notes:226 227- default to read-only DB access228- reject non-`SELECT` SQL in early versions229- limit row counts230- return rows plus column names231 232Start from `templates/database_server.py`.233 234### File Processor Pattern235 236Use when the server needs to inspect or transform files on demand.237 238Recommended first slice:239 240- summarize file contents241- search within files242- extract deterministic metadata243 244Implementation notes:245 246- accept explicit file paths247- check for missing files and encoding failures248- cap previews and result counts249- avoid shelling out unless a specific external tool is required250 251Start from `templates/file_processor.py`.252 253## Quality Bar254 255Before handing off a FastMCP server, verify all of the following:256 257- server imports cleanly258- `fastmcp inspect <file.py:mcp>` succeeds259- `fastmcp list <server spec> --json` succeeds260- every new tool has at least one real `fastmcp call`261- environment variables are documented262- the tool surface is small enough to understand without guesswork263 264## Troubleshooting265 266### FastMCP command missing267 268Install the package in the active environment:269 270```bash271pip install fastmcp272fastmcp version273```274 275### `fastmcp inspect` fails276 277Check that:278 279- the file imports without side effects that crash280- the FastMCP instance is named correctly in `<file.py:object>`281- optional dependencies from the template are installed282 283### Tool works in Python but not through CLI284 285Run:286 287```bash288fastmcp list server.py --json289fastmcp call server.py your_tool_name --json290```291 292This usually exposes naming mismatches, missing required arguments, or non-serializable return values.293 294### Hermes cannot see the deployed server295 296The server-building part may be correct while the Hermes config is not. Load the `native-mcp` skill and configure the server in `~/.hermes/config.yaml`, then restart Hermes.297 298## References299 300For CLI details, install targets, and deployment checks, read `references/fastmcp-cli.md`.301