mcpc

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

mcpc: MCP command-line client

mcpc：MCP 命令行客户端

mcpc

maps every MCP operation to a shell command. For agents this is often more efficient than function calling: discover the right tool on demand, then generate shell commands (ideally with

--json

) instead of carrying tool definitions in context.

mcpc

将所有 MCP 操作映射为 Shell 命令。对于 Agent 而言，这通常比函数调用更高效：可按需发现合适的工具，然后生成 Shell 命令（建议搭配

--json

参数），无需在上下文中携带工具定义。

Mental model

核心思路

Connect once to a server — this creates a persistent, named
```
@session
```
. A background bridge process keeps the connection (and its state) alive.
Run commands against the
@session
: list/call tools, read resources, get prompts, run async tasks. There is no one-shot
```
mcpc <url> tools-list
```
— connect first.
Default output is human-readable; add
```
--json
```
for machine-readable, MCP-spec shaped output that composes with
```
jq
```
and shell pipelines (code mode).

Everything is self-documenting — when unsure, ask the CLI:

bash

mcpc --help                       # all commands + global options
mcpc help connect                 # help for one command
mcpc @apify tools-call foo --help # that tool's details + schema

一次连接到服务器——这会创建一个持久化的命名
```
@session
```
（会话）。后台桥接进程会保持连接（及其状态）处于活跃状态。
针对
@session
运行命令：列出/调用工具、读取资源、获取提示词、运行异步任务。不存在一次性的
```
mcpc <url> tools-list
```
命令——需先建立连接。
默认输出为人类可读格式；添加
```
--json
```
参数可获取符合 MCP 规范的机器可读输出，可与
```
jq
```
和 Shell 管道配合使用（代码模式）。

所有功能均自带文档——如有疑问，直接询问 CLI：

bash

mcpc --help                       # 查看所有命令及全局选项
mcpc help connect                 # 查看单个命令的帮助信息
mcpc @apify tools-call foo --help # 查看该工具的详细信息及 schema

First steps

入门步骤

bash

mcpc                                   # list sessions + auth profiles (start here)
mcpc connect mcp.apify.com @apify      # connect, create the @apify session
mcpc @apify                            # server info, capabilities, tools overview
mcpc @apify tools-list                 # list tools
mcpc @apify tools-call <tool> q:="hi"  # call a tool

bash

mcpc                                   # 列出会话及认证配置文件（从这里开始）
mcpc connect mcp.apify.com @apify      # 建立连接，创建 @apify 会话
mcpc @apify                            # 查看服务器信息、功能及工具概览
mcpc @apify tools-list                 # 列出所有工具
mcpc @apify tools-call <tool> q:="hi"  # 调用某个工具

Connecting

连接服务器

Server formats accepted by

connect

```
mcp.example.com
```
— remote HTTP server (
```
https://
```
is added automatically)

localhost:8080

127.0.0.1:8080

— local HTTP server (

http://

is the default for

localhost

and

127.0.0.1

)

```
~/.vscode/mcp.json:filesystem
```
— a single entry from a config file (
```
file:entry
```
)
```
~/.vscode/mcp.json
```
— connect every entry in a config file
(no server) — auto-discover standard configs and connect all of them

bash

mcpc connect mcp.apify.com @apify        # remote server, explicit session name
mcpc connect mcp.apify.com               # auto-name the session → @apify
mcpc connect ./.vscode/mcp.json:fs @fs   # one config entry (stdio or http)
mcpc connect                             # discover standard configs + connect everything

```
@session
```
is optional — omit it to auto-generate a name from the server (
```
mcp.apify.com
```
→
```
@apify
```
). A matching session (same server + auth) is reused.
Stdio (command-based) entries launch a local process on connect — only connect to configs you trust. Bulk connects skip stdio entries unless you pass
```
--stdio
```
.
The MCP protocol version is negotiated automatically. Pass
```
--protocol-version <version>
```
(e.g.
```
--protocol-version 2025-11-25
```
) to pin one exact version — the connection fails if the server does not support it.
```
login
```
/
```
logout
```
only accept an MCP server URL (a bare host or full
```
http(s)://
```
URL) — not config files or auto-discovery.

connect

命令支持的服务器格式：

```
mcp.example.com
```
—— 远程 HTTP 服务器（会自动添加
```
https://
```
）

localhost:8080

或

127.0.0.1:8080

—— 本地 HTTP 服务器（

localhost

和

127.0.0.1

默认使用

http://

）

