mcpc

mcpc — a universal MCP CLI client

mcpc is a command-line client for the Model Context Protocol (MCP) that maps every MCP operation to an intuitive shell command.

Use it to manually inspect and debug MCP servers, to script repeatable MCP workflows in plain shell, or to give AI agents the full MCP protocol through a single Bash() tool call, so they can interact with any MCP server and its latest capabilities using the most universal programming interface there is: the UNIX shell.

Key features:

• Full MCP support - Tools, prompts, resources, async tasks, skills, notifications, and logging over stdio and Streamable HTTP.
• Persistent sessions - Keep connections to multiple servers alive in parallel, whether the server protocol is stateful or stateless.
• ️ Progressive tool discovery - Find relevant MCP tools on the fly to save tokens and increase accuracy.
• Code mode - JSON output composes with jq, xargs, and shell pipelines for MCP workflows as shell scripts.
• Secure - Full OAuth 2.1 support with CIMD and DCR, uses OS keychain for credentials storage.
• AI sandboxing - Proxy MCP server connections to protect credentials from AI-generated code.
• Lightweight - Minimal dependencies, works on Mac/Win/Linux, doesn't use LLMs on its own.
• Agentic payments - Experimental support for the x402 protocol on Base.

Table of contents

• Motivation
• Install
• Quickstart
• Usage
• Sessions
• Authentication
• MCP proxy
• AI agents
• Agentic payments (x402)
• MCP support
• Configuration
• Security
• Errors
• Development
• Related work
• License

Motivation

Many AI agents misuse MCP. They treat tools as prompt-time function calls, repeatedly injecting tool definitions and results into the context. Tokens get wasted, context rots, the agent gets slower and less reliable — hence the popular conclusion: "MCP sucks, CLIs are better".

mcpc challenges that narrative. It maps every MCP operation to an intuitive CLI command that agents pick up from --help alone. Any agent with shell access gets full MCP support without wiring up dozens of MCP functions. Just one Bash() tool, and mcpc handles the rest:

 ┌──────────┐   Bash()   ┌────────┐    MCP    ┌────────────┐
 │ AI agent │ ─────────► │  mcpc  │ ────────► │ MCP server │
 └──────────┘            └────────┘           └────────────┘
                                     Sessions, OAuth, Tools,
                                     Resources, Prompts,
                                     Tasks, x402, ...

CLI is the perfect local interface between agents and MCP, while MCP remains the standard remote interface for server discovery, authentication, payments, and access control. The two aren't exclusive – they're complementary.

As a bonus, the same mcpc configuration, OAuth profiles, and live sessions can be shared across many AI agents on the same machine. Authenticate once, reuse everywhere.

Install

With Homebrew (macOS and Linux), which brings its own Node.js:

brew install apify/tap/mcpc

Otherwise install the latest Node.js or Bun first, then:

npm install -g @apify/mcpc

# Or with Bun
bun install -g @apify/mcpc

Linux: credentials use the OS keychain via the Secret Service API. GNOME/KDE desktops work out of the box. On headless/CI systems, mcpc falls back to a file-based store (~/.mcpc/credentials.json, mode 0600).

To force the keychain on headless systems, install libsecret + gnome-keyring (via apt-get, dnf, or pacman) and run:

dbus-run-session -- bash -c "echo -n 'password' | gnome-keyring-daemon --unlock && mcpc ..."

Quickstart

…

Usage

…

REFERENCE.md collects the full --help output of every command in one page. In your terminal, run mcpc help to see the same help for a single command.

General actions

With no arguments, mcpc lists all active sessions and saved OAuth profiles:

# List all sessions and OAuth profiles (also in JSON mode)
mcpc
mcpc --json

# Show command help or version
mcpc --help
mcpc --version

# Clean stale sessions and old log files
mcpc clean

Server formats

The connect, login, and logout commands accept a `` argument in these formats:

