Test By Mcpc CLI

Test MCP Servers with mcpc

Drive mcpc 0.7.x as the operator-facing harness for any MCP server — stdio or Streamable HTTP. This skill owns the released CLI contract, session-first command shape, JSON scripting, task execution, protocol-version probing, skills extension verification, and cleanup. It does not own writing the server or client itself.

When to use this skill

• Connecting to a real MCP server over stdio or Streamable HTTP and verifying the live surface with mcpc connect … @session
• Inspecting tools, prompts, resources, directory resources, templates, skills, logging, subscriptions, or instructions from mcpc
• Reproducing auth, proxy, cleanup, task, protocol-version, or transport failures with the released mcpc 0.7.x CLI
• Scripting repeatable smoke checks in --json mode, including CI assertions on exit codes and isError
• Comparing a local stdio server against a deployed Streamable HTTP target during release verification
• Translating pre-0.2.0 target-first examples or removed 0.2.x-era commands to current syntax

Do NOT use this skill when

• Building or refactoring server code → use build-mcp-use-server for mcp-use servers; for raw @modelcontextprotocol/sdk servers follow the SDK's own docs
• Building or refactoring client/agent code → out of scope; this skill only drives mcpc
• Running an agentic-quality / hardening / context-budget audit beyond CLI testing → use audit-agentic-mcp
• Porting an existing v1 server to v2 → out of scope; follow the SDK's own migration guide

Source of truth

1. Confirm the running CLI: mcpc --version must report 0.7.x. Older 0.2.x–0.6.x syntax overlaps but drifts on skills, completions, directory resources, x402 receipts, exit codes, and login flags; pre-0.2.0 syntax is structurally different.
2. When docs and mcpc --help disagree, trust mcpc help <command> on the version actually installed. mcpc help --skill (or mcpc --skill) prints upstream's own agent guide.
3. This skill was verified against 0.7.0 and live-tested against https://research-mcp.yigitkonur.com/mcp (mcp-researchpowerpack v9) and @modelcontextprotocol/server-everything over stdio and Streamable HTTP.
4. If mcpc is missing, older, or your config shape is wrong, start with references/guides/installation.md. Establish the plain CLI path first, then layer wrappers back in only after the raw command path already works.

Load-bearing rules

These rules apply across every workflow below. Each one is live-verified against 0.7.0; violating one is the most common failure mode.

Stale syntax to refuse outright:

mcpc mcp.example.com tools-list          # pre-0.2.0 target-first — drop
mcpc mcp.example.com connect @demo       # pre-0.2.0 — drop
mcpc --clean=sessions                    # pre-0.2.0 flag — use: mcpc clean sessions
mcpc @demo tools                         # shorthand aliases removed in 0.3.0 — use tools-list
mcpc shell @demo                         # shell removed in 0.4.0 — no replacement

Translate to current shape using references/patterns/session-first-syntax.md. Raw JSON-RPC method names work as command aliases (tools/list, logging/setLevel, etc.). In 0.7.0, mcpc help tools/list correctly resolves command help instead of erroring. Teach the hyphenated CLI form first.

Minimal read sets

Do not load the whole skill by default. Pick one bundle, then widen only if the task forces you to.

Standard workflow

1. Verify the syntax family

• mcpc --version reports 0.7.x.
• Examples use mcpc connect <server-or-file:entry> @session shape.
• Validate the contract with plain mcpc, not a wrapper that may mangle quoting, TTY, or session state.

2. Connect a stable session

Default to a fresh connect with a name you chose. Reach for the session inventory only when reuse, cleanup, or stale-state diagnosis is the actual job.

# Remote URL; https:// is added automatically for non-local hosts
mcpc connect research-mcp.yigitkonur.com/mcp @research

# Localhost keeps http:// by default
mcpc connect 127.0.0.1:3011/mcp @everything-http

# Stdio via mcpServers config entry
mcpc connect /tmp/everything-mcp.json:everything @everything-stdio

Use --no-profile when anonymous HTTP testing matters on a machine with saved OAuth profiles. Re-running connect with the same @name reuses the session; a new @name always creates a second one (rule 2). Because an unreachable target can still produce exit 0, verify the exact-name session is live before treating the connection as ready (rule 4).

To inspect an existing session, narrow the lookup to a single name instead of dumping the whole inventory:

mcpc
mcpc --json | jq '.sessions[] | select(.name == "@research")'

If an older session is not live, do not reuse it for a smoke test. Either mcpc restart @session or create a fresh session with a new name. If mcpc restart @session returns Session not found (exit 1), stop retrying that name and create a fresh session immediately.

3. Inspect before deep testing

mcpc @research
mcpc @research help
mcpc @research grep search
mcpc @research tools-list --full
mcpc @research resources-list
mcpc @research resources-directory-read <uri>
mcpc @research prompts-list
mcpc @research skills-list
mcpc @research skills-get <skill> [file]

Prefer help and grep before heavy jq pipelines. The mcpc @research banner shows the server metadata (title, description, websiteUrl) and negotiated MCP protocol version — on 2026-07-28 connections server-discover also works (references/guides/protocol-versions.md). If acceptance criteria explicitly mention prompts, resources, or templates, add those list calls in the first pass instead of widening the read set later.