```
~/.vscode/mcp.json:filesystem
```
—— 配置文件中的单个条目（格式为
```
file:entry
```
）
```
~/.vscode/mcp.json
```
—— 连接配置文件中的所有条目
(无服务器参数) —— 自动发现标准配置并连接所有条目

bash

mcpc connect mcp.apify.com @apify        # 远程服务器，指定会话名称
mcpc connect mcp.apify.com               # 自动生成会话名称 → @apify
mcpc connect ./.vscode/mcp.json:fs @fs   # 连接单个配置条目（stdio 或 http）
mcpc connect                             # 发现标准配置并连接所有条目

```
@session
```
为可选参数——省略时会从服务器地址自动生成名称（
```
mcp.apify.com
```
→
```
@apify
```
）。匹配的会话（相同服务器+认证信息）会被复用。
Stdio（基于命令）条目在连接时会启动本地进程——仅连接你信任的配置。批量连接会跳过 stdio 条目，除非你传入
```
--stdio
```
参数。
MCP 协议版本会自动协商。传入
```
--protocol-version <version>
```
（例如
```
--protocol-version 2025-11-25
```
）可固定使用某个特定版本——如果服务器不支持该版本，连接会失败。
```
login
```
/
```
logout
```
仅接受 MCP 服务器 URL（裸主机名或完整的
```
http(s)://
```
URL）——不支持配置文件或自动发现。

Sessions

会话管理

bash

mcpc                     # list all sessions and their state
mcpc @apify              # session details, capabilities, tools (also reports the
                         # negotiated MCP version and the transport carrying it)
mcpc restart @apify      # restart (after server updates, or to recover an 'expired' session)
mcpc close @apify        # tear the session down

Session states:

🟢 live — ready to use
🟡 connecting / reconnecting — transient; retry in a moment
🟡 disconnected — bridge alive but the server has gone quiet; retry to reconnect
🟡 crashed — bridge process died; auto-restarts on next use

🔴 unauthorized — auth failed; run

mcpc login <server>

then

mcpc restart @session

🔴 expired — server dropped the session; run
```
mcpc restart @session
```

bash

mcpc                     # 列出所有会话及其状态
mcpc @apify              # 查看会话详情、功能、工具（同时显示协商后的 MCP 版本及传输方式）
mcpc restart @apify      # 重启会话（服务器更新后，或恢复已过期的会话）
mcpc close @apify        # 终止会话

会话状态：

🟢 live（活跃） —— 可正常使用
🟡 connecting（连接中） / reconnecting（重连中） —— 临时状态；稍候重试
🟡 disconnected（已断开） —— 桥接进程仍活跃，但服务器无响应；重试即可重连
🟡 crashed（崩溃） —— 桥接进程已终止；下次使用时会自动重启
🔴 unauthorized（未授权） —— 认证失败；运行
```
mcpc login <server>
```
后再执行
```
mcpc restart @session
```
🔴 expired（已过期） —— 服务器已终止会话；运行
```
mcpc restart @session
```

Discovering and inspecting tools

工具发现与查看

bash

mcpc @apify tools-list                  # compact list with inline param signatures
mcpc @apify tools-list --full           # full JSON schemas
mcpc @apify tools-get <tool>            # one tool's details + schema
mcpc @apify tools-call <tool> --help    # shortcut for tools-get: that tool's details + schema

mcpc grep "search"                      # search tools + instructions across ALL sessions
mcpc @apify grep "actor" --resources    # search one session

bash

mcpc @apify tools-list                  # 简洁列表，包含内置参数签名
mcpc @apify tools-list --full           # 完整的 JSON schema
mcpc @apify tools-get <tool>            # 查看单个工具的详细信息及 schema
mcpc @apify tools-call <tool> --help    # tools-get 的快捷方式：查看该工具的详细信息及 schema

mcpc grep "search"                      # 在所有会话中搜索工具及说明
mcpc @apify grep "actor" --resources    # 在单个会话中搜索

grep filters: --tools/--resources/--prompts/--instructions, -E regex, -s case-sensitive, -m <n> max

grep 过滤选项：--tools/--resources/--prompts/--instructions，-E 正则表达式，-s 区分大小写，-m <n> 最多匹配数量

grep exits 0 on match, 1 on no matches (grep convention)

grep 匹配成功时退出码为 0，无匹配时为 1（符合 grep 惯例）


Prefer progressive discovery: `grep` to find the right tool, then `tools-get` for its
schema. This keeps token use low instead of dumping every tool definition.

For scripts and CI, pin a tool's schema to catch breaking changes early:

