/mcpc

name: mcpc
description: Use the mcpc CLI to work with MCP (Model Context Protocol) servers from the shell - connect to a server as a persistent session, then list and call tools, read resources, get prompts, and run async tasks. Use --json for scripting and code mode. Reach for this whenever interacting with MCP servers, calling MCP tools, or accessing MCP resources programmatically.
allowed-tools: Bash(mcpc:*), Read, Grep

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 # that tool's details + 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`:

• `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` 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

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.

Sessions

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`

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 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
# grep filters: --tools/--resources/--prompts/--instructions, -E regex, -s case-sensitive, -m <n> max
# grep exits 0 on match, 1 on no matches (grep convention)

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:

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
# also on tools-get; --schema-mode strict | compatible (default) | ignore

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