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.

mcpc is the most MCP specification-compliant CLI client available. Here's how it compares to other MCP CLI clients (see Related work for details and notes):

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 gnome-keyring (via apt-get, dnf, or pacman) and run:

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

Quickstart

# List all active sessions and saved authentication profiles
mcpc

# Log in to a remote MCP server and save OAuth credentials for future use
mcpc login mcp.apify.com

# Create a persistent session and interact with it
mcpc connect mcp.apify.com @test
mcpc @test              # show server info and capabilities
mcpc @test tools-list   # list available tools
mcpc @test tools-call search-actors keywords:="website crawler"

# Use JSON mode for scripting
mcpc --json @test tools-list

# Use a local MCP server package (stdio) referenced from a config file
mcpc connect ./.vscode/mcp.json:filesystem @fs
mcpc @fs tools-list

Usage

Usage: mcpc [<@session>] [<command>] [options]

Universal command-line client for the Model Context Protocol (MCP).

Commands:
  connect [<server>] [@session]  Connect to an MCP server and start a new named @session
  close <@session>               Close a session
  restart <@session>             Restart a session (losing all state)
  login <server>                 Log in to a server and save an OAuth profile
  logout <server>                Delete an OAuth profile for a server
  clean [resources...]           Clean up mcpc data (sessions, profiles, logs, all)
  grep                  Search tools and instructions across all active sessions
  x402 [subcommand] [args...]    Configure an x402 payment wallet (EXPERIMENTAL)
  help [command] [subcommand]    Show help for a command

Options:
  --json                         Output in JSON format for scripting
  --verbose                      Enable debug logging
  --profile <name>               OAuth profi