MCP CLI: Dynamic Tool Discovery for AI Agents

MCP is an open standard for connecting AI agents to external tools, APIs, and data. As the ecosystem grows, agent builders hit a predictable wall: context-window bloat. Every server an agent connects to advertises its tools with full schemas — names, parameters, types, descriptions — and the conventional pattern loads all of them into context before the agent does any work.

mcp-cli inverts that. It is a lightweight command-line interface that lets an agent discover and call MCP tools on demand, so context holds only the definitions actually in use.

Why static loading hurts

The illustration below comes from the project’s own documentation. Wiring up six servers the conventional way costs tens of thousands of tokens before a single request; discovering tools on demand costs a fraction of that.

Setup	Approx. tokens
6 servers, 60 tools, all schemas preloaded	~47,000
Same servers, discovered on demand	~400

Preloading tool definitions across several servers (GitHub, a database, browser automation) can eat a third or more of the effective context. The cost compounds:

• Less room for actual reasoning and code generation.
• More frequent context compaction interrupting the agent’s flow.
• A hard ceiling on how many servers you can connect at once.
• Higher API spend from the input-token overhead on every turn.

The discover-inspect-execute pattern

Most tasks touch only a handful of tools, yet static loading pays for all of them. Dynamic discovery pulls definitions in three steps:

1. Discover which servers and tools exist → mcp-cli
2. Inspect one tool’s schema → mcp-cli github/search
3. Execute it → mcp-cli github/search '{"path": "README.md"}'

You pay only for what you use.

What it is

• Built on Bun; compiles to a single standalone binary.
• Works with both stdio (local) and HTTP (remote) servers.
• Glob search across servers — mcp-cli grep "*mail*" -d.
• Built for coding agents (Claude Code, Gemini CLI, and similar).
• Structured error messages with recovery suggestions.

Quick start

1. Install.

# Binary install
curl -fsSL https://raw.githubusercontent.com/philschmid/mcp-cli/main/install.sh | bash

# Or via Bun
bun install -g https://github.com/philschmid/mcp-cli

2. Configure servers. Create mcp_servers.json in the working directory or ~/.config/mcp/:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "."
      ]
    },
    "deepwiki": {
      "url": "https://mcp.deepwiki.com/mcp"
    }
  }
}

3. Discover tools.

# List all servers and their tools
mcp-cli

# Add -d to include descriptions
mcp-cli -d

4. Inspect a tool’s schema.

mcp-cli filesystem/read_file
# Prints the tool name, server, description, and input schema

5. Execute it.

mcp-cli filesystem/read_file '{"path": "./README.md"}'

6. Chain calls for complex work. The CLI accepts JSON from arguments, stdin, heredocs, or files, so an agent can build and pipe commands:

# Heredoc — best for JSON with awkward quoting
mcp-cli server/tool <<EOF
{"content": "Text with 'single quotes' and \"double quotes\""}
EOF

# From a file
cat args.json | mcp-cli server/tool

# Build JSON with jq
jq -n '{query: "mcp", filters: ["active", "starred"]}' | mcp-cli github/search

# Find TypeScript files, then read the first one
mcp-cli filesystem/search_files '{"path": "src/", "pattern": "*.ts"}' --json \
  | jq -r '.content[0].text' | head -1 \
  | xargs -I {} sh -c 'mcp-cli filesystem/read_file "{\"path\": \"{}\"}"'

Command reference

Command	Output
mcp-cli	List all servers and tool names
mcp-cli <server>	Show a server’s tools and parameters
mcp-cli <server>/<tool>	Get a tool’s JSON schema
mcp-cli <server>/<tool> '<json>'	Call a tool with arguments
mcp-cli grep "<glob>"	Search tools by name

Add -d to include descriptions (for example, mcp-cli filesystem -d).

Flag	Purpose
-j, --json	JSON output for scripting
-r, --raw	Raw text content
-d	Include descriptions

Exit codes: 0 success, 1 client error (bad args, missing config), 2 server error (a tool failed), 3 network error.

Integrating with an agent

mcp-cli is meant to be driven by an agent through its bash tool. The reliable pattern is the same three steps, stated as rules the agent can follow:

1. Discover — run mcp-cli, or mcp-cli grep "<pattern>" to find tools by name.
2. Inspect — run mcp-cli <server> -d or mcp-cli <server>/<tool> to get the input schema when context is missing. With more than about five servers configured, skip -d on a whole server so you don’t dump every description into context.
3. Execute — run mcp-cli <server>/<tool> '<json>', wrapping JSON in single quotes to keep the shell from mangling it.

Give the agent those rules in its system prompt, or — for agents that support skills — ship them as a skill definition so the workflow is available without prompt edits. Either way, the point holds: the agent spends its tokens on reasoning, not on carrying tool definitions it isn’t using.

mcp-cli is open source at github.com/philschmid/mcp-cli.