Test MCP Servers with mcpc

Drive mcpc 0.2.x as the operator-facing harness for any MCP server — stdio or Streamable HTTP. This skill owns the released CLI contract (0.2.0–0.2.4), session-first command shape, JSON scripting, task execution, 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, templates, logging, subscriptions, or instructions from mcpc
• Reproducing auth, proxy, cleanup, task, or transport failures with the released mcpc 0.2.x CLI
• Scripting repeatable smoke checks in --json mode, including CI assertions and isError parsing
• Comparing a local stdio server against a deployed Streamable HTTP target during release verification
• Translating older 0.1.11 target-first examples to current session-first syntax

Do NOT use this skill when

• Building or refactoring server code → use build-mcp-server-sdk-v1, build-mcp-server-sdk-v2, or build-mcp-use-server
• Building or refactoring client/agent code → use build-mcp-use-client or build-mcp-use-agent
• Running an agentic-quality / hardening / context-budget audit beyond CLI testing → use audit-agentic-mcp
• Porting an existing v1 server to v2 → use convert-mcp-sdk-v1-to-v2

Source of truth

1. Confirm the running CLI: mcpc --version must report 0.2.x. Older 0.1.11 syntax is structurally different and stale.
2. When docs and mcpc --help disagree, trust mcpc --help <command> on the version actually installed.
3. This skill was verified against 0.2.4 and live-tested against https://research.yigitkonur.com/mcp 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. Violating any one of them is the most common failure mode in mcpc 0.2.x.

Stale syntax to refuse outright:

mcpc mcp.example.com tools-list                          # 0.1.11 — drop
mcpc mcp.example.com connect @demo                        # 0.1.11 — drop
mcpc --config .vscode/mcp.json filesystem connect @demo   # 0.1.11 — drop
mcpc --clean=sessions                                     # legacy flag — drop

Translate to current shape using references/patterns/session-first-syntax.md.

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.2.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. 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.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.

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, stop retrying that name and create a fresh session immediately. For Everything-specific work, prefer a fresh stdio session unless you intentionally started the streamableHttp server yourself.

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 prompts-list

Prefer help and grep before heavy jq pipelines. 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 prompts-get some-prompt --schema ./expected-prompt-schema.json

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

• If completions appears in server info, treat it as informational until a CLI command is confirmed.
• If tasks appear in capabilities, still inspect per-tool execution.taskSupport.
• If a tool is marked task:required, prove it with one --task or --detach call before writing automation around it.

6. Exercise the capability you care about

mcpc --json @research tools-call search-reddit '{"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 logging-set-level debug

7. Treat JSON payloads as truth

RESULT=$(mcpc --json @everything-http tools-call trigger-sampling-request prompt:='"hello"')
echo "$RESULT" | jq '.isError // false'

A command can exit 0 and still carry "isError": true. Always assert on payload, not exit code alone.

8. Use task mode deliberately

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

Use --task when you need the final result in the CLI. Use --detach when a task ID is enough. mcpc 0.2.4 does not have a standalone tasks-result command.

9. Close or clean explicitly

mcpc close @research
mcpc clean
mcpc clean sessions logs

Use mcpc clean all only for a real reset. Do not run close and clean for the same session in parallel.

Capability boundary

What mcpc 0.2.4 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 0.1.11 target-first syntax unless explicitly documenting migration.
• Do not tell users to test HTTP+SSE with mcpc 0.2.x; use Streamable HTTP or stdio instead.
• Do not assume tasks-get can recover the full detached result body.
• Do not treat a green success banner as proof that the server call succeeded.
• Do not assume advertised capabilities always mean polished CLI support.
• Do not run mcpc clean all casually on machines with saved profiles.
• Treat proxy /health as a liveness probe only — verify proxy auth with a real MCP request on the exact release you ship before depending on it.