Test MCP By CLI

Validate MCP servers with mcp-cli (philschmid/mcp-cli v0.3.0) using release-verified behavior first, then use official repo source only when it matches what the installed binary actually does.

Core rules

• Execute commands directly and sequentially.

• Do not write helper scripts unless explicitly requested.

• Treat server work as incomplete until verification checks pass.

• Prefer single-server commands while debugging.

• After rebuilding a server, always retest with MCP_NO_DAEMON=1 .

• Treat mcp-cli --help and real command output as the primary behavioral source for the installed release.

• Remember that call returns the raw MCP JSON envelope on stdout in the installed v0.3.0 binary.

What to load first

Use this progressive order to keep context tight:

• This file (SKILL.md ) for command strategy, decision rules, and execution flow.

• Skill references for concrete command blocks:

• references/testing-flow.md — 8-phase verification sequence and checklist

• references/configuration-and-arguments.md — config format, search paths, tool filtering, env var substitution, JSON input methods

• references/output-debugging-and-chaining.md — raw output parsing, stream handling, chaining, CI/CD patterns, verified environment variables

• references/errors-and-recovery.md — common errors, exit codes, daemon behavior, and release inconsistencies

• Read only the relevant reference for the current problem instead of loading all files.

• Return to this file when you need the overall workflow or decision rules.

Execution workflow

• Follow the 8-phase verification order in references/testing-flow.md .

• Use config and JSON argument patterns from references/configuration-and-arguments.md .

• Use stream handling, chaining, and env controls from references/output-debugging-and-chaining.md .

• If any command fails, apply diagnosis from references/errors-and-recovery.md .

• Do not report done until all checklist items pass.

Decision rules

Apply when things go wrong:

• If Phase 1 (connect) fails: stop everything. Fix config or server startup before proceeding.

• If a tool is missing from inventory: check disabledTools in config — it takes precedence over allowedTools . Read references/configuration-and-arguments.md .

• If calls return stale results: use MCP_NO_DAEMON=1 — the daemon caches old server processes for 60s. Read daemon section in references/errors-and-recovery.md .

• If calls hang: lower timeout with MCP_TIMEOUT=30 (default is 1800s). Read env var section in references/output-debugging-and-chaining.md .

• If debugging protocol issues: use MCP_DEBUG=1 to see full protocol traffic on stderr.

• If mcp-cli (no args) hangs: it connects ALL servers. Use mcp-cli info <server> to test one at a time.

• If you get AMBIGUOUS_COMMAND : always use a subcommand — call , info , or grep .

• If output parsing looks wrong: call returns raw JSON in this release. Extract content with jq -r '.content[0].text' . Read references/output-debugging-and-chaining.md .

• If docs and binary disagree: trust the installed binary and real command output over inferred internals.

Repository-specific execution mode

When validating this repository's own source code, run the local CLI implementation:

bun run src/index.ts -c ./mcp_servers.json info filesystem bun run src/index.ts -c ./mcp_servers.json call filesystem read_file '{"path":"./README.md"}'

Use globally installed mcp-cli for all other workflows.

Minimal quick start

Install if missing

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

Connect and inspect

mcp-cli info my-server mcp-cli info my-server my-tool

Happy path + error path

mcp-cli call my-server my-tool '{"param":"value"}' mcp-cli call my-server my-tool '{}'

Fresh-connection check after rebuild

MCP_NO_DAEMON=1 mcp-cli call my-server my-tool '{"param":"value"}'

If any step fails, continue debugging; do not claim completion.

Reference files

File When to read

references/testing-flow.md

Running the full 8-phase verification sequence or the final checklist

references/configuration-and-arguments.md

Setting up config files, tool filtering, env var substitution, or passing JSON arguments

references/output-debugging-and-chaining.md

Parsing output, piping between tools, CI/CD scripts, or controlling behavior via env vars

references/errors-and-recovery.md

Any command fails — error type lookup, exit code interpretation, daemon issues, or release inconsistencies