Client Commands - Fastmcp

import { VersionBadge } from '/snippets/version-badge.mdx'

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.

Listing Tools

fastmcp list connects to a server and prints its tools as function signatures, showing parameter names, types, and descriptions at a glance:

bash

fastmcp list http://localhost:8000/mcp
fastmcp list server.py
fastmcp list weather  # name-based resolution

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:

bash

fastmcp list server.py --input-schema

Resources and Prompts

By default, only tools are shown. Add --resources or --prompts to include those:

bash

fastmcp list server.py --resources --prompts

Machine-Readable Output

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:

bash

fastmcp list server.py --json

Options

Option	Flag	Description
Command	`--command`	Connect via stdio (e.g., `'npx -y @mcp/server'`)
Transport	`--transport`, `-t`	Force `http` or `sse` for URL targets
Resources	`--resources`	Include resources in output
Prompts	`--prompts`	Include prompts in output
Input Schema	`--input-schema`	Show full input schemas
Output Schema	`--output-schema`	Show full output schemas
JSON	`--json`	Structured JSON output
Timeout	`--timeout`	Connection timeout in seconds
Auth	`--auth`	`oauth` (default for HTTP), a bearer token, or `none`

Calling Tools

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:

bash

fastmcp call server.py greet name=World
fastmcp call http://localhost:8000/mcp search query=hello limit=5

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.

Complex Arguments

For tools with nested or structured parameters, key=value syntax gets awkward. Pass a single JSON object instead:

bash

fastmcp call server.py create_item '{"name": "Widget", "tags": ["sale"], "metadata": {"color": "blue"}}'

Or use --input-json to provide a base dictionary, then override individual keys with key=value pairs:

bash

fastmcp call server.py search --input-json '{"query": "hello", "limit": 5}' limit=10

Error Handling

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.

Structured Output

--json emits the raw result including content blocks, error status, and structured content:

bash

fastmcp call server.py get_weather city=London --json

Interactive Elicitation

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.

Options

Option	Flag	Description
Command	`--command`	Connect via stdio
Transport	`--transport`, `-t`	Force `http` or `sse`
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`

Discovering Configured Servers

fastmcp discover scans your machine for MCP servers configured in editors and tools. It checks:

Claude Desktop — claude_desktop_config.json
Claude Code — ~/.claude.json
Cursor — .cursor/mcp.json (walks up from current directory)
Gemini CLI — ~/.gemini/settings.json
Goose — ~/.config/goose/config.yaml
Project — ./mcp.json in the current directory

bash

fastmcp discover

The output groups servers by source, showing each server's name and transport. Filter by source or get 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 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.

LLM Agent Integration

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.

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.