• Remote URL (e.g. mcp.apify.com or https://mcp.apify.com) — scheme defaults to https://
• Config file entry (e.g. ~/.vscode/mcp.json:filesystem) — file:entry-name syntax

connect additionally supports two bulk forms that connect many servers at once:

• Config file without an entry (e.g. ~/.vscode/mcp.json) — connect every server in the file
• No argument (mcpc connect) — auto-discover MCP config files in the current directory and your home dir (.mcp.json, mcp.json, .cursor/mcp.json, .vscode/mcp.json, ~/.claude.json, Claude Desktop, Windsurf, Kiro, …) and connect everything found (run mcpc connect --help for the full list).

mcpc connect                      # discover standard config files and connect all servers
mcpc connect ~/.vscode/mcp.json   # connect every server in one file

Bulk connects auto-generate session names (so they don't take an @session) and skip local stdio servers by default — pass --stdio to include them. Each discovered config file is listed with its servers, the names of the headers they send, and their status (● live, ✗ failed); files that can't be used are shown as (0 servers) or (invalid) with the reason, rather than silently ignored. The command waits for every handshake to finish (with a progress spinner in human mode); --json reports each server's details. If every server fails to connect, the command exits with a non-zero code.

Auto-discovery does not trust config files in the current directory to read environment variables. A .mcp.json checked into a repository could carry "headers": { "X": "${GITHUB_TOKEN}" } (or ${SECRET} in a hostname) pointed at an attacker's server, and a bare mcpc connect in that checkout would send the secret on the first request. So mcpc connect skips every project-scope entry that references a ${VAR} — in url, headers, command, args or env, with or without --stdio — and shows which variables it would have read; it also refuses -H, which would go to every discovered server. Files under your home directory are your own and expand ${VAR} as usual. To connect a skipped entry, review the file and name it explicitly (mcpc connect ./.mcp.json): naming a file is the trust step.

MCP commands

All MCP commands go through a named session created with connect:

# Connect to a remote server and create a session
mcpc connect mcp.apify.com @apify
mcpc @apify tools-list
mcpc @apify tools-call search-apify-docs query:="What are Actors?"

# Connect to a local server via config file entry
mcpc connect ~/.vscode/mcp.json:filesystem @fs
mcpc @fs tools-list
mcpc @fs tools-call list_directory path:=/

See MCP feature support for details about all supported MCP features and commands.

Command arguments

The tools-call and prompts-get commands accept arguments as positional parameters after the tool/prompt name:

…

Auto-parsing rules for key:=value: valid JSON keeps its type (count:=10 → number, enabled:=true → boolean, cfg:='{"k":"v"}' → object); anything else is a string (greeting:=hello → "hello"). Force a string literal with JSON quotes: id:='"123"'. Inline JSON is detected when the first arg starts with { or [. Stdin is read when no positional args are given and input is piped.

Pitfalls: no spaces around := (use query:=hello world, not query := ...); quote the whole argument when it contains shell expansions ("query:=${VAR}"). For complex inputs, prefer piping JSON via stdin.

Grep (search across sessions)

mcpc grep searches tools, resources, and prompts across all active sessions or within a single session:

# Search tools and server instructions in all active sessions
mcpc grep "search"

# Search within a single session
mcpc @apify grep "actor"

# Search resources and prompts instead of the default tools and instructions
mcpc grep "config" --resources --prompts

# Regex search
mcpc grep "search|find" -E

# Case-sensitive search (default is case-insensitive)
mcpc grep "Search" --case-sensitive

# Limit results
mcpc grep "e" -m 5

# JSON output for scripting
mcpc grep "actor" --json

By default, grep searches tools and server instructions. Use --resources or --prompts to search those types instead (combine with --tools or --instructions to mix and match). Sessions that are crashed or unavailable are shown with their status rather than silently skipped. Like grep(1), the command exits with code 0 when there are matches and 1 when there are none.

The grep command is useful for dynamic tool discovery, also called Tool search tool by Anthropic or Dynamic context discovery by Cursor. Rather than loading all tools into the AI agent's context, the agent can use grep to discover the right tool for the job, and only load the relevant tools into the context when needed to reduce token usage and improve accuracy.

JSON mode

By default, mcpc prints output in Markdown-ish text format with colors, making it easy for both humans and AIs to read.

With --json option, mcpc always emits only a single JSON object (or array), to enable scripting. For all MCP commands, the returned objects are always consistent with the MCP specification. On success, the JSON object is printed to stdout, on error to stderr.

Note that --json is not available for mcpc --help. For login, --json prints a single { profile, serverUrl, scopes } object on stdout (interactive prompts go to stderr).

Sessions

Up to protocol version 2025-11-25, MCP was a stateful protocol: clients and servers negotiate protocol version and capabilities in an initialize handshake, and then communicate within a persistent session. Protocol version 2026-07-28 made MCP stateless — there is no handshake or server-side session anymore, and every request stands on its own.

mcpc keeps one session-based workflow on top of both: you first connect a named session, then interact with the server through it. On stateful servers the session maps directly to the protocol-level MCP session. On stateless (2026-07-28) servers the session abstracts the protocol away — a lightweight bridge process still holds the connection, the negotiated protocol version, and client-side state, so everything built on "connect first, then interact" keeps working the same: cached tool listings, searching across sessions with grep, server keepalive and status checks by periodic probing, change notifications, resource-to-file syncs, and automatic OAuth token refresh. It is also more efficient than forcing every MCP command to rediscover the server and reauthenticate.

The protocol version is negotiated automatically (mcpc @session shows the result). To pin one exact version instead, pass --protocol-version to connect (e.g. `mcpc connect mcp.apify