```bash
mcpc --json @apify tools-get <tool> > expected.json          # snapshot the schema
mcpc @apify tools-call <tool> --schema expected.json <args>  # fail fast if it drifted


建议逐步发现：先用 `grep` 找到合适的工具，再用 `tools-get` 查看其 schema。这样可以减少 Token 使用，避免导出所有工具定义。

对于脚本和 CI 场景，可固定工具的 schema 以提前发现破坏性变更：

```bash
mcpc --json @apify tools-get <tool> > expected.json          # 生成 schema 快照
mcpc @apify tools-call <tool> --schema expected.json <args>  # 如果 schema 变更则快速失败

also on tools-get; --schema-mode strict | compatible (default) | ignore

tools-get 也支持该参数；--schema-mode 可选值：strict | compatible（默认） | ignore

undefined

undefined

Calling tools (passing arguments)

调用工具（传递参数）

Arguments go after the tool name. Three interchangeable styles:

bash

undefined

参数需放在工具名称之后。支持三种可互换的格式：

bash

undefined

1) key:=value — values are auto-parsed as JSON, falling back to string

1) key:=value —— 值会自动解析为 JSON，解析失败则作为字符串处理

mcpc @apify tools-call search query:="hello world" limit:=10 enabled:=true mcpc @apify tools-call search config:='{"nested":"value"}' items:='[1,2,3]' mcpc @apify tools-call search id:='"123"' # force a string with JSON quotes

