FastMCP Server Reference: Build, Validate, Install, and Deploy

This reference covers building, validating, installing, and deploying MCP servers in Python using FastMCP. Use it when you need to create a new MCP server, wrap an API or database as MCP tools, smoke-test a server before wiring into a client, or prepare a server for HTTP deployment.

Prerequisites

Install FastMCP in your active Python environment:

pip install fastmcp
fastmcp version

If you plan to use the API wrapper template, install httpx as well:

pip install httpx

Server Design Principles

Pick the Smallest Viable Server Shape

Start with the narrowest useful surface area. For an API wrapper, begin with 1-3 high-value endpoints. For a database server, expose read-only introspection and a constrained query path. For a file processor, expose deterministic operations with explicit path arguments. Add prompts or resources 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.

Implement Tools First

Begin with @mcp.tool functions before adding resources or prompts. 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. Default to read-only behavior for first versions.

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 documents, 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. Use tools for actions, resources for data and document retrieval, and prompts for reusable LLM instructions.

Scaffolding a Server

List Available Templates

To see which templates are available:

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

Scaffold from a Template

Copy a template directly or use the scaffold helper. The following example scaffolds an API wrapper server:

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

The --template parameter accepts values such as api_wrapper, database_server, and file_processor. The --name parameter is the human-readable name for the new server. The --output parameter is the file path for the generated script. If copying manually, replace the __SERVER_NAME__ placeholder with the real server name.

Template Patterns

• API Wrapper Pattern: Expose REST/HTTP API as MCP tools. First slice: one read path, one list/search path, optional health check. Start from templates/api_wrapper.py.
• Database Pattern: Expose safe query and inspection capabilities. First slice: list_tables, describe_table, one constrained read query tool. Start from templates/database_server.py.
• File Processor Pattern: Inspect or transform files on demand. First slice: summarize file contents, search within files, extract deterministic metadata. Start from templates/file_processor.py.

Local Validation

Inspect the Server

Before integrating anywhere, validate the server with the FastMCP CLI. The fastmcp inspect command checks that the file imports cleanly and the FastMCP instance is named correctly:

fastmcp inspect acme_server.py:mcp

List Tools

List all tools exposed by the server:

fastmcp list acme_server.py --json

Call a Tool

Test a specific tool with arguments:

fastmcp call acme_server.py search_resources query=router limit=5 --json

Run the Server Locally

For iterative debugging, run the server over stdio transport:

fastmcp run acme_server.py:mcp

Test HTTP Transport

To test HTTP transport locally:

fastmcp run acme_server.py:mcp --transport http --host 127.0.0.1 --port 8000

Then list tools and call them over HTTP:

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.

Installation into Clients

When local validation passes, 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 .

The -e flag specifies the environment for Cursor installation (e.g., . for the current directory).

Discover Existing Servers

To inspect named MCP servers already configured on the machine:

fastmcp discover

Hermes Integration

For Hermes integration, configure the server in ~/.hermes/config.yaml using the native-mcp skill, or continue using the FastMCP CLI during development. If the server already exists and only needs connection to Hermes, use the native-mcp skill. For ad-hoc CLI access to an existing MCP server instead of building one, use mcporter.

Deployment

Final Validation

Before deploying, run final validation:

fastmcp inspect acme_server.py:mcp

Repository Requirements

Ensure the repo contains:

• The Python file with the FastMCP server object
• requirements.txt or pyproject.toml
• Environment variable documentation

Hosting Options

For managed hosting, Prefect Horizon is the documented path. For generic HTTP hosting, validate HTTP transport locally first, then deploy on any Python-compatible platform that can expose the server port.

Constraints and Best Practices

• Keep authentication in environment variables, not hardcoded.
• Centralize request logic in one helper for API wrappers.
• Surface API errors with concise context.
• Normalize inconsistent upstream payloads before returning them.
• Reject non-SELECT SQL in early database server versions.
• Limit row counts in database queries.
• Return rows plus column names from database queries.
• Accept explicit file paths in file processors.
• Check for missing files and encoding failures in file processors.
• Cap previews and result counts in file processors.
• Avoid shelling out unless a specific external tool is required.
• The server must import cleanly.
• fastmcp inspect must succeed.
• fastmcp list --json must succeed.
• Every new tool must have at least one real fastmcp call.
• Environment variables must be documented.
• The tool surface must be small enough to understand without guesswork.

Failure Modes

• FastMCP command missing: Install the package in the active environment with pip install fastmcp.
• fastmcp inspect fails: The file imports with side effects that crash, the FastMCP instance is named incorrectly, or optional dependencies are missing.
• Tool works in Python but not through CLI: Naming mismatches, missing required arguments, or non-serializable return values. Debug with fastmcp list --json and fastmcp call.
• Hermes cannot see deployed server: Server building is correct but Hermes configuration is wrong. Use the native-mcp skill and configure in ~/.hermes/config.yaml, then restart Hermes.

Quick Validation Commands

For a quick check that a server is functional:

fastmcp list server.py --json
fastmcp call server.py your_tool_name --json

Additional Resources

For detailed CLI reference, see references/fastmcp-cli.md. The scaffold script is located at scripts/scaffold_fastmcp.py. Template files are at templates/api_wrapper.py, templates/database_server.py, and templates/file_processor.py.

Tool Naming Examples

When designing tools, use concrete verb-based names. Examples include get_customer for retrieving a single customer record, search_tickets for querying a ticket system, and summarize_text_file for generating a summary of a text file. Avoid generic names like do_thing which provide no context about the tool's purpose.