apify/mcpc

What is mcpc?

mcpc is a command‑line client that lets you talk to any server that implements the Model Context Protocol (MCP) – a standard API used by AI agents to call tools, fetch resources, run tasks, and more. It turns every MCP operation into a simple shell command, so you can:

• Inspect and debug an MCP server manually.
• Script complex MCP workflows with ordinary Bash pipelines and tools like jq.
• Give AI agents a single Bash() tool that can reach any MCP server, handling authentication, sessions, and payments for the agent.

In short, it’s a universal “MCP‑to‑shell” bridge.

---

Key Features (as described in the README)

Feature	What it means
Full MCP support	Implements the whole MCP spec – tools, prompts, resources, async tasks, skills, notifications, logging, and both stateful and stateless protocol versions.
Persistent sessions	You can keep multiple named connections alive at once, even if the underlying server is stateless.
Progressive tool discovery	mcpc grep can search a server’s tool catalogue on the fly, letting agents load only the tools they actually need (saves tokens).
Code mode / JSON output	--json makes every command emit a single JSON object, perfect for piping into jq, xargs, or other shell utilities.
Secure OAuth 2.1	Built‑in client‑credentials flow, credential storage in the OS keychain (or a protected file on headless systems).
AI sandboxing	A proxy mode that shields stored credentials from code generated by AI agents.
Lightweight	Minimal dependencies, works on macOS, Windows, and Linux without pulling in any LLMs itself.
Agentic payments (x402)	Experimental support for the x402 payment protocol (used on the Base platform).

---

Who Might Use It?

Use case	How mcpc helps
AI‑agent developers	Instead of writing dozens of MCP wrappers, an agent can call mcpc from its Bash tool and get full MCP functionality (tool calls, resource reads, task management, etc.).
DevOps / debugging	Inspect server capabilities (mcpc @session tools-list), test tool calls, or replay a workflow directly from the terminal.
Automation / scripting	Combine mcpc with standard Unix tools (jq, xargs, awk) to build repeatable pipelines that interact with MCP servers.
Security‑conscious teams	Credentials are stored in the OS keychain; a sandbox mode prevents AI‑generated code from leaking them.
Payments integration	Use the experimental x402 commands to attach a payment wallet to MCP calls that require it.

---

How It Works (high‑level flow)

1. Login – mcpc login <server> performs an OAuth 2.1 client‑credentials handshake and saves the token securely.
2. Connect – mcpc connect <server> @name creates a named session (e.g. @apify). The client negotiates the MCP version and keeps a lightweight bridge process alive.
3. Run commands – Prefix any command with the session name, e.g. mcpc @apify tools-call search-actors query:="web crawler". Arguments can be passed as key:=value pairs, JSON blobs, or via stdin.
4. Script / pipe – Add --json to get pure JSON output, then pipe it to jq or other shell utilities.
5. Session management – Sessions can be listed (mcpc), restarted, closed, or cleaned up (mcpc clean). The bridge auto‑reconnects on network hiccups and refreshes OAuth tokens.

---

Installation

• Homebrew (macOS/Linux): brew install mcpc
• npm / Bun: npm install -g @apify/mcpc or bun install -g @apify/mcpc
• On Linux, credentials are stored in the desktop secret‑service; on headless CI it falls back to a 0600‑mode file (~/.mcpc/credentials.json).

---

Example Quickstart

# List sessions / profiles
mcpc

# Log in to a remote MCP server
mcpc login mcp.apify.com

# Create a persistent session named @test
mcpc connect mcp.apify.com @test

# Show server capabilities
mcpc @test

# List available tools
mcpc @test tools-list

# Call a tool (JSON output for scripting)
mcpc --json @test tools-call search-actors keywords:="website crawler"

---

Documentation & Further Reading

• Full command reference: mcpc --help (or the generated REFERENCE.md).
• MCP specification: https://modelcontextprotocol.io/specification/latest
• Security notes: the README explains how config‑file auto‑discovery avoids leaking secrets.
• Related work: a comparison chart in the repo shows how mcpc stacks up against other MCP CLI clients.

---

Bottom line: If you need a reliable, scriptable way for humans or AI agents to interact with MCP servers—handling authentication, sessions, tool discovery, and even payments—mcpc provides a thin, Unix‑friendly wrapper that does all of that without pulling in heavyweight AI libraries.