Skip to content

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

Publish regular skill files for Mintlify discovery (#5956)

nate nowackd92276995f2f
diff --git a/.github/workflows/run-static.yml b/.github/workflows/run-static.yml
index 68926334c..fe21b7932 100644
--- a/.github/workflows/run-static.yml
+++ b/.github/workflows/run-static.yml
@@ -29,6 +29,9 @@ jobs:
steps:
- uses: actions/checkout@v7
+ - name: Check published skills match their sources
+ run: diff -ru skills docs/.mintlify/skills
+
- name: Setup uv
uses: ./.github/actions/setup-uv
with:
diff --git a/docs/.mintlify/skills/fastmcp-client-cli b/docs/.mintlify/skills/fastmcp-client-cli
deleted file mode 120000
index 249b27419..000000000
--- a/docs/.mintlify/skills/fastmcp-client-cli
+++ /dev/null
@@ -1 +0,0 @@
-../../../skills/fastmcp-client-cli
\ No newline at end of file
diff --git a/docs/.mintlify/skills/fastmcp-client-cli/SKILL.md b/docs/.mintlify/skills/fastmcp-client-cli/SKILL.md
new file mode 100644
index 000000000..ae66a5e31
--- /dev/null
+++ b/docs/.mintlify/skills/fastmcp-client-cli/SKILL.md
@@ -0,0 +1,114 @@
+---
+name: fastmcp-client-cli
+description: Query and invoke tools on MCP servers using fastmcp list and fastmcp call. Use when you need to discover what tools a server offers, call tools, or integrate MCP servers into workflows.
+---
+
+# FastMCP CLI: List and Call
+
+Use `fastmcp list` and `fastmcp call` to interact with any MCP server from the command line.
+
+## Listing Tools
+
+```bash
+# Remote server
+fastmcp list http://localhost:8000/mcp
+
+# Local Python file (runs via fastmcp run automatically)
+fastmcp list server.py
+
+# MCPConfig with multiple servers
+fastmcp list mcp.json
+
+# Stdio command (npx, uvx, etc.)
+fastmcp list --command 'npx -y @modelcontextprotocol/server-github'
+
+# Include full input/output schemas
+fastmcp list server.py --input-schema --output-schema
+
+# Machine-readable JSON
+fastmcp list server.py --json
+
+# Include resources and prompts
+fastmcp list server.py --resources --prompts
+```
+
+Default output shows tool signatures and descriptions. Use `--input-schema` or `--output-schema` to include full JSON schemas, `--json` for structured output.
+
+## Calling Tools
+
+```bash
+# Key=value arguments (auto-coerced to correct types)
+fastmcp call server.py greet name=World
+fastmcp call server.py add a=3 b=4
+
+# Single JSON object for complex/nested args
+fastmcp call server.py create_item '{"name": "Widget", "tags": ["a", "b"]}'
+
+# --input-json with key=value overrides
+fastmcp call server.py search --input-json '{"query": "hello", "limit": 5}' limit=10
+
+# JSON output for scripting
+fastmcp call server.py add a=3 b=4 --json
+```
+
+Type coercion is automatic: `limit=5` becomes an integer, `verbose=true` becomes a boolean, based on the tool's input schema.
+
+## Server Targets
+
+All commands accept the same server targets:
+
+| Target | Example |
+|--------|---------|
+| HTTP/HTTPS URL | `http://localhost:8000/mcp` |
+| Python file | `server.py` |
+| MCPConfig JSON | `mcp.json` (must have `mcpServers` key) |
+| Stdio command | `--command 'npx -y @mcp/server'` |
+| Discovered name | `weather` or `source:name` |
+
+Servers configured in editor configs (Claude Desktop, Claude Code, Cursor, Gemini CLI, Goose) or project-level `mcp.json` can be referenced by name. Use `source:name` (e.g. `claude-code:my-server`, `cursor:weather`) to target a specific source. Run `fastmcp discover` to see available names.
+
+For SSE servers, pass `--transport sse`:
+
+```bash
+fastmcp list http://localhost:8000/mcp --transport sse
+```
+
+## Auth
+
+HTTP targets automatically use OAuth (no-ops if the server doesn't require auth). Disable with `--auth none`:
+
+```bash
+fastmcp call http://server/mcp tool --auth none
+```
+
+## Discovering Configured Servers
+
+```bash
+# See all MCP servers in editor/project configs
+fastmcp discover
+
+# Filter by source
+fastmcp discover --source claude-code
+
+# JSON output
+fastmcp discover --json
+```
+
+Scans Claude Desktop, Claude Code, Cursor, Gemini CLI, Goose, and `./mcp.json`. Sources: `claude-desktop`, `claude-code`, `cursor`, `gemini`, `goose`, `project`.
+
+## Workflow Pattern
+
+Discover tools first, then call them:
+
+```bash
+# 1. See what servers are configured
+fastmcp discover
+
+# 2. See what tools a server has
+fastmcp list weather
+
+# 3. Call a tool
+fastmcp call weather get_forecast city=London
+```
+
+If you call a nonexistent tool, FastMCP suggests close matches.
diff --git a/docs/.mintlify/skills/fastmcp-server b/docs/.mintlify/skills/fastmcp-server
deleted file mode 120000
index a01de2ff8..000000000
--- a/docs/.mintlify/skills/fastmcp-server
+++ /dev/null
@@ -1 +0,0 @@
-../../../skills/fastmcp-server
\ No newline at end of file
diff --git a/docs/.mintlify/skills/fastmcp-server/SKILL.md b/docs/.mintlify/skills/fastmcp-server/SKILL.md
new file mode 100644
index 000000000..7b71de3f1
--- /dev/null
+++ b/docs/.mintlify/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.