ceos/fastmcp
1
0
Fork 0
mirror of https://github.com/PrefectHQ/fastmcp.git synced 2026-08-09 07:09:11 +02:00
Code Issues Projects Releases Packages Wiki Activity

Align CLI, deployment, and config docs (#4259)

Browse source 
* docs: align CLI and deployment docs

Generated with Codex.

* docs: restore install config support, fix CIMD placeholder, add missing CLI flags

* docs: restore contrib guidance, correct --copy availability

* docs: remove dead redirect-shadowed pages

* Fix stale --path default in run command help

* docs: correct Goose flag support, fix README link to moved testing page

---------

Co-authored-by: Jeremiah Lowin <153965+jlowin@users.noreply.github.com>
This commit is contained in:
Bill Easton 2026-07-19 13:24:07 -05:00 • committed by GitHub
commit 149a7aa2ce
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
18 changed files with 85 additions and 1334 deletions
Download patch file Download diff file Expand all files Collapse all files

12
docs/cli/auth.mdx
View file

@ -23,21 +23,24 @@ fastmcp auth cimd create \
```json
{
"client_id": "https://your-domain.com/oauth/client.json",
"client_id": "https://YOUR-DOMAIN.com/path/to/client.json",
"client_name": "My App",
"redirect_uris": ["http://localhost:*/callback"],
"token_endpoint_auth_method": "none"
"token_endpoint_auth_method": "none",
"grant_types": ["authorization_code"],
"response_types": ["code"]
}
```
The generated document includes a placeholder `client_id` — update it to match the URL where you'll host the document before deploying.
By default, the generated document includes a placeholder `client_id`. Update it to match the URL where you'll host the document before deploying, or pass `--client-id` when generating the file.
### Options
| Option | Flag | Description |
| ------ | ---- | ----------- |
| Name | `--name` | **Required.** Human-readable client name |
| Redirect URI | `--redirect-uri` | **Required.** Allowed redirect URIs (repeatable) |
| Redirect URI | `--redirect-uri`, `-r` | **Required.** Allowed redirect URIs (repeatable) |
| Client ID | `--client-id` | URL where this document will be hosted; defaults to a placeholder |
| Client URI | `--client-uri` | Client's home page URL |
| Logo URI | `--logo-uri` | Client's logo URL |
| Scope | `--scope` | Space-separated list of scopes |
@ -51,6 +54,7 @@ fastmcp auth cimd create \
--name "My Production App" \
--redirect-uri "http://localhost:*/callback" \
--redirect-uri "https://myapp.example.com/callback" \
--client-id "https://myapp.example.com/oauth/client.json" \
--client-uri "https://myapp.example.com" \
--scope "read write" \
--output client.json

17
docs/cli/client.mdx
View file

@ -104,11 +104,28 @@ Some tools request additional input during execution through MCP's elicitation m
| ------ | ---- | ----------- |
| Command | `--command` | Connect via stdio |
| Transport | `--transport`, `-t` | Force `http` or `sse` |
| Prompt | `--prompt` | Treat the target as a prompt name instead of a tool/resource |
| Input JSON | `--input-json` | Base arguments as JSON (merged with `key=value`) |
| JSON | `--json` | Raw JSON output |
| Timeout | `--timeout` | Connection timeout in seconds |
| Auth | `--auth` | `oauth`, a bearer token, or `none` |
## Reading Resources and Getting Prompts
`fastmcp call` can also read resources and render prompts. If the target contains `://`, the CLI treats it as a resource URI and calls `read_resource`:
```bash
fastmcp call server.py resource://docs/readme
fastmcp call server.py file:///tmp/example.txt --json
```
To get a prompt, pass `--prompt`; prompt arguments use the same `key=value` and `--input-json` forms as tool calls:
```bash
fastmcp call server.py summarize --prompt topic=weather
fastmcp call server.py summarize --prompt --input-json '{"topic": "weather"}'
```
## Discovering Configured Servers
`fastmcp discover` scans your machine for MCP servers configured in editors and tools. It checks:

5
docs/cli/inspecting.mdx
View file

@ -55,6 +55,11 @@ fastmcp inspect server.py --format mcp -o manifest.json
| ------ | ---- | ----------- |
| Format | `--format`, `-f` | `fastmcp` or `mcp` (required when using `-o`) |
| Output File | `--output`, `-o` | Save to file instead of stdout |
| Python | `--python` | Python version to use when running via `uv` |
| Extra Packages | `--with` | Additional packages to install (repeatable) |
| Project | `--project` | Run within a specific uv project directory |
| Requirements | `--with-requirements` | Install from a requirements file |
| Skip Env | `--skip-env` | Do not set up a uv environment |
## Entrypoints

23
docs/cli/install-mcp.mdx
View file

@ -14,7 +14,7 @@ import { VersionBadge } from '/snippets/version-badge.mdx'
```bash
fastmcp install claude-desktop server.py
fastmcp install claude-code server.py --with pandas --with matplotlib
fastmcp install cursor server.py -e .
fastmcp install cursor server.py --with-editable .
```
<Warning>
@ -41,14 +41,13 @@ Because MCP clients run servers in isolation, you need to tell the install comma
```bash
fastmcp install claude-desktop server.py --with pandas --with "sqlalchemy>=2.0"
fastmcp install cursor server.py -e . --with-requirements requirements.txt
fastmcp install cursor server.py --with-editable . --with-requirements requirements.txt
```
**`fastmcp.json`** configuration files declare dependencies alongside the server definition. When you install from a config file, dependencies are picked up automatically:
**`fastmcp.json`** configuration files declare dependencies alongside the server definition. When you install from a config file explicitly, dependencies are picked up automatically:
```bash
fastmcp install claude-desktop fastmcp.json
fastmcp install claude-desktop # auto-detects fastmcp.json in current directory
```
See [Server Configuration](/deployment/server-configuration) for the full config format.
@ -57,15 +56,19 @@ See [Server Configuration](/deployment/server-configuration) for the full config
| Option | Flag | Description |
| ------ | ---- | ----------- |
| Server Name | `--server-name`, `-n` | Custom name for the server |
| Editable Package | `--with-editable`, `-e` | Install a directory in editable mode |
| Server Name | `--name`, `-n` | Custom name for the server |
| Editable Package | `--with-editable` | Install a directory in editable mode |
| Extra Packages | `--with` | Additional packages (repeatable) |
| Environment Variables | `--env` | `KEY=VALUE` pairs (repeatable) |
| Environment File | `--env-file`, `-f` | Load env vars from a `.env` file |
| Environment File | `--env-file` | Load env vars from a `.env` file |
| Python | `--python` | Python version (e.g., `3.11`) |
| Project | `--project` | Run within a uv project directory |
| Requirements | `--with-requirements` | Install from a requirements file |
| Config Path | `--config-path` | Custom path to Claude Desktop config directory (`claude-desktop` only) |
| Workspace | `--workspace` | Install to the workspace directory instead of globally (`cursor` only) |
| Copy | `--copy` | Copy the generated output to the clipboard (`mcp-json` and `stdio` only) |
`goose` installs through a deeplink that runs your server with `uvx`, so it accepts only `--name`, `--with`, and `--python`. Options that depend on a local uv project — `--with-editable`, `--project`, and `--with-requirements` — are unavailable there. Deeplinks also cannot carry environment variables: passing `--env` or `--env-file` exits with an error directing you to `fastmcp install mcp-json`, which generates a config you can add to Goose by hand with the variables included.
## Examples
@ -73,12 +76,12 @@ See [Server Configuration](/deployment/server-configuration) for the full config
# Basic install with auto-detected server instance
fastmcp install claude-desktop server.py
# Install from fastmcp.json with auto-detection
fastmcp install claude-desktop
# Install from fastmcp.json
fastmcp install claude-desktop fastmcp.json
# Explicit entrypoint with dependencies
fastmcp install claude-desktop server.py:my_server \
--server-name "My Analysis Server" \
--name "My Analysis Server" \
--with pandas
# With environment variables

2
docs/cli/overview.mdx
View file

@ -23,7 +23,7 @@ fastmcp --help
| [`install`](/cli/install-mcp) | Install a server into Claude Code, Claude Desktop, Cursor, Gemini CLI, or Goose |
| [`inspect`](/cli/inspecting) | Print a server's tools, resources, and prompts as a summary or JSON report |
| [`list`](/cli/client) | List a server's tools (and optionally resources and prompts) |
| [`call`](/cli/client#calling-tools) | Call a single tool with arguments |
| [`call`](/cli/client#calling-tools) | Call a tool, read a resource, or get a prompt |
| [`discover`](/cli/client#discovering-configured-servers) | Find MCP servers configured in your editors and tools |
| [`generate-cli`](/cli/generate-cli) | Scaffold a standalone typed CLI from a server's tool schemas |
| [`project prepare`](/cli/running#pre-building-environments) | Pre-install dependencies into a reusable uv project |

13
docs/cli/running.mdx
View file

@ -69,19 +69,22 @@ fastmcp run mcp.json
```
<Warning>
`fastmcp run` completely ignores the `if __name__ == "__main__"` block. Any setup code in that block won't execute. If you need initialization logic to run, use a [factory function](/cli/overview#factory-functions).
`fastmcp run` completely ignores the `if __name__ == "__main__"` block. Any setup code in that block won't execute. If you need initialization logic to run, use a [factory function](#entrypoints).
</Warning>
### Options
| Option | Flag | Description |
| ------ | ---- | ----------- |
| Transport | `--transport`, `-t` | `stdio` (default), `http`, or `sse` |
| Transport | `--transport`, `-t` | `stdio` (default), `http` / `streamable-http`, or `sse` |
| Host | `--host` | Bind address for HTTP (default: `127.0.0.1`) |
| Port | `--port`, `-p` | Bind port for HTTP (default: `8000`) |
| Path | `--path` | URL path for HTTP (default: `/mcp/`) |
| Path | `--path` | URL path for HTTP (default: `/mcp` for `http`, `/sse` for `sse`) |
| Log Level | `--log-level`, `-l` | `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL` |
| No Banner | `--no-banner` | Suppress the startup banner |
| Stateless | `--stateless` | Run without sessions, for serverless and multi-worker deployments |
| Module Mode | `--module`, `-m` | Run a Python module via `python -m` instead of a file path |
| Skip Source | `--skip-source` | Skip source preparation (use when the source is already prepared) |
| Auto-Reload | `--reload` / `--no-reload` | Watch for file changes and restart automatically |
| Reload Dirs | `--reload-dir` | Directories to watch (repeatable) |
| Skip Env | `--skip-env` | Don't set up a uv environment (use when already in one) |
@ -127,7 +130,7 @@ Auto-reload is on by default — save a file and the MCP server restarts automat
```bash
fastmcp dev inspector server.py
fastmcp dev inspector server.py -e . --with pandas
fastmcp dev inspector server.py --with-editable . --with pandas
```
<Tip>
@ -140,7 +143,7 @@ The Inspector connects over **stdio only**. When it launches, you may need to se
| Option | Flag | Description |
| ------ | ---- | ----------- |
| Editable Package | `--with-editable`, `-e` | Install a directory in editable mode |
| Editable Package | `--with-editable` | Install a directory in editable mode |
| Extra Packages | `--with` | Additional packages (repeatable) |
| Inspector Version | `--inspector-version` | MCP Inspector version to use |
| UI Port | `--ui-port` | Port for the Inspector UI |

161
docs/clients/cli.mdx
View file

@ -1,161 +0,0 @@
---
title: Client CLI
sidebarTitle: CLI
description: Query and invoke MCP server tools directly from the terminal with fastmcp list and fastmcp call.
icon: terminal
---
import { VersionBadge } from '/snippets/version-badge.mdx'
<VersionBadge version="3.0.0" />
MCP servers are designed for programmatic consumption by AI assistants and applications. But during development, you often want to poke at a server directly: check what tools it exposes, call one with test arguments, or verify that a deployment is responding correctly. The FastMCP CLI gives you that direct access with two commands, `fastmcp list` and `fastmcp call`, so you can query and invoke any MCP server without writing a single line of Python.
These commands are also valuable for LLM-based agents that lack native MCP support. An agent that can execute shell commands can use `fastmcp list --json` to discover available tools and `fastmcp call --json` to invoke them, with structured JSON output designed for programmatic consumption.
## Server Targets
Both commands need to know which server to talk to. You provide a "server spec" as the first argument, and FastMCP figures out the transport automatically. You can point at an HTTP URL for a running server, a Python file that defines one, a JSON configuration file that describes one, or a JavaScript file. The CLI resolves the right connection mechanism so you can focus on the query.
```bash
fastmcp list http://localhost:8000/mcp
fastmcp list server.py
fastmcp list mcp-config.json
```
Python files are handled with particular care. Rather than requiring your script to call `mcp.run()` at the bottom, the CLI routes it through `fastmcp run` internally, which means any Python file that defines a FastMCP server object works as a target with no boilerplate.
For servers that communicate over stdio (common with Node.js-based MCP servers), use the `--command` flag instead of a positional server spec. The string is shell-split into a command and arguments.
```bash
fastmcp list --command 'npx -y @modelcontextprotocol/server-github'
```
### Name-Based Resolution
If your MCP servers are already configured in an editor or tool, you can refer to them by name instead of spelling out URLs or file paths. The CLI scans config files from Claude Desktop, Claude Code, Cursor, Gemini CLI, and Goose, and matches the name you provide.
```bash
fastmcp list weather
fastmcp call weather get_forecast city=London
```
You can also use the `source:name` form to target a specific source directly, which is useful when the same server name appears in multiple configs or when you want to be explicit about which config you mean.
```bash
fastmcp list claude-code:my-server
fastmcp call cursor:weather get_forecast city=London
```
The available source names are `claude-desktop`, `claude-code`, `cursor`, `gemini`, `goose`, and `project` (for `./mcp.json`). Run `fastmcp discover` to see what's available.
## Discovering Configured Servers
`fastmcp discover` scans your local editor and project configurations for MCP server definitions. It checks Claude Desktop, Claude Code (`~/.claude.json`), Cursor workspace configs (walking up from the current directory), Gemini CLI (`~/.gemini/settings.json`), Goose (`~/.config/goose/config.yaml`), and `mcp.json` in the current directory.
```bash
fastmcp discover
```
The output groups servers by source, showing each server's name and transport. Use `--source` to filter to specific sources, and `--json` for machine-readable output.
```bash
fastmcp discover --source claude-code
fastmcp discover --source cursor --source gemini --json
```
Any server that appears here can be used by name (or `source:name`) with `fastmcp list` and `fastmcp call`, which means you can go from "I have a server configured in Claude Code" to querying it without copying any URLs or paths.
## Discovering Tools
`fastmcp list` connects to a server and prints every tool it exposes. The default output is compact: each tool appears as a function signature with its parameter names, types, and a description.
```bash
fastmcp list http://localhost:8000/mcp
```
The output looks like a Python function signature, making it easy to see at a glance what a tool expects and what it returns. Required parameters appear with just their type annotation, while optional ones show their defaults.
When you need the full JSON Schema for a tool's inputs or outputs -- useful for understanding nested object structures or enum constraints -- opt into them with `--input-schema` or `--output-schema`. These print the raw schema beneath each tool signature.
### Beyond Tools
MCP servers can expose resources and prompts alongside tools. By default, `fastmcp list` only shows tools because they are the most common interaction point. Add `--resources` or `--prompts` to include those in the output.
```bash
fastmcp list server.py --resources --prompts
```
Resources appear with their URIs and descriptions. Prompts appear with their argument names so you can see what parameters they accept.
### Machine-Readable Output
The `--json` flag switches from human-friendly text to structured JSON. Each tool includes its name, description, and full input schema (and output schema when present). When combined with `--resources` or `--prompts`, those are included as additional top-level keys.
```bash
fastmcp list server.py --json
```
This is the format to use when building automation around MCP servers or feeding tool definitions to an LLM agent that needs to decide which tool to call.
## Calling Tools
`fastmcp call` invokes a single tool on a server. You provide the server spec, the tool name, and arguments as `key=value` pairs. The CLI fetches the tool's schema, coerces your string values to the correct types (integers, floats, booleans, arrays, objects), and makes the call.
```bash
fastmcp call http://localhost:8000/mcp search query=hello limit=5
```
Type coercion is driven by the tool's JSON Schema. If a parameter is declared as an integer, the string `"5"` becomes the integer `5`. Booleans accept `true`/`false`, `yes`/`no`, and `1`/`0`. Array and object parameters are parsed as JSON.
For tools with complex or deeply nested arguments, the `key=value` syntax gets unwieldy. You can pass a single JSON object as the argument instead, and the CLI treats it as the full input dictionary.
```bash
fastmcp call server.py create_item '{"name": "Widget", "tags": ["sale", "new"], "metadata": {"color": "blue"}}'
```
Alternatively, `--input-json` provides the base argument dictionary. Any `key=value` pairs you add alongside it override keys from the JSON, which is useful for templating a complex call and varying one parameter at a time.
### Error Handling
The CLI validates your call before sending it. If you misspell a tool name, it uses fuzzy matching to suggest corrections. If you omit a required argument, it tells you which ones are missing and prints the tool's signature as a reminder.
When a tool call itself returns an error (the server executed the tool but it failed), the error message is printed and the CLI exits with a non-zero status code, making it straightforward to use in scripts.
### Structured Output
Like `fastmcp list`, the `--json` flag on `fastmcp call` emits structured JSON instead of formatted text. The output includes the content blocks, error status, and structured content when the server provides it. Use this when you need to parse tool results programmatically.
```bash
fastmcp call server.py get_weather city=London --json
```
## Authentication
When the server target is an HTTP URL, the CLI automatically enables OAuth authentication. If the server requires it, you will be guided through the OAuth flow (typically opening a browser for authorization). If the server has no auth requirements, the OAuth setup is a silent no-op.
To explicitly disable authentication -- for example, when connecting to a local development server where OAuth setup would just slow you down -- pass `--auth none`.
```bash
fastmcp call http://localhost:8000/mcp my_tool --auth none
```
## Transport Override
FastMCP defaults to Streamable HTTP for URL targets. If you are connecting to a server that only supports Server-Sent Events (SSE), use `--transport sse` to force the older transport. This appends `/sse` to the URL path automatically so the client picks the correct protocol.
```bash
fastmcp list http://localhost:8000 --transport sse
```
## Interactive Elicitation
Some MCP tools request additional input from the user during execution through a mechanism called elicitation. When a tool sends an elicitation request, the CLI prints the server's question to the terminal and prompts you to respond. Each field in the elicitation schema is presented with its name and expected type, and required fields are clearly marked.
You can type `decline` to skip a question or `cancel` to abort the tool call entirely. This interactive behavior means the CLI works naturally with tools that have multi-step or conversational workflows.
## LLM Agent Integration
For LLM agents that can execute shell commands but lack built-in MCP support, the CLI provides a clean integration path. The agent calls `fastmcp list --json` to get a structured description of every available tool, including full input schemas, and then calls `fastmcp call --json` with the chosen tool and arguments. Both commands return well-formed JSON that is straightforward to parse.
Because the CLI handles connection management, transport selection, and type coercion internally, the agent does not need to understand MCP protocol details. It just needs to read JSON and construct shell commands.

166
docs/clients/generate-cli.mdx
View file

@ -1,166 +0,0 @@
---
title: Generate CLI
sidebarTitle: Generate CLI
description: Turn any MCP server into a standalone, typed command-line tool.
icon: wand-magic-sparkles
tag: NEW
---
import { VersionBadge } from '/snippets/version-badge.mdx'
<VersionBadge version="3.0.0" />
`fastmcp list` and `fastmcp call` let you poke at a server interactively, but they're developer tools — you always have to spell out the server spec, the tool name, and the arguments. `fastmcp generate-cli` takes the next step: it connects to a server, reads its schemas, and writes a standalone Python script where every tool is a proper subcommand with typed flags, help text, and tab completion. The result is a CLI that feels like it was hand-written for that specific server.
The key insight is that MCP tool schemas already contain everything a CLI framework needs: parameter names, types, descriptions, required/optional status, and defaults. `generate-cli` maps that schema into [cyclopts](https://cyclopts.readthedocs.io/) commands, so JSON Schema types become Python type annotations, descriptions become `--help` text, and required parameters become mandatory flags.
## Generating a Script
Point the command at any server spec — URLs, Python files, discovered server names, MCPConfig JSON — and it writes a CLI script:
```bash
fastmcp generate-cli weather
fastmcp generate-cli http://localhost:8000/mcp
fastmcp generate-cli server.py my_weather_cli.py
```
The second positional argument sets the output path. When omitted, it defaults to `cli.py`. If either the CLI file or its companion `SKILL.md` already exists, the command refuses to overwrite unless you pass `-f`:
```bash
fastmcp generate-cli weather -f
fastmcp generate-cli weather my_cli.py -f
```
Name-based resolution works here too, so if you have a server configured in Claude Desktop, Cursor, or any other supported editor, you can reference it by name. Run [`fastmcp discover`](/clients/cli#discovering-configured-servers) to see what's available.
```bash
fastmcp generate-cli claude-code:my-server output.py
```
The `--timeout` and `--auth` flags work the same way they do in `fastmcp list` and `fastmcp call`.
## What You Get
The generated script is a regular Python file — executable, editable, and yours. Here's what it looks like in practice:
```
$ python cli.py --help
Usage: weather-cli COMMAND
CLI for weather MCP server
Commands:
call-tool Call a tool on the server
list-tools List available tools.
list-resources List available resources.
read-resource Read a resource by URI.
list-prompts List available prompts.
get-prompt Get a prompt by name. Pass arguments as key=value pairs.
```
The `call-tool` subcommand is where the generated code lives. Each tool on the server becomes its own command:
```
$ python cli.py call-tool --help
Usage: weather-cli call-tool COMMAND
Call a tool on the server
Commands:
get_forecast Get the weather forecast for a city.
search_city Search for a city by name.
```
And each tool has typed parameters with help text pulled directly from the server's schema:
```
$ python cli.py call-tool get_forecast --help
Usage: weather-cli call-tool get_forecast [OPTIONS]
Get the weather forecast for a city.
Options:
--city [str] City name (required)
--days [int] Number of forecast days (default: 3)
```
Tool names are preserved exactly as the server defines them — underscores stay as underscores, so `call-tool get_forecast` matches what the server expects.
## Agent Skill
Alongside the CLI script, `generate-cli` also writes a `SKILL.md` file — a [Claude Code agent skill](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/skills) that documents the generated CLI. The skill includes every tool's exact invocation syntax, parameter flags with types and descriptions, and the utility commands, so an agent can use the CLI immediately without running `--help` or experimenting with flag names.
The skill is written to the same directory as the CLI script. For a weather server, it looks something like:
````markdown
---
name: "weather-cli"
description: "CLI for the weather MCP server. Call tools, list resources, and get prompts."
---
# weather CLI
## Tool Commands
### get_forecast
Get the weather forecast for a city.
```bash
uv run --with fastmcp python cli.py call-tool get_forecast --city <value> --days <value>
```
| Flag | Type | Required | Description |
|------|------|----------|-------------|
| `--city` | string | yes | City name |
| `--days` | integer | no | Number of forecast days |
````
To skip skill generation, pass `--no-skill`:
```bash
fastmcp generate-cli weather --no-skill
```
## How It Works
The generated script is a client, not a server. It doesn't bundle or embed the MCP server — it connects to it on every invocation. For URL-based servers, the server needs to be running. For stdio-based servers, the command specified in `CLIENT_SPEC` must be available on the system's `PATH`.
At the top of the generated file, a `CLIENT_SPEC` variable holds the resolved transport: either a URL string or a `StdioTransport` with the command and arguments baked in. Every invocation connects through this spec, so the script works without any external configuration.
### Parameter Handling
Parameters are mapped intelligently based on their complexity:
**Simple types** (`string`, `integer`, `number`, `boolean`) become typed Python parameters with clean flags:
```bash
python cli.py call-tool get_forecast --city London --days 3
```
**Arrays of simple types** (`array` with `string`/`integer`/`number`/`boolean` items) become `list[T]` parameters that accept multiple flags:
```bash
python cli.py call-tool tag_items --tags python --tags fastapi --tags mcp
```
**Complex types** (objects, nested arrays, or unions) accept JSON strings. The tool's `--help` displays the full JSON schema so you know exactly what structure to pass:
```bash
python cli.py call-tool create_user \
--name John \
--metadata '{"role": "admin", "dept": "engineering"}'
```
Required parameters are mandatory flags; optional ones default to their schema default or `None`. Empty values are filtered out before calling the server.
Beyond tool commands, the script includes generic commands that work regardless of what the server exposes: `list-tools`, `list-resources`, `read-resource`, `list-prompts`, and `get-prompt`. These connect to the server at runtime, so they always reflect the server's current state even if the tools have changed since generation.
## Editing the Output
The most common edit is changing `CLIENT_SPEC`. If you generated from a local dev server and want to point at production, just change the string. If you generated from a discovered name and want to pin the transport, replace it with an explicit URL or `StdioTransport`.
Beyond that, it's a regular Python file. You can add commands, change the output formatting, integrate it into a larger application, or strip out the parts you don't need. The helper functions (`_call_tool`, `_print_tool_result`) are thin wrappers around `fastmcp.Client` that are easy to adapt.
The generated script requires `fastmcp` as a dependency. If the script lives outside a project that already has fastmcp installed, `uv run` is the easiest way to run it without permanent installation:
```bash
uv run --with fastmcp python cli.py call-tool get_forecast --city London
```

16
docs/deployment/http.mdx
View file

@ -79,17 +79,17 @@ The ASGI approach shines in production environments where you need reliability a
### Custom Path
By default, your MCP server is accessible at `/mcp/` on your domain. You can customize this path to fit your URL structure or avoid conflicts with existing endpoints. This is particularly useful when integrating MCP into an existing application or following specific API conventions.
By default, your MCP server is accessible at `/mcp` on your domain. You can customize this path to fit your URL structure or avoid conflicts with existing endpoints. This is particularly useful when integrating MCP into an existing application or following specific API conventions.
```python
# Option 1: With mcp.run()
mcp.run(transport="http", host="0.0.0.0", port=8000, path="/api/mcp/")
mcp.run(transport="http", host="0.0.0.0", port=8000, path="/api/mcp")
# Option 2: With ASGI app
app = mcp.http_app(path="/api/mcp/")
app = mcp.http_app(path="/api/mcp")
```
Now your server is accessible at `http://localhost:8000/api/mcp/`.
Now your server is accessible at `http://localhost:8000/api/mcp`.
### Authentication
@ -345,7 +345,7 @@ def analyze(data: str) -> dict:
return {"result": f"Analyzed: {data}"}
# Create the ASGI app
mcp_app = mcp.http_app(path='/mcp')
mcp_app = mcp.http_app(path="/mcp")
# Create a Starlette app and mount the MCP server
app = Starlette(
@ -357,7 +357,7 @@ app = Starlette(
)
```
The MCP endpoint will be available at `/mcp-server/mcp/` of the resulting Starlette app.
The MCP endpoint will be available at `/mcp-server/mcp` of the resulting Starlette app.
<Warning>
For Streamable HTTP transport, you **must** pass the lifespan context from the FastMCP app to the resulting Starlette app, as nested lifespans are not recognized. Otherwise, the FastMCP server's session manager will not be properly initialized.
@ -376,7 +376,7 @@ from starlette.routing import Mount
mcp = FastMCP("MyServer")
# Create the ASGI app
mcp_app = mcp.http_app(path='/mcp')
mcp_app = mcp.http_app(path="/mcp")
# Create nested application structure
inner_app = Starlette(routes=[Mount("/inner", app=mcp_app)])
@ -386,7 +386,7 @@ app = Starlette(
)
```
In this setup, the MCP server is accessible at the `/outer/inner/mcp/` path.
In this setup, the MCP server is accessible at the `/outer/inner/mcp` path.
### FastAPI Integration

2
docs/deployment/running-server.mdx
View file

@ -240,7 +240,7 @@ if __name__ == "__main__":
mcp.run(transport="http") # Health check at http://localhost:8000/health
```
Custom routes are served by the same web server as your MCP endpoint. They're available at the root of your domain while the MCP endpoint is at `/mcp/`. For more complex web applications, consider [mounting your MCP server into a FastAPI or Starlette app](/deployment/http#integration-with-web-frameworks).
Custom routes are served by the same web server as your MCP endpoint. They're available at the root of your domain while the MCP endpoint is at `/mcp`. For more complex web applications, consider [mounting your MCP server into a FastAPI or Starlette app](/deployment/http#integration-with-web-frameworks).
## Alternative Initialization Patterns

29
docs/deployment/server-configuration.mdx
View file

@ -229,9 +229,10 @@ Environment variables are included in this section because they're runtime confi
<Expandable title="Deployment Fields">
<ParamField body="transport" type="string" default="stdio">
Protocol for client communication:
Protocol for client communication. `"http"` and `"streamable-http"` both select FastMCP's Streamable HTTP transport:
- `"stdio"`: Standard input/output for desktop clients
- `"http"`: Network-accessible HTTP server
- `"http"`: Network-accessible Streamable HTTP server
- `"streamable-http"`: Explicit alias for Streamable HTTP
- `"sse"`: Server-sent events
</ParamField>
@ -241,12 +242,12 @@ Environment variables are included in this section because they're runtime confi
- `"0.0.0.0"`: All network interfaces
</ParamField>
<ParamField body="port" type="integer" default="3000">
Port number for HTTP transport.
<ParamField body="port" type="integer" default="8000">
Port number for HTTP transport. If omitted, FastMCP uses the server runtime default.
</ParamField>
<ParamField body="path" type="string" default="/mcp/">
URL path for the MCP endpoint when using HTTP transport.
<ParamField body="path" type="string" default="/mcp">
URL path for the MCP endpoint when using HTTP transport. The default is `/mcp` for Streamable HTTP and `/sse` for SSE.
</ParamField>
<ParamField body="log_level" type="string" default="INFO">
@ -396,20 +397,20 @@ This flag tells FastMCP: "I already have the source code, skip any download/clon
Note: For filesystem sources (local Python files), this flag has no effect since they don't require preparation.
The configuration file works with all FastMCP commands:
The configuration file works with server-loading commands that explicitly accept FastMCP config files:
- **`run`** - Start the server in production mode
- **`dev`** - Launch with the Inspector UI for development
- **`dev inspector`** - Launch with the Inspector UI for development
- **`inspect`** - View server capabilities and configuration
- **`install`** - Install to Claude Desktop, Cursor, or other MCP clients
- **`install`** - Install to Claude Desktop, Cursor, or another MCP client
When no file argument is provided, FastMCP searches the current directory for `fastmcp.json`. This means you can simply navigate to your project directory and run `fastmcp run` to start your server with all its configured settings.
`run`, `dev inspector`, and `inspect` search the current directory for a file named exactly `fastmcp.json` when you don't pass a file argument, so you can navigate to your project directory and run `fastmcp run` to start your server with all its configured settings. `install` requires an explicit path to the config file — it never searches.
### CLI Override Behavior
Command-line arguments take precedence over configuration file values, allowing ad-hoc adjustments without modifying the file:
```bash
# Config specifies port 3000, CLI overrides to 8080
# Config specifies port 8000, CLI overrides to 8080
fastmcp run fastmcp.json --port 8080
# Config specifies stdio, CLI overrides to HTTP
@ -434,7 +435,7 @@ You can use different configuration files for different environments:
- `prod.fastmcp.json` - Production settings
- `test_fastmcp.json` - Test configuration
Any file with "fastmcp.json" in the name is recognized as a configuration file.
Only a file named exactly `fastmcp.json` is auto-detected when you omit the path. Other FastMCP configuration files can use any `.json` name, but you must pass them explicitly.
## Examples
@ -471,7 +472,7 @@ A configuration optimized for local development:
"type": "uv",
"python": "3.12",
"dependencies": ["fastmcp[dev]"],
"editable": "."
"editable": ["."]
},
// HOW should it run?
"deployment": {
@ -510,7 +511,7 @@ A production-ready configuration with full dependency management:
"transport": "http",
"host": "0.0.0.0",
"port": 3000,
"path": "/api/mcp/",
"path": "/api/mcp",
"log_level": "INFO",
"env": {
"ENV": "production",

4
docs/development/contributing.mdx
View file

@ -134,7 +134,7 @@ Tests are documentation that shows how features work. Good tests give reviewers
uv run pytest tests/server/ -v
# Run all tests before submitting PR
uv run pytest
uv run pytest -n auto
```
Every new feature needs tests. See the [Testing Guide](/development/tests) for patterns and requirements.
@ -166,7 +166,7 @@ just api-ref-all
#### Before Submitting
1. **Run all checks**: `uv run prek run --all-files && uv run pytest`
1. **Run all checks**: `uv run prek run --all-files && uv run pytest -n auto`
2. **Keep scope small**: One feature or fix per PR
3. **Write clear description**: Your PR description becomes permanent documentation
4. **Update docs**: Include documentation for API changes

2
docs/development/tests.mdx
View file

@ -14,7 +14,7 @@ Good tests are the foundation of reliable software. In FastMCP, we treat tests a
```bash
# Run all tests
uv run pytest
uv run pytest -n auto
# Run specific test file
uv run pytest tests/server/test_auth.py

851
docs/patterns/cli.mdx
View file

@ -1,851 +0,0 @@
---
title: FastMCP CLI
sidebarTitle: CLI
description: Learn how to use the FastMCP command-line interface
icon: terminal
---
import { VersionBadge } from "/snippets/version-badge.mdx"
FastMCP provides a command-line interface (CLI) that makes it easy to run, develop, and install your MCP servers. The CLI is automatically installed when you install FastMCP.
```bash
fastmcp --help
```
## Commands Overview
| Command | Purpose | Dependency Management |
| ------- | ------- | --------------------- |
| `list` | List tools on any MCP server | **Supports:** URLs, local files, MCPConfig JSON, stdio commands. **Deps:** N/A (connects to existing servers) |
| `call` | Call a tool on any MCP server | **Supports:** URLs, local files, MCPConfig JSON, stdio commands. **Deps:** N/A (connects to existing servers) |
| `run` | Run a FastMCP server directly | **Supports:** Local files, factory functions, URLs, fastmcp.json configs, MCP configs. **Deps:** Uses your local environment directly. With `--python`, `--with`, `--project`, or `--with-requirements`: Runs via `uv run` subprocess. With fastmcp.json: Automatically manages dependencies based on configuration |
| `dev` | Run a server with the MCP Inspector for testing | **Supports:** Local files and fastmcp.json configs. **Deps:** Always runs via `uv run` subprocess (never uses your local environment); dependencies must be specified or available in a uv-managed project. With fastmcp.json: Uses configured dependencies |
| `install` | Install a server in MCP client applications | **Supports:** Local files and fastmcp.json configs. **Deps:** Creates an isolated environment; dependencies must be explicitly specified with `--with` and/or `--with-editable`. With fastmcp.json: Uses configured dependencies |
| `inspect` | Generate a JSON report about a FastMCP server | **Supports:** Local files and fastmcp.json configs. **Deps:** Uses your current environment; you are responsible for ensuring all dependencies are available |
| `project prepare` | Create a persistent uv project from fastmcp.json environment config | **Supports:** fastmcp.json configs only. **Deps:** Creates a uv project directory with all dependencies pre-installed for reuse with `--project` flag |
| `auth cimd` | Create and validate CIMD documents for OAuth authentication | N/A |
| `version` | Display version information | N/A |
## `fastmcp list`
List tools available on any MCP server. This works with remote URLs, local Python files, MCPConfig JSON files, and arbitrary stdio commands. Together with `fastmcp call`, these commands are especially useful for giving LLMs that don't have built-in MCP support access to MCP tools via shell commands.
```bash
fastmcp list http://localhost:8000/mcp
fastmcp list server.py
fastmcp list mcp.json
fastmcp list --command 'npx -y @modelcontextprotocol/server-github'
```
By default, the output shows each tool's signature and description. Use `--input-schema` or `--output-schema` to include full JSON schemas, or `--json` for machine-readable output.
### Options
| Option | Flag | Description |
| ------ | ---- | ----------- |
| Command | `--command` | Connect to a stdio server command (e.g. `'npx -y @mcp/server'`) |
| Transport | `--transport`, `-t` | Force transport type for URL targets (`http` or `sse`) |
| Resources | `--resources` | Also list resources |
| Prompts | `--prompts` | Also list prompts |
| Input Schema | `--input-schema` | Show full input schemas |
| Output Schema | `--output-schema` | Show full output schemas |
| JSON | `--json` | Output as JSON |
| Timeout | `--timeout` | Connection timeout in seconds |
| Auth | `--auth` | Auth method: `oauth` (default for HTTP), a bearer token, or `none` to disable |
### Server Targets
The `<server>` argument accepts:
1. **URLs** — `http://` or `https://` endpoints. Uses Streamable HTTP by default; pass `--transport sse` for SSE servers.
2. **Python files** — `.py` files are run via `fastmcp run` automatically.
3. **MCPConfig JSON** — `.json` files with an `mcpServers` key are treated as multi-server configs.
4. **Stdio commands** — Use `--command` to connect to any MCP server via stdio (e.g. `npx`, `uvx`).
### Examples
```bash
# List tools on a remote server
fastmcp list http://localhost:8000/mcp
# List tools from a local Python file
fastmcp list server.py
# Include full input schemas
fastmcp list server.py --input-schema
# Machine-readable JSON
fastmcp list server.py --json
# SSE server
fastmcp list http://localhost:8000/mcp --transport sse
# Stdio command
fastmcp list --command 'npx -y @modelcontextprotocol/server-github'
# Include resources and prompts
fastmcp list server.py --resources --prompts
```
## `fastmcp call`
Call a tool on any MCP server. Arguments can be passed as `key=value` pairs, a single JSON object, or via `--input-json`.
```bash
fastmcp call server.py greet name=World
fastmcp call http://localhost:8000/mcp search query=hello limit=5
fastmcp call server.py create_item '{"name": "x", "tags": ["a", "b"]}'
```
Tool arguments are automatically coerced to the correct type based on the tool's input schema — string values like `limit=5` become integers when the schema expects one.
### Options
| Option | Flag | Description |
| ------ | ---- | ----------- |
| Command | `--command` | Connect to a stdio server command (e.g. `'npx -y @mcp/server'`) |
| Transport | `--transport`, `-t` | Force transport type for URL targets (`http` or `sse`) |
| Input JSON | `--input-json` | JSON string of tool arguments (merged with key=value args) |
| JSON | `--json` | Output raw JSON result |
| Timeout | `--timeout` | Connection timeout in seconds |
| Auth | `--auth` | Auth method: `oauth` (default for HTTP), a bearer token, or `none` to disable |
### Argument Passing
There are three ways to pass arguments:
**Key=value pairs** are the simplest for flat arguments. Values are coerced using the tool's JSON schema (strings become ints, bools, etc.):
```bash
fastmcp call server.py search query=hello limit=5 verbose=true
```
**A single JSON object** works when you have structured or nested arguments:
```bash
fastmcp call server.py create_item '{"name": "Widget", "tags": ["new", "sale"]}'
```
**`--input-json`** provides a base dict that key=value pairs can override:
```bash
fastmcp call server.py search --input-json '{"query": "hello", "limit": 5}' limit=10
```
### Examples
```bash
# Call a tool with simple args
fastmcp call server.py greet name=World
# Call with JSON object
fastmcp call server.py create '{"name": "x", "tags": ["a"]}'
# Get JSON output for scripting
fastmcp call server.py add a=3 b=4 --json
# Call a tool on a remote server
fastmcp call http://localhost:8000/mcp search query=hello
# Call via stdio command
fastmcp call --command 'npx -y @mcp/server' tool_name arg=value
# Disable OAuth for HTTP targets
fastmcp call http://localhost:8000/mcp search query=hello --auth none
```
<Tip>
If you call a tool that doesn't exist, FastMCP will suggest similar tool names. Use `fastmcp list` to see all available tools on a server.
</Tip>
## `fastmcp run`
Run a FastMCP server directly or proxy a remote server.
```bash
fastmcp run server.py
```
<Tip>
By default, this command runs the server directly in your current Python environment. You are responsible for ensuring all dependencies are available. When using `--python`, `--with`, `--project`, or `--with-requirements` options, it runs the server via `uv run` subprocess instead.
</Tip>
### Options
| Option | Flag | Description |
| ------ | ---- | ----------- |
| Transport | `--transport`, `-t` | Transport protocol to use (`stdio`, `http`, or `sse`) |
| Host | `--host` | Host to bind to when using http transport (default: 127.0.0.1) |
| Port | `--port`, `-p` | Port to bind to when using http transport (default: 8000) |
| Path | `--path` | Path to bind to when using http transport (default: `/mcp/` or `/sse/` for SSE) |
| Log Level | `--log-level`, `-l` | Log level (DEBUG, INFO, WARNING, ERROR, CRITICAL) |
| No Banner | `--no-banner` | Disable the startup banner display |
| Auto-Reload | `--reload` / `--no-reload` | Enable auto-reload on file changes (development mode) |
| Reload Directories | `--reload-dir` | Directories to watch for changes (can be used multiple times) |
| No Environment | `--skip-env` | Skip environment setup with uv (use when already in a uv environment) |
| Python Version | `--python` | Python version to use (e.g., 3.10, 3.11) |
| Additional Packages | `--with` | Additional packages to install (can be used multiple times) |
| Project Directory | `--project` | Run the command within the given project directory |
| Requirements File | `--with-requirements` | Requirements file to install dependencies from |
### Entrypoints
<VersionBadge version="2.3.5" />
The `fastmcp run` command supports the following entrypoints:
1. **[Inferred server instance](#inferred-server-instance)**: `server.py` - imports the module and looks for a FastMCP server instance named `mcp`, `server`, or `app`. Errors if no such object is found.
2. **[Explicit server entrypoint](#explicit-server-entrypoint)**: `server.py:custom_name` - imports and uses the specified server entrypoint
3. **[Factory function](#factory-function)**: `server.py:create_server` - calls the specified function (sync or async) to create a server instance
4. **[Remote server proxy](#remote-server-proxy)**: `https://example.com/mcp-server` - connects to a remote server and creates a **local proxy server**
5. **[FastMCP configuration file](#fastmcp-configuration)**: `fastmcp.json` - runs servers using FastMCP's declarative configuration format (auto-detects files in current directory)
6. **MCP configuration file**: `mcp.json` - runs servers defined in a standard MCP configuration file
<Warning>
Note: When using `fastmcp run` with a local file, it **completely ignores** the `if __name__ == "__main__"` block. This means:
- Any setup code in `__main__` will NOT run
- Server configuration in `__main__` is bypassed
- `fastmcp run` finds your server entrypoint/factory and runs it with its own transport settings
If you need setup code to run, use the **factory pattern** instead.
</Warning>
#### Inferred Server Instance
If you provide a path to a file, `fastmcp run` will load the file and look for a FastMCP server instance stored as a variable named `mcp`, `server`, or `app`. If no such object is found, it will raise an error.
For example, if you have a file called `server.py` with the following content:
```python server.py
from fastmcp import FastMCP
mcp = FastMCP("MyServer")
```
You can run it with:
```bash
fastmcp run server.py
```
#### Explicit Server Entrypoint
If your server is stored as a variable with a custom name, or you want to be explicit about which server to run, you can use the following syntax to load a specific server entrypoint:
```bash
fastmcp run server.py:custom_name
```
For example, if you have a file called `server.py` with the following content:
```python
from fastmcp import FastMCP
my_server = FastMCP("CustomServer")
@my_server.tool
def hello() -> str:
return "Hello from custom server!"
```
You can run it with:
```bash
fastmcp run server.py:my_server
```
#### Factory Function
<VersionBadge version="2.11.2" />
Since `fastmcp run` ignores the `if __name__ == "__main__"` block, you can use a factory function to run setup code before your server starts. Factory functions are called without any arguments and must return a FastMCP server instance. Both sync and async factory functions are supported.
The syntax for using a factory function is the same as for an explicit server entrypoint: `fastmcp run server.py:factory_fn`. FastMCP will automatically detect that you have identified a function rather than a server Instance
For example, if you have a file called `server.py` with the following content:
```python
from fastmcp import FastMCP
async def create_server() -> FastMCP:
mcp = FastMCP("MyServer")
@mcp.tool
def add(x: int, y: int) -> int:
return x + y
# Setup that runs with fastmcp run
tool = await mcp.get_tool("add")
tool.disable()
return mcp
```
You can run it with:
```bash
fastmcp run server.py:create_server
```
#### Remote Server Proxy
FastMCP run can also start a local proxy server that connects to a remote server. This is useful when you want to run a remote server locally for testing or development purposes, or to use with a client that doesn't support direct connections to remote servers.
To start a local proxy, you can use the following syntax:
```bash
fastmcp run https://example.com/mcp
```
#### FastMCP Configuration
<VersionBadge version="2.11.4" />
FastMCP supports declarative configuration through `fastmcp.json` files. When you run `fastmcp run` without arguments, it automatically looks for a `fastmcp.json` file in the current directory:
```bash
# Auto-detect fastmcp.json in current directory
fastmcp run
# Or explicitly specify a configuration file
fastmcp run my-config.fastmcp.json
```
The configuration file handles dependencies, environment variables, and transport settings. Command-line arguments override configuration file values:
```bash
# Override port from config file
fastmcp run fastmcp.json --port 8080
# Skip environment setup when already in a uv environment
fastmcp run fastmcp.json --skip-env
```
<Note>
The `--skip-env` flag is useful when:
- You're already in an activated virtual environment
- You're inside a Docker container with pre-installed dependencies
- You're in a uv-managed environment (prevents infinite recursion)
- You want to test the server without environment setup
</Note>
See [Server Configuration](/deployment/server-configuration) for detailed documentation on fastmcp.json.
#### MCP Configuration
FastMCP can also run servers defined in a standard MCP configuration file. This is useful when you want to run multiple servers from a single file, or when you want to use a client that doesn't support direct connections to remote servers.
To run a MCP configuration file, you can use the following syntax:
```bash
fastmcp run mcp.json
```
This will run all the servers defined in the file.
## `fastmcp dev`
The `dev` command group contains development tools for MCP servers.
### `fastmcp dev inspector`
Run a MCP server with the [MCP Inspector](https://github.com/modelcontextprotocol/inspector) for testing. Auto-reload is enabled by default, so your server automatically restarts when you save changes to source files.
```bash
fastmcp dev inspector server.py
```
<Tip>
This command always runs your server via `uv run` subprocess (never your local environment) to work with the MCP Inspector. Dependencies can be:
- Specified using `--with` and/or `--with-editable` options
- Defined in a `fastmcp.json` configuration file
- Available in a uv-managed project
When using `fastmcp.json`, the dev command automatically uses the configured dependencies.
</Tip>
<Warning>
The `dev inspector` command is a shortcut for testing a server over STDIO only. When the Inspector launches, you may need to:
1. Select "STDIO" from the transport dropdown
2. Connect manually
This command does not support HTTP testing. To test a server over Streamable HTTP or SSE:
1. Start your server manually with the appropriate transport using either the command line:
```bash
fastmcp run server.py --transport http
```
or by setting the transport in your code:
```bash
python server.py # Assuming your __main__ block sets Streamable HTTP transport
```
2. Open the MCP Inspector separately and connect to your running server
</Warning>
#### Options
| Option | Flag | Description |
| ------ | ---- | ----------- |
| Editable Package | `--with-editable`, `-e` | Directory containing pyproject.toml to install in editable mode |
| Additional Packages | `--with` | Additional packages to install (can be used multiple times) |
| Inspector Version | `--inspector-version` | Version of the MCP Inspector to use |
| UI Port | `--ui-port` | Port for the MCP Inspector UI |
| Server Port | `--server-port` | Port for the MCP Inspector Proxy server |
| Auto-Reload | `--reload` / `--no-reload` | Enable/disable auto-reload on file changes (enabled by default) |
| Reload Directories | `--reload-dir` | Directories to watch for changes (can be used multiple times) |
| Python Version | `--python` | Python version to use (e.g., 3.10, 3.11) |
| Project Directory | `--project` | Run the command within the given project directory |
| Requirements File | `--with-requirements` | Requirements file to install dependencies from |
#### Entrypoints
The `dev inspector` command supports local FastMCP server files and configuration:
1. **Inferred server instance**: `server.py` - imports the module and looks for a FastMCP server instance named `mcp`, `server`, or `app`. Errors if no such object is found.
2. **Explicit server entrypoint**: `server.py:custom_name` - imports and uses the specified server entrypoint
3. **Factory function**: `server.py:create_server` - calls the specified function (sync or async) to create a server instance
4. **FastMCP configuration**: `fastmcp.json` - uses FastMCP's declarative configuration (auto-detects in current directory)
<Warning>
The `dev inspector` command **only supports local files and fastmcp.json** - no URLs, remote servers, or standard MCP configuration files.
</Warning>
**Examples**
```bash
# Run dev server with editable mode and additional packages
fastmcp dev inspector server.py -e . --with pandas --with matplotlib
# Run dev server with fastmcp.json configuration (auto-detects)
fastmcp dev inspector
# Run dev server with explicit fastmcp.json file
fastmcp dev inspector dev.fastmcp.json
# Run dev server with specific Python version
fastmcp dev inspector server.py --python 3.11
# Run dev server with requirements file
fastmcp dev inspector server.py --with-requirements requirements.txt
# Run dev server within a specific project directory
fastmcp dev inspector server.py --project /path/to/project
```
## `fastmcp install`
<VersionBadge version="2.10.3" />
Install a MCP server in MCP client applications. FastMCP currently supports the following clients:
- **Claude Code** - Installs via Claude Code's built-in MCP management system
- **Claude Desktop** - Installs via direct configuration file modification
- **Cursor** - Installs via deeplink that opens Cursor for user confirmation
- **Gemini CLI** - Installs via Gemini CLI's built-in MCP management system
- **Goose** - Installs via deeplink that opens Goose for user confirmation (uses `uvx`)
- **MCP JSON** - Generates standard MCP JSON configuration for manual use
- **Stdio** - Outputs the shell command to run a server over stdio transport
```bash
fastmcp install claude-code server.py
fastmcp install claude-desktop server.py
fastmcp install cursor server.py
fastmcp install gemini-cli server.py
fastmcp install goose server.py
fastmcp install mcp-json server.py
fastmcp install stdio server.py
```
Note that for security reasons, MCP clients usually run every server in a completely isolated environment. Therefore, all dependencies must be explicitly specified using the `--with` and/or `--with-editable` options (following `uv` conventions) or by attaching them to your server in code via the `dependencies` parameter. You should not assume that the MCP server will have access to your local environment.
<Warning>
**`uv` must be installed and available in your system PATH**. Both Claude Desktop and Cursor run in isolated environments and need `uv` to manage dependencies. On macOS, install `uv` globally with Homebrew for Claude Desktop compatibility: `brew install uv`.
</Warning>
<Note>
**Python Version Considerations**: The install commands now support the `--python` option to specify a Python version directly. You can also use `--project` to run within a specific project directory or `--with-requirements` to install dependencies from a requirements file.
</Note>
<Tip>
**FastMCP `install` commands focus on local server files with STDIO transport.** For remote servers running with HTTP or SSE transport, use your client's native configuration - FastMCP's value is simplifying the complex local setup with dependencies and `uv` commands.
</Tip>
### Options
| Option | Flag | Description |
| ------ | ---- | ----------- |
| Server Name | `--server-name`, `-n` | Custom name for the server (defaults to server's name attribute or file name) |
| Editable Package | `--with-editable`, `-e` | Directory containing pyproject.toml to install in editable mode |
| Additional Packages | `--with` | Additional packages to install (can be used multiple times) |
| Environment Variables | `--env` | Environment variables in KEY=VALUE format (can be used multiple times) |
| Environment File | `--env-file`, `-f` | Load environment variables from a .env file |
| Python Version | `--python` | Python version to use (e.g., 3.10, 3.11) |
| Project Directory | `--project` | Run the command within the given project directory |
| Requirements File | `--with-requirements` | Requirements file to install dependencies from |
### Entrypoints
The `install` command supports local FastMCP server files and configuration:
1. **Inferred server instance**: `server.py` - imports the module and looks for a FastMCP server instance named `mcp`, `server`, or `app`. Errors if no such object is found.
2. **Explicit server entrypoint**: `server.py:custom_name` - imports and uses the specified server entrypoint
3. **Factory function**: `server.py:create_server` - calls the specified function (sync or async) to create a server instance
4. **FastMCP configuration**: `fastmcp.json` - uses FastMCP's declarative configuration with dependencies and settings
<Note>
Factory functions are particularly useful for install commands since they allow setup code to run that would otherwise be ignored when the MCP client runs your server. When using fastmcp.json, dependencies are automatically handled.
</Note>
<Warning>
The `install` command **only supports local files and fastmcp.json** - no URLs, remote servers, or standard MCP configuration files. For remote servers, use your MCP client's native configuration.
</Warning>
**Examples**
```bash
# Auto-detects server entrypoint (looks for 'mcp', 'server', or 'app')
fastmcp install claude-desktop server.py
# Install with fastmcp.json configuration (auto-detects)
fastmcp install claude-desktop
# Install with explicit fastmcp.json file
fastmcp install claude-desktop my-config.fastmcp.json
# Uses specific server entrypoint
fastmcp install claude-desktop server.py:my_server
# With custom name and dependencies
fastmcp install claude-desktop server.py:my_server --server-name "My Analysis Server" --with pandas
# Install in Claude Code with environment variables
fastmcp install claude-code server.py --env API_KEY=secret --env DEBUG=true
# Install in Cursor with environment variables
fastmcp install cursor server.py --env API_KEY=secret --env DEBUG=true
# Install with environment file
fastmcp install cursor server.py --env-file .env
# Install in Goose (uses uvx deeplink)
fastmcp install goose server.py --with pandas
# Install with specific Python version
fastmcp install claude-desktop server.py --python 3.11
# Install with requirements file
fastmcp install claude-code server.py --with-requirements requirements.txt
# Install within a project directory
fastmcp install cursor server.py --project /path/to/project
# Generate MCP JSON configuration
fastmcp install mcp-json server.py --name "My Server" --with pandas
# Copy JSON configuration to clipboard
fastmcp install mcp-json server.py --copy
# Output the stdio command for running a server
fastmcp install stdio server.py
# Output the stdio command from a fastmcp.json (includes configured dependencies)
fastmcp install stdio fastmcp.json
# Copy the stdio command to clipboard
fastmcp install stdio server.py --copy
```
### MCP JSON Generation
The `mcp-json` subcommand generates standard MCP JSON configuration that can be used with any MCP-compatible client. This is useful when:
- Working with MCP clients not directly supported by FastMCP
- Creating configuration for CI/CD environments
- Sharing server configurations with others
- Integration with custom tooling
The generated JSON follows the standard MCP server configuration format used by Claude Desktop, VS Code, Cursor, and other MCP clients, with the server name as the root key:
```json
{
"server-name": {
"command": "uv",
"args": [
"run",
"--with",
"fastmcp",
"fastmcp",
"run",
"/path/to/server.py"
],
"env": {
"API_KEY": "value"
}
}
}
```
<Note>
To use this configuration with your MCP client, you'll typically need to add it to the client's `mcpServers` object. Consult your client's documentation for any specific configuration requirements or formatting needs.
</Note>
**Options specific to mcp-json:**
| Option | Flag | Description |
| ------ | ---- | ----------- |
| Copy to Clipboard | `--copy` | Copy configuration to clipboard instead of printing to stdout |
### Stdio Command
The `stdio` subcommand outputs the shell command an MCP host uses to start your server over stdio transport. Use it when you need a ready-to-paste `uv run --with fastmcp fastmcp run ...` command for a tool or script without a dedicated install target.
```bash
# Print the command to stdout
fastmcp install stdio server.py
# Output: uv run --with fastmcp fastmcp run /absolute/path/to/server.py
```
When you pass a `fastmcp.json`, FastMCP automatically includes dependencies from the configuration:
```bash
fastmcp install stdio fastmcp.json
# Output: uv run --with fastmcp --with pillow --with 'qrcode[pil]>=8.0' fastmcp run /absolute/path/to/qr_server.py
```
Use `--copy` to send the command directly to your clipboard:
```bash
fastmcp install stdio server.py --copy
# ✓ Command copied to clipboard
```
**Options specific to stdio:**
| Option | Flag | Description |
| ------ | ---- | ----------- |
| Copy to Clipboard | `--copy` | Copy command to clipboard instead of printing to stdout |
## `fastmcp inspect`
<VersionBadge version="2.9.0" />
Inspect a FastMCP server to view summary information or generate a detailed JSON report.
```bash
# Show text summary
fastmcp inspect server.py
# Output FastMCP JSON to stdout
fastmcp inspect server.py --format fastmcp
# Save MCP JSON to file (format required with -o)
fastmcp inspect server.py --format mcp -o manifest.json
```
### Options
| Option | Flag | Description |
| ------ | ---- | ----------- |
| Format | `--format`, `-f` | Output format: `fastmcp` (FastMCP-specific) or `mcp` (MCP protocol). Required when using `-o` |
| Output File | `--output`, `-o` | Save JSON report to file instead of stdout. Requires `--format` |
### Output Formats
#### FastMCP Format (`--format fastmcp`)
The default and most comprehensive format, includes all FastMCP-specific metadata:
- Server name, instructions, and version
- FastMCP version and MCP version
- Tool tags and enabled status
- Output schemas for tools
- Annotations and custom metadata
- Uses snake_case field names
- **Use this for**: Complete server introspection and debugging FastMCP servers
#### MCP Protocol Format (`--format mcp`)
Shows exactly what MCP clients will see via the protocol:
- Only includes standard MCP protocol fields
- Matches output from `client.list_tools()`, `client.list_prompts()`, etc.
- Uses camelCase field names (e.g., `inputSchema`)
- Excludes FastMCP-specific fields like tags and enabled status
- **Use this for**: Debugging client visibility and ensuring MCP compatibility
### Entrypoints
The `inspect` command supports local FastMCP server files and configuration:
1. **Inferred server instance**: `server.py` - imports the module and looks for a FastMCP server instance named `mcp`, `server`, or `app`. Errors if no such object is found.
2. **Explicit server entrypoint**: `server.py:custom_name` - imports and uses the specified server entrypoint
3. **Factory function**: `server.py:create_server` - calls the specified function (sync or async) to create a server instance
4. **FastMCP configuration**: `fastmcp.json` - inspects servers defined with FastMCP's declarative configuration
<Warning>
The `inspect` command **only supports local files and fastmcp.json** - no URLs, remote servers, or standard MCP configuration files.
</Warning>
### Examples
```bash
# Show text summary (no JSON output)
fastmcp inspect server.py
# Output:
# Server: MyServer
# Instructions: A helpful MCP server
# Version: 1.0.0
#
# Components:
# Tools: 5
# Prompts: 2
# Resources: 3
# Templates: 1
#
# Environment:
# FastMCP: 2.0.0
# MCP: 1.0.0
#
# Use --format [fastmcp|mcp] for complete JSON output
# Output FastMCP format to stdout
fastmcp inspect server.py --format fastmcp
# Specify server entrypoint
fastmcp inspect server.py:my_server
# Output MCP protocol format to stdout
fastmcp inspect server.py --format mcp
# Save to file (format required)
fastmcp inspect server.py --format fastmcp -o server-manifest.json
# Save MCP format with custom server object
fastmcp inspect server.py:my_server --format mcp -o mcp-manifest.json
# Error: format required with output file
fastmcp inspect server.py -o output.json
# Error: --format is required when using -o/--output
```
## `fastmcp project prepare`
Create a persistent uv project directory from a fastmcp.json file's environment configuration. This allows you to pre-install all dependencies once and reuse them with the `--project` flag.
```bash
fastmcp project prepare fastmcp.json --output-dir ./env
```
### Options
| Option | Flag | Description |
| ------ | ---- | ----------- |
| Output Directory | `--output-dir` | **Required.** Directory where the persistent uv project will be created |
### Usage Pattern
```bash
# Step 1: Prepare the environment (installs dependencies)
fastmcp project prepare fastmcp.json --output-dir ./my-env
# Step 2: Run using the prepared environment (fast, no dependency installation)
fastmcp run fastmcp.json --project ./my-env
```
The prepare command creates a uv project with:
- A `pyproject.toml` containing all dependencies from the fastmcp.json
- A `.venv` with all packages pre-installed
- A `uv.lock` file for reproducible environments
This is useful when you want to separate environment setup from server execution, such as in deployment scenarios where dependencies are installed once and the server is run multiple times.
## `fastmcp auth`
<VersionBadge version="3.0.0" />
Authentication-related utilities and configuration commands.
### `fastmcp auth cimd create`
Generate a CIMD (Client ID Metadata Document) for hosting. This creates a JSON document that you can host at an HTTPS URL to use as your OAuth client identity.
```bash
fastmcp auth cimd create --name "My App" --redirect-uri "http://localhost:*/callback"
```
#### Options
| Option | Flag | Description |
| ------ | ---- | ----------- |
| Name | `--name` | **Required.** Human-readable name of the client application |
| Redirect URI | `--redirect-uri` | **Required.** Allowed redirect URIs (can specify multiple) |
| Client URI | `--client-uri` | URL of the client's home page |
| Logo URI | `--logo-uri` | URL of the client's logo image |
| Scope | `--scope` | Space-separated list of scopes the client may request |
| Output | `--output`, `-o` | Output file path (default: stdout) |
| Pretty | `--pretty` | Pretty-print JSON output (default: true) |
#### Example
```bash
# Generate document to stdout
fastmcp auth cimd create \
--name "My Production App" \
--redirect-uri "http://localhost:*/callback" \
--redirect-uri "https://myapp.example.com/callback" \
--client-uri "https://myapp.example.com" \
--scope "read write"
# Save to file
fastmcp auth cimd create \
--name "My App" \
--redirect-uri "http://localhost:*/callback" \
--output client.json
```
The generated document includes a placeholder `client_id` that you must update to match the URL where you'll host the document before deploying.
### `fastmcp auth cimd validate`
Validate a hosted CIMD document by fetching it from its URL and checking that it conforms to the CIMD specification.
```bash
fastmcp auth cimd validate https://myapp.example.com/oauth/client.json
```
#### Options
| Option | Flag | Description |
| ------ | ---- | ----------- |
| Timeout | `--timeout`, `-t` | HTTP request timeout in seconds (default: 10) |
The validator checks:
- The URL is a valid CIMD URL (HTTPS with non-root path)
- The document is valid JSON and conforms to the CIMD schema
- The `client_id` field in the document matches the URL
- No shared-secret authentication methods are used
On success, it displays the document details:
```
→ Fetching https://myapp.example.com/oauth/client.json...
✓ Valid CIMD document
Document details:
client_id: https://myapp.example.com/oauth/client.json
client_name: My App
token_endpoint_auth_method: none
redirect_uris:
• http://localhost:*/callback
```
## `fastmcp version`
Display version information about FastMCP and related components.
```bash
fastmcp version
```
### Options
| Option | Flag | Description |
| ------ | ---- | ----------- |
| Copy to Clipboard | `--copy` | Copy version information to clipboard |

8
docs/patterns/contrib.mdx
View file

@ -30,12 +30,12 @@ from fastmcp.contrib import my_module
## Contributing
We welcome contributions to the `contrib` package! If you have a module that extends FastMCP in a useful way, consider contributing it:
Contrib modules are accepted selectively. Before opening a PR, first open an issue with the problem, intended maintenance model, and why the pattern belongs in-repo instead of a standalone package. If maintainers agree it belongs in `contrib`, prepare the module with:
1. Create a new directory in `fastmcp_slim/fastmcp/contrib/` for your module
3. Add proper tests for your module in `tests/contrib/`
2. Include comprehensive documentation in a README.md file, including usage and examples, as well as any additional dependencies or installation instructions
5. Submit a pull request
2. Add proper tests for your module in `tests/contrib/`
3. Include comprehensive documentation in a README.md file, including usage and examples, as well as any additional dependencies or installation instructions
4. Submit a focused pull request linked to the maintainer-approved issue
The ideal contrib module:
- Solves a specific use case or integration need

104
docs/patterns/testing.mdx
View file

@ -1,104 +0,0 @@
---
title: Testing your FastMCP Server
sidebarTitle: Testing
description: How to test your FastMCP server.
icon: vial
---
The best way to ensure a reliable and maintainable FastMCP Server is to test it! The FastMCP Client combined with Pytest provides a simple and powerful way to test your FastMCP servers.
## Prerequisites
Testing FastMCP servers requires `pytest-asyncio` to handle async test functions and fixtures. Install it as a development dependency:
```bash
pip install pytest-asyncio
```
We recommend configuring pytest to automatically handle async tests by setting the asyncio mode to `auto` in your `pyproject.toml`:
```toml
[tool.pytest.ini_options]
asyncio_mode = "auto"
```
This eliminates the need to decorate every async test with `@pytest.mark.asyncio`.
## Testing with Pytest Fixtures
Using Pytest Fixtures, you can wrap your FastMCP Server in a Client instance that makes interacting with your server fast and easy. This is especially useful when building your own MCP Servers and enables a tight development loop by allowing you to avoid using a separate tool like MCP Inspector during development:
```python
import pytest
from fastmcp.client import Client
from fastmcp.client.transports import FastMCPTransport
from my_project.main import mcp
@pytest.fixture
async def main_mcp_client():
async with Client(transport=mcp) as mcp_client:
yield mcp_client
async def test_list_tools(main_mcp_client: Client[FastMCPTransport]):
list_tools = await main_mcp_client.list_tools()
assert len(list_tools) == 5
```
We recommend the [inline-snapshot library](https://github.com/15r10nk/inline-snapshot) for asserting complex data structures coming from your MCP Server. This library allows you to write tests that are easy to read and understand, and are also easy to update when the data structure changes.
```python
from inline_snapshot import snapshot
async def test_list_tools(main_mcp_client: Client[FastMCPTransport]):
list_tools = await main_mcp_client.list_tools()
assert list_tools == snapshot()
```
Simply run `pytest --inline-snapshot=fix,create` to fill in the `snapshot()` with actual data.
<Tip>
For values that change you can leverage the [dirty-equals](https://github.com/samuelcolvin/dirty-equals) library to perform flexible equality assertions on dynamic or non-deterministic values.
</Tip>
Using the pytest `parametrize` decorator, you can easily test your tools with a wide variety of inputs.
```python
import pytest
from my_project.main import mcp
from fastmcp.client import Client
from fastmcp.client.transports import FastMCPTransport
@pytest.fixture
async def main_mcp_client():
async with Client(mcp) as client:
yield client
@pytest.mark.parametrize(
"first_number, second_number, expected",
[
(1, 2, 3),
(2, 3, 5),
(3, 4, 7),
],
)
async def test_add(
first_number: int,
second_number: int,
expected: int,
main_mcp_client: Client[FastMCPTransport],
):
result = await main_mcp_client.call_tool(
name="add", arguments={"x": first_number, "y": second_number}
)
assert result.data is not None
assert isinstance(result.data, int)
assert result.data == expected
```
<Tip>
The [FastMCP Repository contains thousands of tests](https://github.com/PrefectHQ/fastmcp/tree/main/tests) for the FastMCP Client and Server. Everything from connecting to remote MCP servers, to testing tools, resources, and prompts is covered, take a look for inspiration!
</Tip>

2
examples/testing_demo/README.md
View file

@ -81,4 +81,4 @@ uv run fastmcp inspect server.py
## Learning More
For detailed information about testing FastMCP servers, see the [Testing Documentation](../../docs/patterns/testing.mdx).
For detailed information about testing FastMCP servers, see the [Testing Documentation](../../docs/servers/testing.mdx).

2
fastmcp_slim/fastmcp/cli/cli.py
View file

@ -435,7 +435,7 @@ async def run(
str | None,
cyclopts.Parameter(
"--path",
help="The route path for the server (default: /mcp/ for http transport, /sse/ for sse transport)",
help="The route path for the server (default: /mcp for http transport, /sse for sse transport)",
),
] = None,
log_level: Annotated[