apify/mcpc

mcpc: MCP command-line client

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.

Mental model

1. Connect once to a server — this creates a persistent, named @session. A background bridge process keeps the connection (and its state) alive.
2. 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.
3. 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:

mcpc --help                       # all commands + global options
mcpc help connect                 # help for one command
mcpc @apify tools-call foo --help # print a specific tool's input schema

First steps

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

Connecting

Server formats accepted by connect / login / logout:

• mcp.example.com — remote HTTP server (https:// is added automatically)
• localhost:8080 or 127.0.0.1:8080 — local HTTP server (http:// is the default for localhost)
• ~/.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

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.

Sessions

mcpc                     # list all sessions and their state
mcpc @apify              # session details, capabilities, tools (also reports the
                         # negotiated protocol version and stateful vs stateless)
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
• 🟡 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

Discovering and inspecting tools

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: print just that tool's input schema

mcpc grep "search"                      # search tools + instructions across ALL sessions
mcpc @apify grep "actor" --resources    # search one session; --tools/--resources/--prompts, -E regex

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.

Calling tools (passing arguments)

Arguments go after the tool name. Three interchangeable styles:

# 1) key:=value — values are auto-parsed as JSON, falling back to string
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 [
mcpc @apify tools-call search '{"query":"hello","limit":10}'

# 3) stdin — auto-detected when piped and no positional args are given
echo '{"query":"hello"}' | mcpc @apify tools-call search

JSON output (code mode)

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

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": [...] }.

Resources and prompts

mcpc @apify resources-list
mcpc @apify resources-read "file:///path/to/file"   # -o <file> to save, --max-size <bytes>
mcpc @apify resources-templates-list
mcpc @apify resources-subscribe <uri>               # and resources-unsubscribe <uri>

mcpc @apify prompts-list
mcpc @apify prompts-get <name> arg1:=value1         # same argument styles as tools-call

Async tasks (long-running tools)

mcpc @apify tools-call <tool> --task <args>     # run as a task with a progress spinner;
                                                # Ctrl+C leaves it running and prints the task ID
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>

Authentication

# OAuth — interactive browser login, saved as a reusable profile
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

# Bearer token — not stored as a profile; kept per-session
mcpc connect mcp.apify.com @s -H "Authorization: Bearer $TOKEN"
mcpc @s tools-list

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.

Proxy for AI isolation

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

# Human: authenticated session + proxy listening on :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
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.

Agent skills (experimental)

Some servers publish agent skills (draft MCP extension, SEP-2640):

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

Debugging

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 clean                                # tidy stale sessions/logs (also: mcpc clean all)

Exit codes

• 0 — success
• 1 — client error (invalid arguments, unknown command)
• 2 — server error (tool failed, resource not found)
• 3 — network error
• 4 — authentication error

Example script

See docs/examples/company-lookup.sh for a complete, AI-generated "code mode" script that validates prerequisites and calls MCP tools with --json.