使用说明
mcp
A CLI tool for discovering and calling tools on external MCP (Model Context Protocol) servers.
When to use this CLI
Most agent harnesses (Claude Code, Cursor, etc.) can connect to MCP servers natively — every tool on every connected server is loaded into the prompt as a typed function the model can call directly. That works well when you need a small, fixed set of tools every turn. It works badly when the catalogue is large, the server is one-off, or you want to compose tool output with the shell.
This CLI is the second path. Reach for it when native loading is wrong for the job.
Decision rule (one sentence): if the tool you need is already loaded as
mcp__<server>__<tool> in your tool list, call it natively; otherwise use
this CLI.
Use this CLI when:
- The server isn't loaded natively (no harness config, ad-hoc URL, dev sandbox).
- The catalogue is large but you only need one or two tools this session — pay for one schema, not all of them.
- You need to search across every connected server at once (
mcp tools --query). - You want to pipe tool output through
jq, capture it in a variable, or script it. - You need to see what each server costs in tokens (
mcp stats). - Your agent has no native MCP support and shell is the only channel.
Use native MCP when:
- The tool is already loaded and you'll call it many times this session — the schema-load cost amortizes.
- Args are deeply nested or typed — the model emits them directly, no JSON escaping.
- You're inside a tight loop where the extra
mcp tools/mcp schemaround-trips matter.
What this CLI gives you that native loading doesn't:
- Lazy schema loading.
mcp toolsreturns name+description only. Schemas (often 10k+ tokens per server) are fetched one tool at a time, on demand, viamcp schema. Native loading pays the full schema tax every turn whether you call the tool or not. - Ad-hoc URLs.
mcp tools https://api.example.com/mcpworks without registering the server. Same forcall,ping. Token auth viaMCP_AUTH_TOKEN. - Cross-server search.
mcp tools --query fooranks tools by keyword across every connected server. Native has no equivalent. - Resource access.
mcp resourceslists a server's readable resources and templates;mcp read <uri>fetches their contents. Useful for servers (like Notion) that expose data as resources rather than tools. - Token visibility.
mcp stats(and--full) tells you exactly what each server's schemas would cost if loaded natively. - Streaming.
mcp call --streamemits NDJSON progress events for long-running tools. - Shell composability. Output is JSON on stdout, logs on stderr, exit codes for success/failure. Pipe, capture, chain at will.
Tradeoffs to know:
- More turns per call (list → schema → call) than a native one-shot invocation.
- Args are passed as a JSON string — escaping matters.
- Schema cache can drift; use
--refreshif a server changed. - Stdio servers have a cold-start cost on first call (use
mcp daemonto keep them warm).
Install
Claude Code plugin
claude plugin marketplace add https://github.com/paulbellamy/mcp
claude plugin install mcp-cli
Pi
Pi ships without built-in MCP support, so this CLI is a
natural fit. The repo is a Pi package:
installing it registers the mcp-cli skill and an extension that downloads the
mcp binary on first session start.
pi install git:github.com/paulbellamy/mcp
Binary
curl -fsSL https://raw.githubusercontent.com/paulbellamy/mcp/master/scripts/install.sh | sh
From source
go install github.com/paulbellamy/mcp@latest
Usage
# Overview: one line per server with its tool names (or why it failed)
mcp list [--refresh]
# List configured servers (full config as JSON)
mcp servers
# Add a server (HTTP or stdio)
mcp add <name> <url>
mcp add <name> --stdio <command> [args...]
# Add an HTTP server with static headers (repeatable; --header or -H).
# Header values may reference environment variables as ${VAR}, expanded at
# request time so secrets never touch servers.json. This is how you connect
# to enterprise MCP servers that authenticate with a static key + org id
# rather than OAuth (e.g. Devin):
mcp add devin https://mcp.devin.ai/mcp \
--header "Authorization: Bearer ${DEVIN_API_KEY}" \
--header "X-Org-Id: ${DEVIN_ORG_ID}"
# Discover tools (compact summaries — name + description only)
mcp tools [server] [--query "search term"] [--refresh]
# Include full inputSchema for every tool (large; usually not needed)
mcp tools --full
# Fetch the full schema for one tool on demand
mcp schema <server> <tool>
# List readable resources (and resource templates) — name + uri + description
mcp resources [server] [--query "search term"]
# Read a resource's contents by URI
mcp read <server> <uri>
# Estimate the token cost of cached schemas across servers
mcp stats [--full]
# Call a tool
mcp call <server> <tool> --params '{"key": "value"}'
# Scalar params can also be passed as individual flags (coerced via the cached
# schema). Array/object params can't be a bare string — pass inline JSON for the
# flag, or use --params:
mcp call <server> <tool> --query hello --limit 10
mcp call <server> <tool> --cmd '["bash","-lc","cd /app && npm run build"]'
# Stream progress for long-running tools
mcp call <server> <tool> --stream --params '{"key": "value"}'
# Override the per-call timeout (default: 2m plain / 5m streaming; 0 = no limit)
mcp call <server> <tool> --timeout 10m --params '{"key": "value"}'
# Authenticate
mcp auth <name> --callback-url <url>
# Use a server without adding it (pass URL directly)
mcp tools https://api.example.com/mcp
mcp call https://api.example.com/mcp <tool> --params '{"key": "value"}'
mcp resources https://api.example.com/mcp
mcp read https://api.example.com/mcp <uri>
mcp ping https://api.example.com/mcp
# Authenticate with a token for ad-hoc URLs
MCP_AUTH_TOKEN=<token> mcp call https://api.example.com/mcp <tool> --params '{}'
# Static headers for ad-hoc URLs (no `add` needed): one "Name: Value" per
# line in MCP_HEADERS. Values may reference env vars as ${VAR}. Works for
# every ad-hoc command (tools, call, resources, read, ping, listen).
MCP_HEADERS="Authorization: Bearer ${DEVIN_API_KEY}
X-Org-Id: ${DEVIN_ORG_ID}" mcp tools https://mcp.devin.ai/mcp
# Ping / remove
mcp ping <server>
mcp remove <name>
# Progress chatter (token refresh, schema-refresh retries, skipped transport
# lines) is off by default so stderr carries only warnings and errors.
# Turn it on with a global flag before the subcommand, or via env.
mcp --verbose call <server> <tool>
MCP_VERBOSE=1 mcp call <server> <tool>
# Print the agent skill (SKILL.md) bundled with this binary. Useful for agents
# without a plugin/skill system: pipe it into their instructions.
mcp --skill
License
MIT
