ceos/fastmcp
1
0
Fork 0
mirror of https://github.com/PrefectHQ/fastmcp.git synced 2026-08-21 21:14:17 +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 |