2) inline JSON — when the first arg starts with { or [

2) 内联 JSON —— 当第一个参数以 { 或 [ 开头时

mcpc @apify tools-call search '{"query":"hello","limit":10}'

3) stdin — auto-detected when piped and no positional args are given

3) 标准输入 —— 当通过管道传递数据且未指定位置参数时会自动识别

echo '{"query":"hello"}' | mcpc @apify tools-call search

undefined

echo '{"query":"hello"}' | mcpc @apify tools-call search

undefined

JSON output (code mode)

JSON 输出（代码模式）

Add

--json

for machine-readable output: results on stdout, errors on stderr, shaped strictly per the MCP spec.

bash

mcpc --json @apify tools-list | jq -r '.[].name'
mcpc --json @apify tools-call search query:="test" | jq -r '.content[0].text'

添加

--json

参数可获取机器可读输出：结果输出到标准输出，错误输出到标准错误，格式严格遵循 MCP 规范。

bash

mcpc --json @apify tools-list | jq -r '.[].name'
mcpc --json @apify tools-call search query:="test" | jq -r '.content[0].text'

chain tools across calls/sessions

跨调用/会话串联工具

mcpc --json @apify tools-call search-actors keywords:="scraper"
| jq -r '.content[0].text | fromjson | .items[0].id'
| xargs -I{} mcpc --json @apify tools-call get-actor actorId:="{}"


`mcpc --json` with no command returns `{ "sessions": [...], "profiles": [...] }`.

mcpc --json @apify tools-call search-actors keywords:="scraper"
| jq -r '.content[0].text | fromjson | .items[0].id'
| xargs -I{} mcpc --json @apify tools-call get-actor actorId:="{}"


不带命令执行 `mcpc --json` 会返回 `{ "sessions": [...], "profiles": [...] }`。

Resources and prompts

资源与提示词

bash

mcpc @apify resources-list
mcpc @apify resources-read "file:///path/to/file"   # -o <file> to save (binary-safe), --raw to pipe
mcpc @apify resources-templates-list
mcpc @apify resources-subscribe <uri> <file>        # keep local <file> in sync with the resource
mcpc @apify resources-unsubscribe <uri>             # stop syncing, keep the file

mcpc @apify prompts-list
mcpc @apify prompts-get <name> arg1:=value1         # same argument syntax as tools-call (values coerced to strings)

bash

mcpc @apify resources-list
mcpc @apify resources-read "file:///path/to/file"   # 使用 -o <file> 保存（支持二进制文件），--raw 参数用于管道传输
mcpc @apify resources-templates-list
mcpc @apify resources-subscribe <uri> <file>        # 保持本地 <file> 与资源同步
mcpc @apify resources-unsubscribe <uri>             # 停止同步，保留本地文件

mcpc @apify prompts-list
mcpc @apify prompts-get <name> arg1:=value1         # 参数语法与 tools-call 相同（值会被强制转换为字符串）

Async tasks (long-running tools)

异步任务（长运行工具）

bash

mcpc @apify tools-call <tool> --task <args>     # run as a task with a progress spinner; Ctrl+C (or
                                                # ESC) leaves it running and prints the task ID.
                                                # Falls back to a normal sync call if the server has no task support.
mcpc @apify tools-call <tool> --detach <args>   # start and return the task ID immediately
mcpc @apify tasks-list
mcpc @apify tasks-get <taskId>                  # status
mcpc @apify tasks-result <taskId>               # block until the final result is ready
mcpc @apify tasks-cancel <taskId>

Task commands need a server on MCP protocol 2025-11-25 that advertises the tasks capability (

tools-list

flags it per tool as

[task:optional|required|forbidden]

). Otherwise

--task

--detach

and the

tasks-*

commands fail with an error — they never silently fall back to a synchronous call, so

--detach

output always has a

taskId

or a non-zero exit code. On 2026-07-28 servers tasks are an extension mcpc does not support yet.

bash

mcpc @apify tools-call <tool> --task <args>     # 以任务模式运行，显示进度 spinner；按 Ctrl+C（或 ESC）会让任务在后台运行并打印任务 ID。
                                                # 如果服务器不支持任务模式，会 fallback 为普通同步调用。
mcpc @apify tools-call <tool> --detach <args>   # 启动任务并立即返回任务 ID
mcpc @apify tasks-list
mcpc @apify tasks-get <taskId>                  # 查看任务状态
mcpc @apify tasks-result <taskId>               # 阻塞直到任务完成并返回最终结果
mcpc @apify tasks-cancel <taskId>

任务命令要求服务器使用 MCP 协议 2025-11-25 版本，且支持任务功能（

tools-list

会在每个工具的标记中显示

[task:optional|required|forbidden]

）。否则

--task

--detach

及

tasks-*

命令会报错——不会静默 fallback 为同步调用，因此

--detach

的输出要么包含

taskId

，要么返回非零退出码。对于 2026-07-28 版本的服务器，任务功能是 mcpc 暂不支持的扩展特性。

Authentication

认证

bash

undefined

bash

undefined

OAuth — interactive browser login, saved as a reusable profile

OAuth —— 交互式浏览器登录，保存为可复用的配置文件

mcpc login mcp.apify.com # "default" profile mcpc login mcp.apify.com --profile work # a named profile (multiple accounts per server) mcpc connect mcp.apify.com @apify --profile work mcpc logout mcp.apify.com

mcpc login mcp.apify.com # 创建「default」配置文件 mcpc login mcp.apify.com --profile work # 创建命名配置文件（同一服务器支持多个账户） mcpc connect mcp.apify.com @apify --profile work mcpc logout mcp.apify.com

Bearer token — not stored as a profile; kept per-session

Bearer 令牌 —— 不保存为配置文件；仅在当前会话中生效

mcpc connect mcp.apify.com @s -H "Authorization: Bearer $TOKEN" mcpc @s tools-list

Machine-to-machine (CI/CD, daemons) — client-credentials grant, no browser needed

机器对机器（CI/CD、守护进程）—— 客户端凭证授权，无需浏览器

mcpc login mcp.example.com --grant client-credentials --client-id my-svc --client-secret s3cr3t

Enterprise-managed authorization — SSO once at the corporate IdP (e.g. Okta),

企业级管理授权 —— 在企业 IdP（如 Okta）完成一次 SSO 登录，

then identity assertion grants (ID-JAG); clients are pre-registered by IT

然后使用身份断言授权（ID-JAG）；客户端由 IT 预先注册

mcpc login mcp.example.com --grant id-jag --idp https://acme.okta.com
--idp-client-id idp-client --client-id mcp-client --client-secret s3cr3t


With no auth flags, mcpc uses the `default` profile if one exists, otherwise it
connects anonymously. Use `--no-profile` to force an anonymous connection, or
`--profile <name>` to require a specific one.

mcpc login mcp.example.com --grant id-jag --idp https://acme.okta.com
--idp-client-id idp-client --client-id mcp-client --client-secret s3cr3t


如果未指定认证参数，mcpc 会使用「default」配置文件（如果存在），否则会匿名连接。使用 `--no-profile` 参数可强制匿名连接，或使用 `--profile <name>` 指定特定配置文件。

Proxy for AI isolation

AI 隔离代理

Expose an authenticated session as a local MCP server, so sandboxed AI code can use it without ever seeing your real credentials:

bash

undefined

将已认证的会话暴露为本地 MCP 服务器，这样沙箱中的 AI 代码可以使用该服务器，而无需访问你的真实凭证：

bash

undefined

Human: authenticated session + proxy listening on :8080

人类用户：已认证会话 + 在 :8080 端口监听的代理

mcpc connect mcp.apify.com @ai-proxy --profile ai-access --proxy 8080

AI in a sandbox limited to localhost: no access to the original tokens

沙箱中的 AI：仅能访问 localhost，无法获取原始令牌

mcpc connect localhost:8080 @sandboxed mcpc @sandboxed tools-list


A proxy does not make an untrusted server safe — stdio servers still touch your system,
and HTTP servers still hold your credentials. Only connect to servers you trust.

mcpc connect localhost:8080 @sandboxed mcpc @sandboxed tools-list


代理并不能保证不可信服务器的安全性——stdio 服务器仍会访问你的系统，HTTP 服务器仍持有你的凭证。仅连接你信任的服务器。

Server-published skills (experimental)

服务器发布的技能（实验性）

Distinct from this guide: some MCP servers publish their own agent skills (draft MCP extension, SEP-2640). Read them with:

bash

mcpc @apify skills-list
mcpc @apify skills-get <name> --raw    # print the SKILL.md markdown (pipe to a file or an LLM)

(

mcpc help --skill

documents mcpc itself;

skills-list

skills-get

fetch skills from the server.)

与本指南不同：部分 MCP 服务器会发布自己的 Agent 技能（MCP 扩展草案，SEP-2640）。可通过以下命令读取：

bash

mcpc @apify skills-list
mcpc @apify skills-get <name> --raw    # 打印 SKILL.md 格式的 Markdown 内容（可输出到文件或传递给 LLM）

（

mcpc help --skill

文档介绍 mcpc 自身；

skills-list

skills-get

用于从服务器获取技能。）

Global flags worth knowing

值得关注的全局标志

bash

--json                  # machine-readable, MCP-spec-shaped output (code mode)
--verbose               # protocol-level debug logging (JSON-RPC, transport)
--profile <name>        # OAuth profile to use ("default" if omitted)
--timeout <seconds>     # request timeout in seconds (default: 60)
--max-chars <n>         # truncate human-readable output to n chars (ignored with --json)
--insecure              # skip TLS verification (self-signed certs only)

(

--no-profile

--stdio

--proxy

, and

-H

are options of

connect

, not global flags.)

mcpc

also has experimental

--x402

auto-payment for paid MCP tools — see

mcpc help x402

bash

--json                  # 机器可读、符合 MCP 规范的输出（代码模式）
--verbose               # 协议级别的调试日志（JSON-RPC、传输层）
--profile <name>        # 使用的 OAuth 配置文件（省略时为「default」）
--timeout <seconds>     # 请求超时时间（单位：秒，默认值：60）
--max-chars <n>         # 将人类可读输出截断为 n 个字符（使用 --json 时忽略该参数）
--insecure              # 跳过 TLS 验证（仅适用于自签名证书）

（

--no-profile

、

--stdio

、

--proxy

和

-H

是

connect

命令的选项，而非全局标志。）

mcpc

还支持实验性的

--x402

自动支付功能，用于付费 MCP 工具——详见

mcpc help x402

。

Debugging

调试

bash

mcpc --verbose @apify tools-call <tool>   # protocol-level detail (JSON-RPC, transport)
mcpc @apify logs                          # bridge log; -n <N>, --follow, --since 1h
mcpc @apify ping                          # round-trip health check
mcpc @apify server-discover               # what the server advertises now (2026-07-28 only;
                                          # on older servers use mcpc @apify instead)
mcpc @apify logging-set-level debug       # deprecated; 2025-11-25 servers only, will be removed
mcpc clean                                # tidy stale sessions/logs (also: mcpc clean all)

bash

mcpc --verbose @apify tools-call <tool>   # 协议级详细信息（JSON-RPC、传输层）
mcpc @apify logs                          # 桥接日志；-n <N> 显示最后 N 行，--follow 实时跟踪，--since 1h 显示最近1小时的日志
mcpc @apify ping                          # 往返健康检查
mcpc @apify server-discover               # 查看服务器当前的广告信息（仅适用于 2026-07-28 版本；
                                          # 旧版本服务器请使用 mcpc @apify）
mcpc @apify logging-set-level debug       # 已废弃；仅适用于 2025-11-25 版本服务器，后续会移除
mcpc clean                                # 清理过期会话/日志（也可使用：mcpc clean all）

Exit codes

退出码

```
0
```
— success
```
1
```
— client error (invalid arguments, unknown command);
```
grep
```
also exits 1 on no matches
```
2
```
— server error (tool failed, resource not found)
```
3
```
— network error
```
4
```
— authentication error

```
0
```
—— 成功
```
1
```
—— 客户端错误（无效参数、未知命令）；
```
grep
```
无匹配时也返回 1
```
2
```
—— 服务器错误（工具调用失败、资源未找到）
```
3
```
—— 网络错误
```
4
```
—— 认证错误