Authoring MCP servers with FastMCP

Find the current API

Check the project's installed FastMCP version and dependency constraints. Fetch the documentation index and read the relevant pages for that version. The index includes versioned documentation; select /v3/ pages for FastMCP 3 and unversioned pages for FastMCP 4. Read individual pages through their .md URLs instead of loading llms-full.txt. For APIs newer than the installed release, check that release's source or signatures. Preserve the project's dependency constraints unless an upgrade is part of the request. For a new project, check the current stable release before choosing a dependency.

Use the standalone fastmcp package. Its API differs from mcp.server.fastmcp in the Python MCP SDK.

Author the server

Choose the MCP interface to suit what the server exposes: tools for callable operations, resources for addressable content, and prompts for reusable message templates. FastMCP derives tool schemas from Python annotations and descriptions; use Literal or enums for finite choices and Field descriptions for parameter semantics. SDK wrappers need to preserve signatures and docstrings, for example with functools.wraps, or discovery loses that information. Inspect the schema the client receives, especially after transforms or custom discovery rendering: requiredness, enum values, and nested fields can disappear from a summary.

Let the intended client tasks guide tool boundaries, descriptions, and result shape. Give clients enough context to use results and recover from errors. The right granularity depends on the service; generated API tools, custom tools, and compositions can all be appropriate.

For paginated or bounded results, expose whether the answer is complete and how to continue. An upstream failure is not an empty result. Return useful recovery information through tool errors rather than a successful-looking payload. Use ToolError, ResourceError, or PromptError from fastmcp.exceptions for intentional client-facing messages. With mask_error_details=True, ordinary exceptions such as ValueError lose their messages; do not put sensitive backend details in the explicit error types, whose messages remain visible.

When using tool search or code mode, make exact named operations discoverable and explain the execution contract: what persists between calls and what becomes the result. A short fetch/filter/return example can prevent repeated empty outputs. Check the installed implementation before describing that behavior.

Look up FastMCP's relevant facilities as needed: context and dependencies, lifespan, authentication, composition, and transports. Use the project's runtime and hosting choices to determine configuration.

When clients need a repeatable workflow across the server's capabilities, consider shipping a skill alongside those capabilities. Put task selection, operation sequencing, and recovery guidance in the skill; keep tool descriptions focused on their individual contracts. Read the version-matched Skills Provider and Experimental Skills Extension docs from the index before implementing it. SkillsDirectoryProvider exposes skill files as resources; the experimental extension adds skills/list and skills/get discovery. Check the installed release and target host's support before selecting either interface. Discovery does not activate a skill: verify that the host reads and uses it in the intended workflow. The experimental extension currently requires directly registered providers and does not support mounted or transformed skill sources.

Verify the server through FastMCP's Client, which can connect directly to a server instance for in-process testing. Check a representative operation, its client-visible schema and result, and a meaningful failure. For composed or transformed servers, verify the public names and URIs through the outer server, including resource references returned by prompts. Namespace transforms change component names and resource URIs, but do not rewrite URI text inside prompt messages. When a prompt must work both standalone and mounted, direct the client to discover the resource template instead of hardcoding the child's URI. Exercise the chosen transport when connection or deployment behavior is part of the change.

Evaluate agent workflows

When the task includes evaluating how agents use the server, test a representative workflow using the project's existing evaluation harness when available. Protocol tests show that a tool works; an agent task shows whether the interface is usable. Start from a known condition, give an agent a user-level request, and check the outcome against independent API or database evidence. For writes, check both the intended change and what should remain unchanged. A normal agent exit or a plausible final answer is not proof of success.

Use the target client's actual capabilities; exposing resources, sampling, or elicitation does not mean that client uses them. To measure the server alone, give the agent only that server's capabilities supported by the client. To measure the user's workflow, include the other capabilities the client really has. Inspect traces for discovery misses, invalid arguments, partial-data assumptions, and repeated recovery attempts before changing tool descriptions or structure. Compare task success alongside calls, latency, and context size; fewer tools or tokens alone is not the objective.