Test MCP by CLI

mcp-cli

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

1. This file (

   SKILL.md

   ) for command strategy, decision rules, and execution flow.
2. 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
3. Read only the relevant reference for the current problem instead of loading all files.
4. Return to this file when you need the overall workflow or decision rules.

Execution workflow

1. Follow the 8-phase verification order in

   references/testing-flow.md

   .
2. Use config and JSON argument patterns from

   references/configuration-and-arguments.md

   .
3. Use stream handling, chaining, and env controls from

   references/output-debugging-and-chaining.md

   .
4. If any command fails, apply diagnosis from

   references/errors-and-recovery.md

   .
5. Do not report done until all checklist items pass.

Decision rules

• 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

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"}'

mcp-cli

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"}'

Reference files

references/testing-flow.md

references/configuration-and-arguments.md

references/output-debugging-and-chaining.md

references/errors-and-recovery.md