4. Validate schema and argument shape

mcpc @research tools-get web-search
mcpc --json @research tools-get web-search | jq '.inputSchema'
mcpc @research tools-get web-search --schema ./expected-tool-schema.json

--schema/--schema-mode are scoped to tools-get and tools-call only — prompts-get has no schema flags. A client-side schema mismatch exits 1 (it never reaches the server). key:=value still works, but arrays and objects should be sent as inline JSON literals or full JSON payloads. Route quoting edge cases to references/patterns/argument-parsing.md.

5. Reality-check advertised capabilities

Do not trust capabilities alone. Check server info, tool metadata, and one real call.

mcpc --json @research | jq '.capabilities'
mcpc --json @everything-http tools-list | jq '.[] | {name, taskSupport: (.execution.taskSupport // "unspecified")}'

• When completions appears in server info, it advertises completion support (completion/complete). Upstream mcpc provides the dedicated session command: mcpc @session completion-complete prompt|resource <ref> [arg:=val ...].
• mcpc does not advertise sampling, roots, or elicitation, so servers that register demo tools conditionally (like Everything) will not expose them at all.
• If tasks appear in capabilities, still inspect per-tool execution.taskSupport, and prove task:required with one --task or --detach call before writing automation around it.

6. Exercise the capability you care about

mcpc --json @research tools-call web-search 'queries:=["OpenAI MCP"]'
mcpc @everything-http prompts-get args-prompt city:=Paris state:=Texas
mcpc @everything-http resources-read demo://resource/static/document/features.md
mcpc @everything-http resources-directory-read demo://resource/directory/
mcpc @everything-http resources-subscribe demo://resource/dynamic/text/1 /tmp/text-sync.json
mcpc @everything-http logging-set-level debug

resources-subscribe requires a target file and syncs updates into it. logging-set-level may print a deprecation warning about MCP 2026-07-28 — the current call still succeeded (exit 0); read past the ⚠. In 0.7.0, human output folds duplicate structured content with a helpful hint to use --json.

7. Treat JSON payloads as truth

RESULT=$(mcpc --json @research tools-call web-search 'queries:=["mcpc"]') || echo "exit=$?"
echo "$RESULT" | jq '.isError // false'

Since 0.5.0 an isError:true result also exits 2, so scripts may assert on the exit code — but still inspect the payload for failure detail. Paid tool invocations include settlement receipts under _meta["x402/payment-response"]. JSON mode also exposes fields human rendering can omit (for example active tasks, subscription state, and experimental capability payloads); do not assume either mode is a strict structural superset of the other. A timeout can also exit 2, but with {error,code} on stderr rather than an isError payload on stdout (rule 3).

8. Use task mode deliberately

mcpc @everything-http tools-list --full
mcpc @everything-http tools-call simulate-research-query topic:='"mcpc tasks"' ambiguous:=false --task
mcpc @everything-http tools-call simulate-research-query topic:='"mcpc tasks"' ambiguous:=false --detach
mcpc @everything-http tasks-get <taskId>
mcpc @everything-http tasks-result <taskId>

Use --task when you need the final result inline. Use --detach when you want the taskId immediately and will fetch the body later with tasks-result — it works even from a different process. On tools or servers without task support, both flags fail loudly instead of falling back to a sync call.

9. Close or clean explicitly

mcpc close @research
mcpc clean

mcpc clean (no args) removes stale data only. Any named target — including clean sessions logs — removes all records of that kind and belongs only in an intentional reset inside an isolated MCPC_HOME_DIR (rule 5). Do not run close and clean for the same session in parallel; a repeated close returns exit 1, not a no-op success.

Capability boundary

What mcpc 0.7.0 can and cannot test as a first-class workflow:

Map advertised capabilities to actual CLI commands using references/guides/capability-coverage.md.

Reference routing

Read the smallest relevant set for the branch you are in.

Core guides

Commands, examples, and troubleshooting

Patterns and advanced details

Guardrails

• Do not teach pre-0.2.0 target-first syntax, removed shorthand aliases, or the removed shell command unless explicitly documenting migration.
• Do not tell users to test HTTP+SSE with mcpc; use Streamable HTTP or stdio instead.
• Do not treat tasks-get status output as the task result — fetch detached bodies with tasks-result.
• Do not treat connect exit 0 or a green banner as proof that the handshake is live; an unreachable target can remain connecting or move to reconnecting, so verify exact-name status and exercise the capability.
• Do not assume advertised capabilities always mean polished CLI support, nor that missing demo tools mean a broken server — mcpc's non-advertised sampling/roots/elicitation capabilities suppress gated tools by design.
• Do not run mcpc clean all — or any named clean target — casually on machines with saved profiles or live sessions; only no-args clean is stale-only.
• Treat proxy /health as an unauthenticated liveness probe only — verify proxy auth with a real MCP request carrying (or omitting) the bearer token.
• Do not read a ⚠ deprecation warning as a failed call; check the exit code and payload of the current invocation.