# Mcpc > A universal CLI client for MCP. mcpc supports persistent sessions, stdio/HTTP, OAuth 2.1, tasks, JSON output for code mode, proxy for AI sandboxes, x402, and more. - **Type:** MCP server - **Install:** `agentstack add mcp-apify-mcpc` - **Verified:** Yes β€” security-reviewed for prompt injection and unsafe behavior - **Seller:** [apify](https://agentstack.voostack.com/s/apify) - **Installs:** 0 - **Category:** [Security](https://agentstack.voostack.com/c/security) - **Latest version:** 0.1.0 - **License:** Apache-2.0 - **Upstream author:** [apify](https://github.com/apify) - **Source:** https://github.com/apify/mcpc - **Website:** https://npmjs.com/package/@apify/mcpc ## Install ```sh agentstack add mcp-apify-mcpc ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # mcpc β€” a universal MCP CLI client [](https://www.npmjs.com/package/@apify/mcpc) [](https://www.npmjs.com/package/@apify/mcpc) [](https://github.com/apify/mcpc/actions/workflows/ci.yml) [](https://github.com/apify/mcpc/blob/main/LICENSE) `mcpc` is a command-line client for the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) that maps every MCP operation to an intuitive command for interactive shell use, scripting, and AI agents. `mcpc` is your new Swiss Army knife for MCP. Reach for it to manually inspect and debug MCP servers, to script repeatable MCP workflows in plain shell, or to give AI coding agents the full power of modern MCP through the most universal interface there is: the UNIX shell. **Key features:** - πŸ”§ [**Full MCP support**](#mcp-support) - Tools, prompts, resources, async tasks, skills, notifications, and logging over stdio and Streamable HTTP. - πŸ”„ **Persistent sessions** - Keep multiple stateful connections to different servers alive in parallel. - πŸ—ΊοΈ **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](https://www.x402.org/) protocol on [Base](https://www.base.org/). ## Table of contents - [Motivation](#motivation) - [Install](#install) - [Quickstart](#quickstart) - [Usage](#usage) - [Sessions](#sessions) - [Authentication](#authentication) - [MCP proxy](#mcp-proxy) - [AI agents](#ai-agents) - [Agentic payments (x402)](#agentic-payments-x402) - [MCP support](#mcp-support) - [Configuration](#configuration) - [Security](#security) - [Errors](#errors) - [Development](#development) - [Related work](#related-work) - [License](#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, and popular conclusion that: _"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 Requires a JavaScript runtime β€” install the latest [Node.js](https://nodejs.org/en/download) or [Bun](https://bun.sh) if you don't have one yet. ```bash npm install -g @apify/mcpc # Or with Bun bun install -g @apify/mcpc ``` **Linux:** credentials use the OS keychain via the [Secret Service API](https://specifications.freedesktop.org/secret-service/). GNOME/KDE desktops work out of the box. On headless/CI systems, `mcpc` falls back to a file-based store (`~/.mcpc/credentials`, mode `0600`). To force the keychain on headless systems, install `libsecret` + `gnome-keyring` (via `apt-get`, `dnf`, or `pacman`) and run: ```bash dbus-run-session -- bash -c "echo -n 'password' | gnome-keyring-daemon --unlock && mcpc ..." ``` ## Quickstart ```bash # List all active sessions and saved authentication profiles mcpc # Login to 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 mcpc @test tools-list 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 config file mcpc connect ./.vscode/mcp.json:filesystem @fs mcpc @fs tools-list ``` ## Usage ``` Usage: mcpc [] [] [options] Universal command-line client for the Model Context Protocol (MCP). Commands: connect [] [@session] Connect to an MCP server and start a new named @session close Close a session restart Restart a session (losing all state) login Log in to a server and save an OAuth profile logout 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 OAuth profile for the server ("default" if not provided) --timeout Request timeout in seconds (default: 60) --max-chars Truncate output to n characters (ignored in --json mode) --insecure Skip TLS certificate verification (for self-signed certs) -v, --version Output the version number -h, --help Display help MCP session commands (after connecting): Show MCP server info, capabilities, and tools overview grep Search tools and instructions tools-list List all server tools tools-get Get tool details and schema tools-call [arg:=val ... | | tasks-list tasks-get tasks-result tasks-cancel prompts-list prompts-get [arg:=val ... | | resources-list resources-read [-o | --raw] resources-subscribe resources-unsubscribe resources-templates-list skills-list skills-get [--raw] logging-set-level ping logs [-n N] [--follow] [--since 1h] Run "mcpc" without arguments to show active sessions and OAuth profiles. Run "mcpc --json" to get the same data as `{ sessions: [...], profiles: [...] }`. Agent guide: mcpc help --skill ``` ### General actions With no arguments, `mcpc` lists all active sessions and saved OAuth profiles: ```bash # 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). ```bash 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 and their status (`● live`, `● connecting`); files that can't be used are shown as `(0 servers)` or `(invalid)` with the reason, rather than silently ignored. Without `--json` the command returns right away without waiting for every connection to finish (still-connecting sessions show `● connecting`); `--json` waits and reports each server's details. ### MCP commands All MCP commands go through a named session created with `connect`: ```bash # 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](#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: ```bash # Key:=value pairs (auto-parsed: tries JSON, falls back to string) mcpc @session tools-call greeting:="hello world" count:=10 enabled:=true mcpc @session tools-call config:='{"key":"value"}' items:='[1,2,3]' # Force string type with JSON quotes mcpc @session tools-call id:='"123"' flag:='"true"' # Inline JSON object (if first arg starts with { or [) mcpc @session tools-call '{"greeting":"hello world","count":10}' # Read from stdin (automatic when no positional args and input is piped) echo '{"greeting":"hello","count":10}' | mcpc @session tools-call cat args.json | mcpc @session tools-call ``` **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: ```bash # 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 only tools. Use `--resources` or `--prompts` to search those types (combine with `--tools` to include tools too). Sessions that are crashed or unavailable are shown with their status rather than silently skipped. The `grep` command is useful for **dynamic tool discovery**, also called [Tool search tool](https://www.anthropic.com/engineering/advanced-tool-use) by Anthropic or [Dynamic context discovery](https://cursor.com/blog/dynamic-context-discovery) by Cursor. Rather than loading all tools into 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 to read by both humans and AIs. With `--json` option, `mcpc` always emits only a single JSON object (or array), to enable [scripting](#scripting). **For all MCP commands, the returned objects are always consistent with the [MCP specification](https://modelcontextprotocol.io/specification/latest).** On success, the JSON object is printed to stdout, on error to stderr. Note that `--json` is not available for `login` and `mcpc --help` commands. ## Sessions MCP is a [stateful protocol](https://modelcontextprotocol.io/specification/latest/basic/lifecycle): clients and servers negotiate protocol version and capabilities, and then communicate within a persistent session. To support these sessions, `mcpc` can start a lightweight **bridge process** that maintains the connection and state. This is more efficient than forcing every MCP command to reconnect and reinitialize, and enables long-term stateful sessions. The sessions are given names prefixed with `@` (e.g. `@apify`), which then serve as unique reference in commands. ```bash # Create a persistent session mcpc connect mcp.apify.com @apify # List all sessions and OAuth profiles mcpc # Run MCP commands in the session mcpc @apify tools-list # Restart the session (kills and restarts the bridge process) mcpc @apify restart # or: mcpc restart @apify # Close the session, terminates bridge process mcpc @apify close # or: mcpc close @apify # ...now session name "@apify" is forgotten and available for future use ``` ### Session lifecycle Session metadata is saved in `~/.mcpc/sessions.json`, [authentication tokens](#authentication) in the OS keychain. The bridge process keeps the session alive with periodic [pings](#ping) and auto-reconnects on network failures or its own crashes (10s cooldown on failed retries). **Session states:** | State | Meaning | | ---------------- | ----------------------------------------------------------------------------------------------- | | 🟒`live` | Bridge process running and server responding | | 🟑`connecting` | Initial bridge startup in progress (`mcpc connect`) | | 🟑`reconnecting` | Bridge crashed or lost auth; auto-reconnecting in the background | | 🟑`disconnected` | Bridge process running but server unreachable; auto-recovers when server responds | | 🟑`crashed` | Bridge process crashed or was killed; auto-reconnects in the background | | πŸ”΄`unauthorized` | Server rejected authentication (401/403) or token refresh failed; re-run `login` then `restart` | | πŸ”΄`expired` | Server rejected session ID (404); requires `restart` | `mcpc` never removes sessions automatically β€” failed ones stay flagged with a recovery hint in the error message. Use `mcpc @apify restart` to kill the bridge and open a fresh `MCP-Session-Id`, or `mcpc @apify close` to remove the session entirely. You can also remove dead sessions by running `mcpc clean`, and all sessions by running `mcpc clean all` (see [Cleanup](#cleanup)). ## Authentication `mcpc` supports all standard [MCP authorization methods](https://modelcontextprotocol.io/specification/latest/basic/authorization). ### Anonymous access For local servers (stdio) or remote servers (Streamable HTTP) which do not require credentials, `mcpc` can be used without authentication: ```bash mcpc connect mcp.apify.com @test mcpc @test tools-list ``` ### Bearer token authentication For remote servers that require a Bearer token (but not OAuth), use the `--header` flag to pass the token. All h … ## Source & license This open-source MCP server is cataloged on AgentStack and links to its original source β€” we do not rehost the code. - **Author:** [apify](https://github.com/apify) - **Source:** [apify/mcpc](https://github.com/apify/mcpc) - **License:** Apache-2.0 - **Homepage:** https://npmjs.com/package/@apify/mcpc Install and usage instructions live in the source repository linked above. ## Pricing - **Free** β€” Free ## Security capabilities Automated source analysis of v0.1.0 β€” what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source β€” more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** β€” security scan: passed β€” Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-apify-mcpc - Seller: https://agentstack.voostack.com/s/apify - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack β€” the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.