test-by-mcpc-cli（测试 BY mcpc CLI）

Test MCP Servers with mcpc

Use mcpc 0.2.x as the operator-facing harness for MCP server testing. This skill is written for the 0.2.0 through 0.2.4 command family, not the older 0.1.11 target-first CLI.

Trigger Boundary

Use this skill when you need to:

• connect to a real MCP server over stdio or Streamable HTTP and verify the live surface
• inspect tools, prompts, resources, templates, logging, subscriptions, or instructions from mcpc
• reproduce auth, proxy, cleanup, task, or transport failures with the released CLI
• script repeatable smoke checks in --json mode
• compare a local stdio server with a deployed HTTP target

Do not use this skill when the main job is building the server or client itself. Use build-mcp-server-sdk-v1, build-mcp-server-sdk-v2, build-mcp-use-server, or build-mcp-use-client for implementation work.

Prerequisites

mcpc --version
mcpc --help

Prefer mcpc 0.2.x. This rewrite was verified against 0.2.4 and live-tested with:

• https://research.yigitkonur.com/mcp
• @modelcontextprotocol/server-everything over stdio and Streamable HTTP

If mcpc is missing, older, or your config shape is wrong, start with references/guides/installation.md. This skill documents raw mcpc behavior. Establish the plain CLI path first, then layer wrappers or harnesses back in only after the raw command path already works.

Minimal Read Sets

Do not load the whole skill by default. Use one of these bundles first, then widen only if the task forces you to.

Remote Streamable HTTP smoke test

Read these first:

• references/commands/quick-reference.md
• references/guides/http-testing.md
• references/guides/discovery-search.md
• references/guides/tool-resource-testing.md
• references/guides/cleanup-maintenance.md

Local stdio plus task verification

Read these first:

• references/commands/quick-reference.md
• references/guides/stdio-testing.md
• references/guides/async-tasks.md
• references/guides/everything-server.md
• references/guides/discovery-search.md
• references/guides/tool-resource-testing.md
• references/guides/cleanup-maintenance.md

Auth, proxy, or payment edge cases

Read these first:

• references/commands/quick-reference.md
• references/guides/authentication.md
• references/guides/proxy-testing.md
• references/guides/x402-payments.md
• references/guides/cleanup-maintenance.md

Command Family Change

The 0.2.x CLI is session-first. Always create or reuse a named session before you run MCP operations.

# Remote Streamable HTTP target
mcpc connect https://research.yigitkonur.com/mcp @research
mcpc @research ping
mcpc @research tools-list

# Local stdio target from a standard mcpServers config
mcpc connect .vscode/mcp.json:filesystem @fs
mcpc @fs tools-list

Treat these forms as stale 0.1.11 syntax drift:

• mcpc mcp.example.com tools-list
• mcpc mcp.example.com connect @demo
• mcpc --config.vscode/mcp.json filesystem connect @demo
• mcpc --clean=sessions

Route migration work to references/patterns/session-first-syntax.md.

Standard Workflow

1. Verify the syntax family

• Confirm mcpc --version reports 0.2.x.
• Confirm examples use mcpc connect <server-or-file:entry> @session.
• Validate the released CLI contract with plain mcpc, not a shell wrapper.
• Treat old --config file entry and direct URL one-shot commands as obsolete.

2. Connect a stable session

Default to a fresh connect. Reach for 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 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.

If you do need to inspect an existing session, narrow the lookup to the exact session name instead of reading the whole inventory first:

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

If an older session for the same target is not live, do not assume that session is still the right test entrypoint. 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 the 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.

4b. Reality-check advertised capabilities

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

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

Rules:

• if completions appears in server info, treat it as informational until you confirm the CLI actually exposes a command
• 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

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

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

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

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

High-Signal Rules

1. Connect first. If an example starts with mcpc <server> tools-list, it is stale.
2. Prefer native discovery with mcpc @session, mcpc @session help, and mcpc grep before custom JSON filtering.
3. Inspect isError, task status, and payload text instead of trusting human-mode success banners.
4. Use --no-profile to force anonymous HTTP tests when saved OAuth state would pollute the result.
5. Use mcpc clean..., not legacy --clean=... flags.
6. If an old session is disconnected, reconnecting, expired, or crashed, do not reuse it blindly for a smoke test. Restart it or create a fresh session.
7. Treat HTTP+SSE endpoints as unsupported for mcpc 0.2.x; use Streamable HTTP or stdio instead.
8. Reach for --insecure only when the endpoint really uses a self-signed or otherwise untrusted certificate.
9. When a tool is marked task:required, expect plain tools-call to fail until you add --task or --detach.
10. Use plain mcpc as the documented baseline; wrappers can change quoting, TTY, and session-state visibility.
11. Treat proxy /health as a liveness probe only. Verify proxy auth with a real MCP request on the exact release you ship before you depend on it.

Capability Boundary

Fully testable with first-class CLI support

• stdio and Streamable HTTP
• tools, prompts, resources, resource templates, logging, grep, proxy, x402, JSON scripting
• task-enabled tool execution with --task, --detach, tasks-list, tasks-get, and tasks-cancel

Nuanced or partial in mcpc 0.2.4

• roots: the client advertises roots capability, so servers like Everything may expose helper tools, but mcpc has no dedicated CLI to configure roots
• sampling: servers may expose sampling demo tools because mcpc advertises sampling-related client capabilities, but the tool payload can still come back with isError: true
• completions: appears in server capabilities, but there is no mcpc completions command
• detached task results: tasks-get shows status, not the original tool result body

Not a first-class mcpc workflow

• HTTP+SSE transport testing
• elicitation commands from the CLI
• standalone completion browsing
• standalone detached-result retrieval after --detach

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 you are 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.