mcp-cli is a Bun-based command-line client for Model Context Protocol servers. It lists the servers and tools in a config file, shows a tool's input schema, searches tools by glob pattern, and calls a tool with JSON arguments read from the command line or from standard input. Results go to stdout as JSON, diagnostics to stderr, so calls compose with jq, pipes, and shell scripts.
Servers are declared in an mcpservers.json file compatible with Claude Desktop, Gemini, and VS Code, resolved from MCPCONFIG_PATH, a -c argument, the current directory, or the home config directories. Both stdio commands and HTTP URLs are supported, ${VAR} placeholders are substituted from the environment at load time, and allowedTools and disabledTools glob patterns restrict which tools a server exposes, with the disable list taking precedence.
The stated reason for a CLI rather than a resident MCP client is context cost: loading full tool schemas into a model's context window consumes thousands of tokens, so schemas are fetched only when needed and an agent can either be given the command set in its system prompt or use the bundled agent skill. Connections are pooled by a lazily spawned per-server daemon that keeps a Unix socket warm and self-terminates after 60 seconds idle, with a 5-second spawn timeout falling back to a direct connection; MCPNODAEMON disables it. Transient failures such as ECONNREFUSED, ETIMEDOUT, and HTTP 429, 502, 503, and 504 are retried with exponential backoff, while config, auth, and validation errors fail immediately.
Features
- Discovery commands: list every server and tool, inspect one server, or print a single tool's input schema, with -d adding descriptions
- Glob search: mcp-cli grep "file" finds tools by name pattern across all configured servers
- Tool calls: arguments come from inline JSON or from standard input, which avoids shell escaping for quotes and long text
- Transport support: stdio subprocess servers and HTTP servers, including bearer headers from environment variables
- Tool filtering: per-server allowedTools and disabledTools glob lists applied to info, grep, and call alike
- Connection pooling: a per-server daemon keeps connections warm behind a Unix socket with a configurable idle timeout and stale-config detection
- Retry policy: exponential backoff for network and rate-limit errors, immediate failure for config, auth, and validation errors
- Structured errors: each error carries a code, details such as the available servers or tools, and a suggested command to run instead
- Single binary: compiles to a standalone executable with bun build --compile
- Agent integration: a documented system-prompt block and a skill file for coding agents that support agent skills
