Skip to content

Commit 8bc3136

Browse files
jlowinjlowin
authored
Restructure docs navigation: CLI section, Composition, More (#3361)
* WIP: Move mounting docs to servers/composition, remove deprecated import_server content * WIP: Add CLI section under More, move testing to Features, restructure nav * WIP: Rename querying to client, remove factory functions from CLI overview * WIP: Promote CLI to top-level section, move Upgrading to More * WIP: Rename CLI installing page to install-mcp * WIP * Add Google Gemini sampling handler docs, fix version badges
1 parent 8a356ad commit 8bc3136

21 files changed

Lines changed: 1020 additions & 163 deletions

‎docs/cli/auth.mdx‎

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
---
2+
title: Auth Utilities
3+
sidebarTitle: Auth
4+
description: Create and validate CIMD documents for OAuth
5+
icon: key
6+
---
7+
8+
import { VersionBadge } from '/snippets/version-badge.mdx'
9+
10+
<VersionBadge version="3.0.0" />
11+
12+
The `fastmcp auth` commands help with CIMD (Client ID Metadata Document) management — part of MCP's OAuth authentication flow. A CIMD is a JSON document you host at an HTTPS URL to identify your client application to MCP servers.
13+
14+
## Creating a CIMD
15+
16+
`fastmcp auth cimd create` generates a CIMD document:
17+
18+
```bash
19+
fastmcp auth cimd create \
20+
--name "My App" \
21+
--redirect-uri "http://localhost:*/callback"
22+
```
23+
24+
```json
25+
{
26+
"client_id": "https://your-domain.com/oauth/client.json",
27+
"client_name": "My App",
28+
"redirect_uris": ["http://localhost:*/callback"],
29+
"token_endpoint_auth_method": "none"
30+
}
31+
```
32+
33+
The generated document includes a placeholder `client_id` — update it to match the URL where you'll host the document before deploying.
34+
35+
### Options
36+
37+
| Option | Flag | Description |
38+
| ------ | ---- | ----------- |
39+
| Name | `--name` | **Required.** Human-readable client name |
40+
| Redirect URI | `--redirect-uri` | **Required.** Allowed redirect URIs (repeatable) |
41+
| Client URI | `--client-uri` | Client's home page URL |
42+
| Logo URI | `--logo-uri` | Client's logo URL |
43+
| Scope | `--scope` | Space-separated list of scopes |
44+
| Output | `--output`, `-o` | Save to file (default: stdout) |
45+
| Pretty | `--pretty` | Pretty-print JSON (default: true) |
46+
47+
### Example
48+
49+
```bash
50+
fastmcp auth cimd create \
51+
--name "My Production App" \
52+
--redirect-uri "http://localhost:*/callback" \
53+
--redirect-uri "https://myapp.example.com/callback" \
54+
--client-uri "https://myapp.example.com" \
55+
--scope "read write" \
56+
--output client.json
57+
```
58+
59+
## Validating a CIMD
60+
61+
`fastmcp auth cimd validate` fetches a hosted CIMD and verifies it conforms to the spec:
62+
63+
```bash
64+
fastmcp auth cimd validate https://myapp.example.com/oauth/client.json
65+
```
66+
67+
The validator checks that the URL is valid (HTTPS, non-root path), the document is valid JSON, the `client_id` matches the URL, and no shared-secret auth methods are used.
68+
69+
On success:
70+
71+
```
72+
→ Fetching https://myapp.example.com/oauth/client.json...
73+
✓ Valid CIMD document
74+
75+
Document details:
76+
client_id: https://myapp.example.com/oauth/client.json
77+
client_name: My App
78+
token_endpoint_auth_method: none
79+
redirect_uris:
80+
• http://localhost:*/callback
81+
```
82+
83+
| Option | Flag | Description |
84+
| ------ | ---- | ----------- |
85+
| Timeout | `--timeout`, `-t` | HTTP request timeout in seconds (default: 10) |

‎docs/cli/client.mdx‎

Lines changed: 140 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,140 @@
1+
---
2+
title: Client Commands
3+
sidebarTitle: Client
4+
description: List tools, call them, and discover configured servers
5+
icon: satellite-dish
6+
---
7+
8+
import { VersionBadge } from '/snippets/version-badge.mdx'
9+
10+
<VersionBadge version="3.0.0" />
11+
12+
The CLI can act as an MCP client — connecting to any server (local or remote) to list what it exposes and call its tools directly. This is useful for development, debugging, scripting, and giving shell-capable LLM agents access to MCP servers.
13+
14+
## Listing Tools
15+
16+
`fastmcp list` connects to a server and prints its tools as function signatures, showing parameter names, types, and descriptions at a glance:
17+
18+
```bash
19+
fastmcp list http://localhost:8000/mcp
20+
fastmcp list server.py
21+
fastmcp list weather # name-based resolution
22+
```
23+
24+
When you need the full JSON Schema for a tool's inputs or outputs — for understanding nested objects, enum constraints, or complex types — opt in with `--input-schema` or `--output-schema`:
25+
26+
```bash
27+
fastmcp list server.py --input-schema
28+
```
29+
30+
### Resources and Prompts
31+
32+
By default, only tools are shown. Add `--resources` or `--prompts` to include those:
33+
34+
```bash
35+
fastmcp list server.py --resources --prompts
36+
```
37+
38+
### Machine-Readable Output
39+
40+
The `--json` flag switches to structured JSON with full schemas included. This is the format to use when feeding tool definitions to an LLM or building automation:
41+
42+
```bash
43+
fastmcp list server.py --json
44+
```
45+
46+
### Options
47+
48+
| Option | Flag | Description |
49+
| ------ | ---- | ----------- |
50+
| Command | `--command` | Connect via stdio (e.g., `'npx -y @mcp/server'`) |
51+
| Transport | `--transport`, `-t` | Force `http` or `sse` for URL targets |
52+
| Resources | `--resources` | Include resources in output |
53+
| Prompts | `--prompts` | Include prompts in output |
54+
| Input Schema | `--input-schema` | Show full input schemas |
55+
| Output Schema | `--output-schema` | Show full output schemas |
56+
| JSON | `--json` | Structured JSON output |
57+
| Timeout | `--timeout` | Connection timeout in seconds |
58+
| Auth | `--auth` | `oauth` (default for HTTP), a bearer token, or `none` |
59+
60+
## Calling Tools
61+
62+
`fastmcp call` invokes a single tool on a server. Pass arguments as `key=value` pairs — the CLI fetches the tool's schema and coerces your string values to the right types automatically:
63+
64+
```bash
65+
fastmcp call server.py greet name=World
66+
fastmcp call http://localhost:8000/mcp search query=hello limit=5
67+
```
68+
69+
Type coercion is schema-driven: `"5"` becomes the integer `5` when the schema expects an integer. Booleans accept `true`/`false`, `yes`/`no`, and `1`/`0`. Arrays and objects are parsed as JSON.
70+
71+
### Complex Arguments
72+
73+
For tools with nested or structured parameters, `key=value` syntax gets awkward. Pass a single JSON object instead:
74+
75+
```bash
76+
fastmcp call server.py create_item '{"name": "Widget", "tags": ["sale"], "metadata": {"color": "blue"}}'
77+
```
78+
79+
Or use `--input-json` to provide a base dictionary, then override individual keys with `key=value` pairs:
80+
81+
```bash
82+
fastmcp call server.py search --input-json '{"query": "hello", "limit": 5}' limit=10
83+
```
84+
85+
### Error Handling
86+
87+
If you misspell a tool name, the CLI suggests corrections via fuzzy matching. Missing required arguments produce a clear message with the tool's signature as a reminder. Tool execution errors are printed with a non-zero exit code, making the CLI straightforward to use in scripts.
88+
89+
### Structured Output
90+
91+
`--json` emits the raw result including content blocks, error status, and structured content:
92+
93+
```bash
94+
fastmcp call server.py get_weather city=London --json
95+
```
96+
97+
### Interactive Elicitation
98+
99+
Some tools request additional input during execution through MCP's elicitation mechanism. When this happens, the CLI prompts you in the terminal — showing each field's name, type, and whether it's required. You can type `decline` to skip a question or `cancel` to abort the call entirely.
100+
101+
### Options
102+
103+
| Option | Flag | Description |
104+
| ------ | ---- | ----------- |
105+
| Command | `--command` | Connect via stdio |
106+
| Transport | `--transport`, `-t` | Force `http` or `sse` |
107+
| Input JSON | `--input-json` | Base arguments as JSON (merged with `key=value`) |
108+
| JSON | `--json` | Raw JSON output |
109+
| Timeout | `--timeout` | Connection timeout in seconds |
110+
| Auth | `--auth` | `oauth`, a bearer token, or `none` |
111+
112+
## Discovering Configured Servers
113+
114+
`fastmcp discover` scans your machine for MCP servers configured in editors and tools. It checks:
115+
116+
- **Claude Desktop** — `claude_desktop_config.json`
117+
- **Claude Code** — `~/.claude.json`
118+
- **Cursor** — `.cursor/mcp.json` (walks up from current directory)
119+
- **Gemini CLI** — `~/.gemini/settings.json`
120+
- **Goose** — `~/.config/goose/config.yaml`
121+
- **Project** — `./mcp.json` in the current directory
122+
123+
```bash
124+
fastmcp discover
125+
```
126+
127+
The output groups servers by source, showing each server's name and transport. Filter by source or get machine-readable output:
128+
129+
```bash
130+
fastmcp discover --source claude-code
131+
fastmcp discover --source cursor --source gemini --json
132+
```
133+
134+
Any server that appears here can be used by name with `list`, `call`, and other commands — so you can go from "I have a server in Claude Code" to querying it without copying URLs or paths.
135+
136+
## LLM Agent Integration
137+
138+
For LLM agents that can execute shell commands but don't have native MCP support, the CLI provides a clean bridge. The agent calls `fastmcp list --json` to discover available tools with full schemas, then `fastmcp call --json` to invoke them with structured results.
139+
140+
Because the CLI handles connection management, transport selection, and type coercion internally, the agent doesn't need to understand MCP protocol details — it just reads JSON and constructs shell commands.

‎docs/cli/generate-cli.mdx‎

Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
1+
---
2+
title: Generate CLI
3+
sidebarTitle: Generate CLI
4+
description: Scaffold a standalone typed CLI from any MCP server
5+
icon: wand-magic-sparkles
6+
---
7+
8+
import { VersionBadge } from '/snippets/version-badge.mdx'
9+
10+
<VersionBadge version="3.0.0" />
11+
12+
`fastmcp list` and `fastmcp call` are general-purpose — you always specify the server, the tool name, and the arguments from scratch. `fastmcp generate-cli` goes further: it connects to a server, reads its tool 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 hand-written for that specific server.
13+
14+
MCP tool schemas already contain everything a CLI framework needs — parameter names, types, descriptions, required/optional status, and defaults. `generate-cli` maps that 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.
15+
16+
## Generating a Script
17+
18+
Point the command at any [server target](/cli/overview#server-targets) and it writes a CLI script:
19+
20+
```bash
21+
fastmcp generate-cli weather
22+
fastmcp generate-cli http://localhost:8000/mcp
23+
fastmcp generate-cli server.py my_weather_cli.py
24+
```
25+
26+
The second positional argument sets the output path (defaults to `cli.py`). If the file already exists, pass `-f` to overwrite:
27+
28+
```bash
29+
fastmcp generate-cli weather -f
30+
```
31+
32+
## What You Get
33+
34+
The generated script is a regular Python file — executable, editable, and yours:
35+
36+
```
37+
$ python cli.py call-tool --help
38+
Usage: weather-cli call-tool COMMAND
39+
40+
Call a tool on the server
41+
42+
Commands:
43+
get_forecast Get the weather forecast for a city.
44+
search_city Search for a city by name.
45+
```
46+
47+
Each tool has typed parameters with help text pulled directly from the server's schema:
48+
49+
```
50+
$ python cli.py call-tool get_forecast --help
51+
Usage: weather-cli call-tool get_forecast [OPTIONS]
52+
53+
Get the weather forecast for a city.
54+
55+
Options:
56+
--city [str] City name (required)
57+
--days [int] Number of forecast days (default: 3)
58+
```
59+
60+
Beyond tool commands, the script includes generic MCP operations — `list-tools`, `list-resources`, `read-resource`, `list-prompts`, and `get-prompt` — that always reflect the server's current state, even if tools have changed since generation.
61+
62+
## Parameter Handling
63+
64+
Parameters are mapped based on their JSON Schema type:
65+
66+
**Simple types** (`string`, `integer`, `number`, `boolean`) become typed flags:
67+
68+
```bash
69+
python cli.py call-tool get_forecast --city London --days 3
70+
```
71+
72+
**Arrays of simple types** become repeatable flags:
73+
74+
```bash
75+
python cli.py call-tool tag_items --tags python --tags fastapi --tags mcp
76+
```
77+
78+
**Complex types** (objects, nested arrays, unions) accept JSON strings. The `--help` output shows the full schema so you know what structure to pass:
79+
80+
```bash
81+
python cli.py call-tool create_user \
82+
--name John \
83+
--metadata '{"role": "admin", "dept": "engineering"}'
84+
```
85+
86+
## Agent Skill
87+
88+
Alongside the CLI script, `generate-cli` writes a `SKILL.md` file — a [Claude Code agent skill](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/skills) that documents every tool's exact invocation syntax, parameter flags, types, and descriptions. An agent can pick up the CLI immediately without running `--help` or experimenting with flag names.
89+
90+
To skip skill generation:
91+
92+
```bash
93+
fastmcp generate-cli weather --no-skill
94+
```
95+
96+
## How It Works
97+
98+
The generated script is a *client*, not a server — it connects to the server on every invocation rather than bundling it. A `CLIENT_SPEC` variable at the top holds the resolved transport (a URL string or `StdioTransport` with baked-in command and arguments).
99+
100+
The most common edit is changing `CLIENT_SPEC` — for example, pointing a script generated from a dev server at production. Beyond that, the helper functions (`_call_tool`, `_print_tool_result`) are thin wrappers around `fastmcp.Client` that are easy to adapt.
101+
102+
The script requires `fastmcp` as a dependency. If it lives outside a project that already has FastMCP installed:
103+
104+
```bash
105+
uv run --with fastmcp python cli.py call-tool get_forecast --city London
106+
```

0 commit comments

Comments
 (0)