Skip to content

πŸš€ The fast, Pythonic way to build MCP servers and clients.

Add server authoring guidance through the docs site (#5703)

nate nowack144014d3ff93
diff --git a/README.md b/README.md
index ec4bf0d80..ed16fd664 100644
--- a/README.md
+++ b/README.md
@@ -117,6 +117,8 @@ Documentation is also available in [llms.txt format](https://llmstxt.org/), whic
- [`llms.txt`](https://gofastmcp.com/llms.txt) is essentially a sitemap, listing all the pages in the documentation.
- [`llms-full.txt`](https://gofastmcp.com/llms-full.txt) contains the entire documentation. Note this may exceed the context window of your LLM.
+Give your coding agent [`llms.txt`](https://gofastmcp.com/llms.txt) as its starting point. See [Coding Agents](https://gofastmcp.com/getting-started/ai-assisted-development) for version-matched documentation and the optional server authoring skill.
+
**Community:** Join our [Discord server](https://discord.gg/uu8dJCgttd) to connect with other FastMCP developers and share what you're building.
## Contributing
diff --git a/docs/.mintlify/skills b/docs/.mintlify/skills
new file mode 120000
index 000000000..5dcab58e1
--- /dev/null
+++ b/docs/.mintlify/skills
@@ -0,0 +1 @@
+../../skills
\ No newline at end of file
diff --git a/docs/docs.json b/docs/docs.json
index f7f7073c9..e0f2e2519 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -94,6 +94,7 @@
"getting-started/welcome",
"getting-started/installation",
"getting-started/quickstart",
+ "getting-started/ai-assisted-development",
"getting-started/whats-new"
]
},
diff --git a/docs/getting-started/ai-assisted-development.mdx b/docs/getting-started/ai-assisted-development.mdx
new file mode 100644
index 000000000..6a9fbb468
--- /dev/null
+++ b/docs/getting-started/ai-assisted-development.mdx
@@ -0,0 +1,48 @@
+---
+title: AI-assisted Development
+sidebarTitle: Coding Agents
+description: Give your coding agent FastMCP authoring guidance and documentation matched to your project.
+icon: robot
+---
+
+Give your coding agent [llms.txt](https://gofastmcp.com/llms.txt) as its starting point for FastMCP. This index links to the documentation as Markdown. Ask the agent to check your project's installed version and read the relevant pages before writing code.
+
+## Read version-matched documentation
+
+For FastMCP 3, use the index entries under `/v3/`; unversioned pages describe FastMCP 4. Every page is available as Markdown by appending `.md` to its URL, such as [the tools guide](https://gofastmcp.com/servers/tools.md). Read the pages relevant to the task; [llms-full.txt](https://gofastmcp.com/llms-full.txt) contains the entire documentation and may exceed your agent's context window.
+
+Agents with MCP support can also search the documentation at `https://gofastmcp.com/mcp`. See [LLM-friendly docs](/getting-started/welcome#llm-friendly-docs) for a client example.
+
+## Add authoring guidance
+
+The optional `fastmcp-server` skill adds a workflow for building, extending, and reviewing servers: choose suitable MCP interfaces, preserve useful schemas and errors, consult version-matched documentation, and verify behavior through a real client. The documentation index helps the agent find API information; installing the skill makes this authoring guidance available for the agent to select across tasks.
+
+Install it with the [Skills CLI](https://github.com/vercel-labs/skills), which lets you choose your coding agent:
+
+```bash
+npx skills add https://gofastmcp.com --skill fastmcp-server
+```
+
+The site's [skill discovery index](https://gofastmcp.com/.well-known/skills/index.json) lists the available skills. The [skill source](https://github.com/PrefectHQ/fastmcp/tree/main/skills/fastmcp-server) lives alongside FastMCP's client CLI skill; the site publishes those same files. You can also install from the repository with `npx skills add PrefectHQ/fastmcp --skill fastmcp-server`. The skill uses the agent's documentation access and code execution tools.
+
+Start a new agent session after installing. Ask it to use the `fastmcp-server` skill when working on your server. For example:
+
+```text
+Use the fastmcp-server skill to build an MCP server for this issue tracker.
+Expose paginated search and issue details, preserve upstream failures as errors,
+and test the interface through a FastMCP client. Keep the project's FastMCP version.
+```
+
+The skill is maintained in the FastMCP repository and evolves separately from package releases. Update your installed copy to pick up changes, or install from a Git revision when you need reproducible instructions. Your project's dependency constraints still determine which FastMCP APIs the agent should use.
+
+<Tip>
+ For an agent that needs to discover and call an existing server, use the [client CLI skill](https://github.com/PrefectHQ/fastmcp/tree/main/skills/fastmcp-client-cli). The server authoring skill is for writing server code.
+</Tip>
+
+## Verify the generated server
+
+Run the server's tests and inspect the schemas and results that clients receive. A successful import or the agent's final message does not establish that the server works. The [testing guide](/development/tests#test-through-an-in-memory-client) shows how to connect `fastmcp.Client` directly to your server without starting a network listener.
+
+For deployment work, also test the intended transport and authentication. Use local fixtures or a test account for operations that change data.
+
+If your server's users need guidance for workflows spanning several operations, consider supplying skills with the server. The [Skills Provider](/servers/providers/skills) serves skill files as resources; the [Experimental Skills Extension](/servers/providers/experimental-skills) adds standard skills discovery. Check the installed FastMCP version and target host's support, and verify that the host actually reads and uses the skill. Discovery alone does not activate it.
diff --git a/skills/fastmcp-server/SKILL.md b/skills/fastmcp-server/SKILL.md
new file mode 100644
index 000000000..7b71de3f1
--- /dev/null
+++ b/skills/fastmcp-server/SKILL.md
@@ -0,0 +1,96 @@
+---
+name: fastmcp-server
+description: Build, extend, or review MCP servers with Python FastMCP, using documentation matched to the project's version.
+---
+
+# Authoring MCP servers with FastMCP
+
+## Find the current API
+
+Check the project's installed FastMCP version and dependency constraints.
+Fetch [the documentation index](https://gofastmcp.com/llms.txt) 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.