Skip to content
Back to search

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.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/apify/mcpc with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/apify/mcpc'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/apify--mcpc/badge.svg)](/listings/apify--mcpc)

HTML

<a href="/listings/apify--mcpc"><img src="/api/listings/apify--mcpc/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

With [Homebrew](https://brew.sh) (macOS and Linux), which brings its own Node.js:

brew install apify/tap/mcpc

Otherwise install the latest [Node.js](https://nodejs.org/en/download) or [Bun](https://bun.sh) 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](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.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 ..."

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 1,659 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # mcpc — a universal MCP CLI client
  2. ![mcpc logo](https://apify.github.io/mcpc/client-logo.svg?v=3)
  3. [![npm version](https://img.shields.io/npm/v/@apify/mcpc.svg)](https://www.npmjs.com/package/@apify/mcpc)
  4. [![npm downloads](https://img.shields.io/npm/dm/@apify/mcpc.svg)](https://www.npmjs.com/package/@apify/mcpc)
  5. [![CI](https://github.com/apify/mcpc/actions/workflows/ci.yml/badge.svg)](https://github.com/apify/mcpc/actions/workflows/ci.yml)
  6. [![License](https://img.shields.io/npm/l/@apify/mcpc.svg)](https://github.com/apify/mcpc/blob/main/LICENSE)
  7. `mcpc` is a command-line client for the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/)
  8. that maps every MCP operation to an intuitive shell command.
  9. Use it to manually inspect and debug MCP servers, to script repeatable MCP workflows in plain shell, or to
  10. give AI agents the full MCP protocol through a single `Bash()` tool call, so they can interact with any MCP
  11. server and its latest capabilities using the most universal programming interface there is: the UNIX shell.
  12. **Key features:**
  13. - 🔧 [**Full MCP support**](#mcp-support) - Tools, prompts, resources, async tasks, skills, notifications, and logging over stdio and Streamable HTTP.
  14. - 🔄 **Persistent sessions** - Keep connections to multiple servers alive in parallel, whether the server protocol is stateful or stateless.
  15. - 🗺️ **Progressive tool discovery** - Find relevant MCP tools on the fly to save tokens and increase accuracy.
  16. - 🔌 **Code mode** - JSON output composes with `jq`, `xargs`, and shell pipelines for MCP workflows as shell scripts.
  17. - 🔒 **Secure** - Full OAuth 2.1 support with CIMD and DCR, uses OS keychain for credentials storage.
  18. - 🤖 **AI sandboxing** - Proxy MCP server connections to protect credentials from AI-generated code.
  19. - 🪶 **Lightweight** - Minimal dependencies, works on Mac/Win/Linux, doesn't use LLMs on its own.
  20. - 💸 **Agentic payments** - Experimental support for the [x402](https://www.x402.org/) protocol on [Base](https://www.base.org/).
  21. `mcpc` is the most [MCP specification](https://modelcontextprotocol.io/specification/latest)-compliant CLI client available:
  22. the only one that covers tools, resources, prompts, async tasks, and skills, plus the OAuth client-credentials and
  23. enterprise-managed authorization extensions, on the latest protocol version. Here's how it compares to other MCP CLI
  24. clients (see [Related work](#related-work) for the full table, legend, and notes):
  25. [![Comparison of MCP CLI clients](https://raw.githubusercontent.com/apify/mcpc/main/docs/images/related-work.svg)](#related-work)
  26. ![mcpc screenshot](https://raw.githubusercontent.com/apify/mcpc/main/docs/images/mcpc-demo.gif?v=3)
  27. ## Table of contents
  28. <!-- START doctoc generated TOC please keep comment here to allow auto update -->
  29. <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
  30. - [Motivation](#motivation)
  31. - [Install](#install)
  32. - [Quickstart](#quickstart)
  33. - [Usage](#usage)
  34. - [Sessions](#sessions)
  35. - [Authentication](#authentication)
  36. - [MCP proxy](#mcp-proxy)
  37. - [AI agents](#ai-agents)
  38. - [Agentic payments (x402)](#agentic-payments-x402)
  39. - [MCP support](#mcp-support)
  40. - [Configuration](#configuration)
  41. - [Security](#security)
  42. - [Errors](#errors)
  43. - [Development](#development)
  44. - [Related work](#related-work)
  45. - [License](#license)
  46. <!-- END doctoc generated TOC please keep comment here to allow auto update -->
  47. ## Motivation
  48. Many AI agents misuse MCP. They treat tools as prompt-time function calls, repeatedly injecting
  49. tool definitions and results into the context. Tokens get wasted, context rots, the
  50. agent gets slower and less reliable — hence the popular conclusion: _"MCP sucks, CLIs are better"_.
  51. `mcpc` challenges that narrative. It maps every MCP operation to an intuitive CLI command that
  52. agents pick up from `--help` alone. Any agent with shell access gets full MCP support without
  53. wiring up dozens of MCP functions. Just one `Bash()` tool, and `mcpc` handles the rest:
  54. ```
  55. ┌──────────┐ Bash() ┌────────┐ MCP ┌────────────┐
  56. │ AI agent │ ─────────► │ mcpc │ ────────► │ MCP server │
  57. └──────────┘ └────────┘ └────────────┘
  58. Sessions, OAuth, Tools,
  59. Resources, Prompts,
  60. Tasks, Skills, x402, ...
  61. ```
  62. CLI is the perfect _local_ interface between agents and MCP, while MCP remains the
  63. standard _remote_ interface for server discovery, authentication, payments, and access control.
  64. The two aren't exclusive – they're complementary.
  65. As a bonus, the same `mcpc` configuration, OAuth profiles, and live sessions can be shared across
  66. many AI agents on the same machine. Authenticate once, reuse everywhere.
  67. ## Install
  68. With [Homebrew](https://brew.sh) (macOS and Linux), which brings its own Node.js:
  69. ```bash
  70. brew install mcpc
  71. ```
  72. Otherwise install the latest [Node.js](https://nodejs.org/en/download) or [Bun](https://bun.sh) first, then:
  73. ```bash
  74. npm install -g @apify/mcpc
  75. # Or with Bun
  76. bun install -g @apify/mcpc
  77. ```
  78. **Linux:** credentials use the OS keychain via the [Secret Service API](https://specifications.freedesktop.org/secret-service/).
  79. GNOME/KDE desktops work out of the box. On headless/CI systems, `mcpc` falls back to a
  80. file-based store (`~/.mcpc/credentials.json`, mode `0600`).
  81. To force the keychain on headless systems, install `gnome-keyring`
  82. (via `apt-get`, `dnf`, or `pacman`) and run:
  83. ```bash
  84. dbus-run-session -- bash -c "echo -n 'password' | gnome-keyring-daemon --unlock && mcpc ..."
  85. ```
  86. ## Quickstart
  87. ```bash
  88. # List all active sessions and saved authentication profiles
  89. mcpc
  90. # Log in to a remote MCP server and save OAuth credentials for future use
  91. mcpc login mcp.apify.com
  92. # Create a persistent session and interact with it
  93. mcpc connect mcp.apify.com @test
  94. mcpc @test # show server info and capabilities
  95. mcpc @test tools-list # list available tools
  96. mcpc @test tools-call search-actors keywords:="website crawler"
  97. # Use JSON mode for scripting
  98. mcpc --json @test tools-list
  99. # Use a local MCP server package (stdio) referenced from a config file
  100. mcpc connect ./.vscode/mcp.json:filesystem @fs
  101. mcpc @fs tools-list
  102. ```
  103. ## Usage
  104. <!-- AUTO-GENERATED: mcpc --help -->
  105. ```
  106. Usage: mcpc [<@session>] [<command>] [options]
  107. Universal command-line client for the Model Context Protocol (MCP).
  108. Commands:
  109. connect [<server>] [@session] Connect to an MCP server and start a new named @session
  110. close <@session> Close a session
  111. restart <@session> Restart a session (losing all state)
  112. login <server> Log in to a server and save an OAuth profile
  113. logout <server> Delete an OAuth profile for a server
  114. clean [resources...] Clean up mcpc data (sessions, profiles, logs, all)
  115. grep <pattern> Search tools and instructions across all active sessions
  116. x402 [subcommand] [args...] Configure an x402 payment wallet (EXPERIMENTAL)
  117. help [command] [subcommand] Show help for a command
  118. Options:
  119. --json Output in JSON format for scripting
  120. --verbose Enable debug logging
  121. --profile <name> OAuth profile for the server ("default" if not provided)
  122. --timeout <seconds> Request timeout in seconds (default: 60)
  123. --max-chars <n> Truncate output to n characters (ignored in --json mode)
  124. --insecure Skip TLS certificate verification (for self-signed certs)
  125. -v, --version Output the version number
  126. -h, --help Display help
  127. MCP session commands (after connecting):
  128. <@session> Show MCP server info, capabilities, and tools overview
  129. <@session> grep <pattern> Search tools and instructions
  130. <@session> tools-list List all server tools
  131. <@session> tools-get <name> Get tool details and schema
  132. <@session> tools-call <name> [arg:=val ... | <json> | <stdin]
  133. <@session> tasks-list
  134. <@session> tasks-get <taskId>
  135. <@session> tasks-result <taskId>
  136. <@session> tasks-cancel <taskId>
  137. <@session> prompts-list
  138. <@session> prompts-get <name> [arg:=val ... | <json> | <stdin]
  139. <@session> completion-complete prompt|resource <ref> <arg:=val ... | <json> | <stdin>
  140. <@session> resources-list
  141. <@session> resources-read <uri> [-o <file> | --raw]
  142. <@session> resources-subscribe <uri> <file>
  143. <@session> resources-unsubscribe <uri>
  144. <@session> resources-templates-list
  145. <@session> resources-directory-read <uri>
  146. <@session> skills-list
  147. <@session> skills-get <skill> [file] [--raw]
  148. <@session> logging-set-level <level>
  149. <@session> ping
  150. <@session> server-discover
  151. <@session> logs [-n N] [--follow] [--since 1h]
  152. Run "mcpc" without arguments to show active sessions and OAuth profiles.
  153. Run "mcpc --json" to get the same data as `{ sessions: [...], profiles: [...] }`.
  154. Agent guide: mcpc help --skill
  155. ```
  156. [REFERENCE.md](docs/REFERENCE.md) collects the full `--help` output of every command in one page.
  157. In your terminal, run `mcpc help <command>` to see the same help for a single command.
  158. ### General actions
  159. With no arguments, `mcpc` lists all active sessions and saved OAuth profiles:
  160. ```bash
  161. # List all sessions and OAuth profiles (also in JSON mode)
  162. mcpc
  163. mcpc --json
  164. # Show command help or version
  165. mcpc --help
  166. mcpc --version
  167. # Clean stale sessions and old log files
  168. mcpc clean
  169. ```
  170. ### Server formats
  171. The `connect`, `login`, and `logout` commands accept a `<server>` argument in these formats:
  172. - **Remote URL** (e.g. `mcp.apify.com` or `https://mcp.apify.com`) — scheme defaults to `https://`
  173. - **Config file entry** (e.g. `~/.vscode/mcp.json:filesystem`) — `file:entry-name` syntax
  174. `connect` additionally supports two **bulk** forms that connect many servers at once:
  175. - **Config file** without an entry (e.g. `~/.vscode/mcp.json`) — connect every server in the file
  176. - **No argument** (`mcpc connect`) — auto-discover MCP config files in the current directory and
  177. your home dir (`.mcp.json`, `mcp.json`, `.cursor/mcp.json`, `.vscode/mcp.json`, `~/.claude.json`,
  178. Claude Desktop, Windsurf, Kiro, …) and connect everything found (run `mcpc connect --help` for the
  179. full list).
  180. ```bash
  181. mcpc connect # discover standard config files and connect all servers
  182. mcpc connect ~/.vscode/mcp.json # connect every server in one file
  183. ```
  184. Bulk connects auto-generate session names (so they don't take an `@session`) and **skip local
  185. stdio servers by default** — pass `--stdio` to include them. Each discovered config file is listed
  186. with its servers, the names of the headers they send, and their status (`● live`, `✗ failed`);
  187. files that can't be used are shown as `(0 servers)` or `(invalid)` with the reason, rather than
  188. silently ignored. The command waits for every handshake to finish (with a progress spinner in
  189. human mode); `--json` reports each server's details. If every server fails to connect, the command
  190. exits with a non-zero code.
  191. **Auto-discovery does not trust config files in the current directory to read environment
  192. variables.** A `.mcp.json` checked into a repository could carry
  193. `"headers": { "X": "${GITHUB_TOKEN}" }` (or `${SECRET}` in a hostname) pointed at an attacker's
  194. server, and a bare `mcpc connect` in that checkout would send the secret on the first request.
  195. So `mcpc connect` skips every project-scope entry that references a `${VAR}` — in `url`, `headers`,
  196. `command`, `args` or `env`, with or without `--stdio` — and shows which variables it would have
  197. read; it also refuses `-H`, which would go to every discovered server. Files under your home
  198. directory are your own and expand `${VAR}` as usual. To connect a skipped entry, review the file
  199. and name it explicitly (`mcpc connect ./.mcp.json`): naming a file is the trust step.
  200. ![mcpc connect skipping a checked-in config that reads ${GITHUB_TOKEN}](https://raw.githubusercontent.com/apify/mcpc/main/docs/vhs/security.gif?v=1)
  201. ### MCP commands
  202. All MCP commands go through a named session created with `connect`:
  203. ```bash
  204. # Connect to a remote server and create a session
  205. mcpc connect mcp.apify.com @apify
  206. mcpc @apify tools-list
  207. mcpc @apify tools-call search-apify-docs query:="What are Actors?"
  208. # Connect to a local server via config file entry
  209. mcpc connect ~/.vscode/mcp.json:filesystem @fs
  210. mcpc @fs tools-list
  211. mcpc @fs tools-call list_directory path:=/
  212. ```
  213. See [MCP support](#mcp-support) for details about all supported MCP features and commands.
  214. #### Command arguments
  215. The `tools-call` and `prompts-get` commands accept arguments as positional parameters after the tool/prompt name:
  216. ```bash
  217. # Key:=value pairs (auto-parsed: tries JSON, falls back to string)
  218. mcpc @session tools-call <tool-name> greeting:="hello world" count:=10 enabled:=true
  219. mcpc @session tools-call <tool-name> config:='{"key":"value"}' items:='[1,2,3]'
  220. # Force string type with JSON quotes
  221. mcpc @session tools-call <tool-name> id:='"123"' flag:='"true"'
  222. # Inline JSON object (if first arg starts with {)
  223. mcpc @session tools-call <tool-name> '{"greeting":"hello world","count":10}'
  224. # Read from stdin (automatic when no positional args and input is piped)
  225. echo '{"greeting":"hello","count":10}' | mcpc @session tools-call <tool-name>
  226. cat args.json | mcpc @session tools-call <tool-name>
  227. ```
  228. **Auto-parsing rules** for `key:=value`: valid JSON keeps its type
  229. (`count:=10` → number, `enabled:=true` → boolean, `cfg:='{"k":"v"}'` → object); anything
  230. else is a string (`greeting:=hello` → `"hello"`). Force a string literal with JSON quotes:
  231. `id:='"123"'`. Inline JSON (an object) is detected when the first arg starts with `{`. Stdin is
  232. read when no positional args are given and input is piped.
  233. **Pitfalls:** no spaces around `:=` (use `query:=hello world`, not `query := ...`); quote
  234. the whole argument when it contains shell expansions (`"query:=${VAR}"`). For complex
  235. inputs, prefer piping JSON via stdin.
  236. ### Grep (search across sessions)
  237. `mcpc grep` searches tools, resources, and prompts across all active sessions or within a single session:
  238. ```bash
  239. # Search tools and server instructions in all active sessions
  240. mcpc grep "search"
  241. # Search within a single session
  242. mcpc @apify grep "actor"
  243. # Search resources and prompts instead of the default tools and instructions
  244. mcpc grep "config" --resources --prompts
  245. # Regex search
  246. mcpc grep "search|find" -E
  247. # Case-sensitive search (default is case-insensitive)
  248. mcpc grep "Search" --case-sensitive
  249. # Limit results
  250. mcpc grep "e" -m 5
  251. # JSON output for scripting
  252. mcpc grep "actor" --json
  253. ```
  254. By default, `grep` searches tools and server instructions. Use `--resources` or `--prompts` to
  255. search those types instead (combine with `--tools` or `--instructions` to mix and match). Sessions
  256. that are crashed or unavailable are shown with their status rather than silently skipped. Like
  257. `grep(1)`, the command exits with code 0 when there are matches and 1 when there are none.
  258. The `grep` command is useful for **dynamic tool discovery**,
  259. also called [Tool search tool](https://www.anthropic.com/engineering/advanced-tool-use) by Anthropic
  260. or [Dynamic context discovery](https://cursor.com/blog/dynamic-context-discovery) by Cursor.
  261. Rather than loading all tools into the AI agent's context, the agent can use `grep` to discover the right tool
  262. for the job, and only load the relevant tools into the context when needed to reduce token usage and improve accuracy.
  263. <!-- TODO: explain this more, show diagram -->
  264. ### JSON mode
  265. By default, `mcpc` prints output in Markdown-ish text format with colors, making it easy for both humans and AIs to read.
  266. With `--json` option, `mcpc` always emits only a single JSON object (or array), to enable [scripting](#scripting).
  267. **For all MCP commands, the returned objects are always consistent with the
  268. [MCP specification](https://modelcontextprotocol.io/specification/latest).**
  269. On success, the JSON object is printed to stdout, on error to stderr.
  270. Note that `--json` is not available for `mcpc --help`. For `login`, `--json` prints a single
  271. `{ profile, serverUrl, scopes }` object on stdout (interactive prompts go to stderr).
  272. ## Sessions
  273. Up to protocol version `2025-11-25`, MCP was a [stateful protocol](https://modelcontextprotocol.io/specification/2025-11-25/basic/lifecycle):
  274. clients and servers negotiate protocol version and capabilities in an `initialize` handshake,
  275. and then communicate within a persistent session. Protocol version `2026-07-28` made MCP
  276. stateless — there is no handshake or server-side session anymore, and every request stands on its own.
  277. `mcpc` keeps one session-based workflow on top of both: you first `connect` a named session,
  278. then interact with the server through it. On stateful servers the session maps directly to the
  279. protocol-level MCP session. On stateless (`2026-07-28`) servers the session abstracts the
  280. protocol away — a lightweight **bridge process** still holds the connection, the negotiated
  281. protocol version, and client-side state, so everything built on "connect first, then interact"
  282. keeps working the same: cached tool listings, [searching across sessions](#grep-search-across-sessions)
  283. with `grep`, server keepalive and status checks by [periodic probing](#ping), change
  284. notifications, resource-to-file syncs, and automatic OAuth token refresh. It is also more
  285. efficient than forcing every MCP command to rediscover the server and reauthenticate.
  286. The protocol version is negotiated automatically (`mcpc @session` shows the result). To pin
  287. one exact version instead, pass `--protocol-version` to `connect` (e.g.
  288. `mcpc connect mcp.apify.com --protocol-version 2025-11-25`) — the connection then fails if the
  289. server does not support that version. Config file entries can set the same via a
  290. `protocolVersion` field.
  291. Sessions are given names prefixed with `@` (e.g. `@apify`),
  292. which then serve as unique references in commands.
  293. ```bash
  294. # Create a persistent session
  295. mcpc connect mcp.apify.com @apify
  296. # List all sessions and OAuth profiles
  297. mcpc
  298. # Run MCP commands in the session
  299. mcpc @apify tools-list
  300. # Restart the session (kills and restarts the bridge process)
  301. mcpc @apify restart # or: mcpc restart @apify
  302. # Close the session (terminates the bridge process)
  303. mcpc @apify close # or: mcpc close @apify
  304. # ...now the session name "@apify" is forgotten and available for future use
  305. ```
  306. ### Session lifecycle
  307. Session metadata is saved in `~/.mcpc/sessions.json`, [authentication tokens](#authentication)
  308. in the OS keychain. The bridge process keeps the session alive with periodic [pings](#ping)
  309. (`server/discover` probes on `2026-07-28` servers) and auto-reconnects on network failures
  310. or its own crashes (10s cooldown on failed retries).
  311. **Session states:**
  312. | State | Meaning |
  313. | ---------------- | ----------------------------------------------------------------------------------------------- |
  314. | 🟢`live` | Bridge process running and server responding |
  315. | 🟡`connecting` | Initial bridge startup in progress (`mcpc connect`) |
  316. | 🟡`reconnecting` | Bridge crashed or lost auth; auto-reconnecting in the background |
  317. | 🟡`disconnected` | Bridge process running but server unreachable; auto-recovers when server responds |
  318. | 🟡`crashed` | Bridge process crashed or was killed; auto-reconnects in the background |
  319. | 🔴`unauthorized` | Server rejected authentication (401/403) or token refresh failed; re-run `login` then `restart` |
  320. | 🔴`expired` | Server rejected session ID (404, stateful servers only); requires `restart` |
  321. `mcpc` never removes sessions automatically — failed ones stay flagged with a recovery hint
  322. in the error message. Use `mcpc @apify restart` to kill the bridge and open a fresh connection
  323. (with a fresh `MCP-Session-Id` on stateful servers), or `mcpc @apify close` to remove the
  324. session entirely.
  325. You can also remove dead sessions by running `mcpc clean`,
  326. and all sessions by running `mcpc clean all` (see [Cleanup](#cleanup)).
  327. ## Authentication
  328. `mcpc` supports all standard [MCP authorization methods](https://modelcontextprotocol.io/specification/latest/basic/authorization).
  329. ### Anonymous access
  330. For local servers (stdio) or remote servers (Streamable HTTP) which do not require credentials,
  331. `mcpc` can be used without authentication:
  332. ```bash
  333. mcpc connect mcp.apify.com @test
  334. mcpc @test tools-list
  335. ```
  336. ### Bearer token authentication
  337. For remote servers that require a Bearer token (but not OAuth), use the `--header` flag to pass the token.
  338. All headers are stored securely in the OS keychain for the session, but they are **not** saved as reusable
  339. [OAuth profiles](#oauth-profiles). This means `--header` must be provided again
  340. whenever you connect a new session.
  341. ```bash
  342. # Create a session with a Bearer token (token saved to keychain for this session only)
  343. mcpc connect https://mcp.apify.com @apify --header "Authorization: Bearer ${APIFY_TOKEN}"
  344. # Use the session (Bearer token is loaded from keychain automatically)
  345. mcpc @apify tools-list
  346. ```
  347. ### OAuth profiles
  348. For OAuth-enabled remote MCP servers, `mcpc` implements the full OAuth 2.1 flow with PKCE as
  349. mandated by the [MCP authorization spec](https://modelcontextprotocol.io/specification/2026-07-28/basic/authorization):
  350. `WWW-Authenticate` 401 challenges, Protected Resource Metadata and authorization server metadata
  351. discovery, all three [client registration approaches](#client-registration-approaches),
  352. [resource indicators (RFC 8707)](https://www.rfc-editor.org/rfc/rfc8707), and automatic
  353. refresh-token rotation.
  354. The OAuth authentication **always** needs to be initiated by the user calling the `login` command,
  355. which opens a web browser with a login screen. `mcpc` never opens the web browser on its own.
  356. The OAuth credentials for specific servers are securely stored as **authentication profiles** - reusable
  357. credentials that allow you to:
  358. - Authenticate once, use credentials across multiple commands or sessions
  359. - Use different accounts (profiles) with the same server
  360. - Manage credentials independently from sessions
  361. Key concepts:
  362. - **Authentication profile**: Named set of OAuth credentials for a specific server (stored in `~/.mcpc/profiles.json` + OS keychain)
  363. - **Session**: Active connection to a server that may reference an authentication profile (stored in `~/.mcpc/sessions.json`)
  364. - **Default profile**: When `--profile` is not specified, `mcpc` uses the authentication profile named `default`
  365. **Example:**
  366. ```bash
  367. # Login to server and save 'default' authentication profile for future use
  368. mcpc login mcp.apify.com
  369. # Use named authentication profile instead of 'default'
  370. mcpc login mcp.apify.com --profile work
  371. # Create two sessions using the two different credentials
  372. mcpc connect mcp.apify.com @apify-personal
  373. mcpc connect mcp.apify.com @apify-work --profile work
  374. # Both sessions now work independently
  375. mcpc @apify-personal tools-list # Uses personal account
  376. mcpc @apify-work tools-list # Uses work account
  377. # Re-authenticate existing profile (e.g., to refresh or change scopes)
  378. mcpc login mcp.apify.com --profile work
  379. # Delete "default" and "work" authentication profiles
  380. mcpc logout mcp.apify.com
  381. mcpc logout mcp.apify.com --profile work
  382. ```
  383. ### Client registration approaches
  384. When logging in, `mcpc` supports all three OAuth client registration approaches defined in the
  385. [MCP authorization spec](https://modelcontextprotocol.io/specification/2026-07-28/basic/authorization#client-registration-approaches),
  386. picking the one the authorization server advertises in its OAuth metadata:
  387. | **Approach** | **`mcpc login` flags** |
  388. | :-------------------------------------- | :---------------------------------------------------------------------------- |
  389. | **Pre-registration** | `--client-id` (and optional `--client-secret`) |
  390. | **Client ID Metadata Documents (CIMD)** | default (or `--client-metadata-url <url>`) |
  391. | **Dynamic Client Registration (DCR)** | fallback (or force with `--no-client-metadata-url` or `--client-name <name>`) |
  392. `mcpc` ships with a hosted [Client ID Metadata Document](https://apify.github.io/mcpc/client-metadata.json)
  393. so every installation presents the same client identity to CIMD-capable authorization servers.
  394. When the authorization server advertises `client_id_metadata_document_supported: true`, the CIMD
  395. URL is used as the `client_id`; otherwise mcpc falls back to Dynamic Client Registration.
  396. ```bash
  397. # Default: mcpc's hosted CIMD is used automatically (no flags needed).
  398. mcpc login mcp.apify.com
  399. # Pre-registered OAuth client (public or confidential) — skips CIMD.
  400. mcpc login mcp.example.com --client-id <id> [--client-secret <secret>]
  401. # Pre-registered client whose redirect URI was registered with localhost
  402. # instead of 127.0.0.1 (e.g. http://localhost:3118/callback).
  403. mcpc login mcp.example.com --client-id <id> --callback-host localhost --callback-port 3118
  404. # Custom CIMD: override the default with your own hosted document.
  405. mcpc login mcp.example.com --client-metadata-url https://example.com/my-client.json
  406. # Disable CIMD: force Dynamic Client Registration even if the server supports CIMD.
  407. mcpc login mcp.example.com --no-client-metadata-url
  408. # Dynamic Client Registration under a client name other than "mcpc" (disables CIMD).
  409. mcpc login mcp.example.com --client-name "My Agent"
  410. ```
  411. See the [MCP authorization spec](https://modelcontextprotocol.io/specification/2026-07-28/basic/authorization#client-registration-approaches)
  412. for details on each approach and the format of Client ID Metadata Documents.
  413. ### MCP authorization extensions
  414. Besides the interactive browser login, `mcpc` supports two official
  415. [MCP authorization extensions](https://modelcontextprotocol.io/extensions/client-matrix),
  416. selected with `mcpc login --grant <grant>`. Both save an [authentication profile](#oauth-profiles) like
  417. a regular login, and `mcpc` declares both extensions to every server it connects to.
  418. #### OAuth client credentials
  419. The [`io.modelcontextprotocol/oauth-client-credentials`](https://modelcontextprotocol.io/extensions/auth/oauth-client-credentials)
  420. extension is for non-interactive, machine-to-machine use such as CI/CD and daemons — no browser:
  421. `mcpc login <server> --grant client-credentials --client-id <id> --client-secret <secret>`
  422. (or a private-key JWT assertion via `--client-key`, RFC 7523). Access tokens are fetched and
  423. refreshed automatically; pin a non-discoverable token endpoint with `--token-endpoint <url>`.
  424. #### Enterprise-managed authorization
  425. The [`io.modelcontextprotocol/enterprise-managed-authorization`](https://modelcontextprotocol.io/extensions/auth/enterprise-managed-authorization)
  426. extension (SEP-990) is for organizations that control MCP server access centrally through their
  427. identity provider (e.g. Okta). You sign in once with corporate SSO, and mcpc then obtains MCP
  428. server tokens via identity assertion grants (ID-JAG) — no per-server consent screens:
  429. ```bash
  430. mcpc login mcp.example.com --grant id-jag \
  431. --idp https://acme.okta.com --idp-client-id <idp-client> \
  432. --client-id <mcp-as-client> --client-secret <secret>
  433. ```
  434. Both clients are pre-registered by your IT team: `--idp-client-id` at the enterprise IdP
  435. (add `--idp-client-secret` for confidential clients), `--client-id`/`--client-secret` at the
  436. MCP server's authorization server. The SSO session is kept alive with the IdP's refresh token;
  437. when it expires, affected sessions turn `unauthorized` with a re-login hint.
  438. See [MCP extensions](#mcp-extensions) for the full list of extensions `mcpc` supports.
  439. ### Authentication precedence
  440. When connecting, `mcpc` picks one auth source based on the flags you pass — explicit flags
  441. always win over stored profiles, and credentials are never silently downgraded. If a profile
  442. is missing, expired, or invalid, `mcpc` fails with an error that includes the right
  443. `mcpc login` command to recover.
  444. | Flag | Behavior |
  445. | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
  446. | `--header "Authorization: ..."` | Use explicit header; skip OAuth auto-detection. Cannot combine with `--profile`. |
  447. | `--profile <name>` | Require the named profile to exist. |
  448. | `--no-profile` | Connect anonymously even if a `default` profile exists. |
  449. | `--x402 [scheme]` | Skip OAuth auto-detection; use x402 payments instead. Optional scheme: `auto` (default), `upto`, `exact`. Combine with `--profile` to use both. |
  450. | _(none)_ | Use `default` profile if it exists; otherwise connect anonymously. |
  451. Headers set on a config file entry (`file:entry`) apply to the server that entry describes.
  452. ```bash
  453. # Default: 'default' profile if it exists, else anonymous
  454. mcpc connect mcp.apify.com @apify-personal
  455. # Specific profile (fails if missing)
  456. mcpc connect mcp.apify.com @apify-work --profile work
  457. # Explicit bearer token (no profile)
  458. mcpc connect mcp.apify.com @apify --header "Authorization: Bearer ${APIFY_TOKEN}"
  459. # Skip default profile, connect anonymously
  460. mcpc connect mcp.apify.com @apify-anon --no-profile
  461. # x402 micropayments instead of OAuth
  462. mcpc connect mcp.example.com @paid --x402
  463. ```
  464. ## MCP proxy
  465. For stronger isolation, `mcpc` can expose an MCP session as a new local proxy MCP server using the `--proxy` option.
  466. The proxy forwards all MCP requests to the upstream server but **never exposes the original authentication tokens** to the client.
  467. This is useful when you want to give someone or something MCP access without revealing your credentials.
  468. The proxy itself serves protocol `2025-11-25` to its clients, regardless of the protocol
  469. version negotiated with the upstream server. See also [AI sandboxes](#ai-sandboxes).
  470. ```bash
  471. # Human authenticates to a remote server
  472. mcpc login mcp.apify.com
  473. # Create authenticated session with proxy server on localhost:8080
  474. mcpc connect mcp.apify.com @open-relay --proxy 8080
  475. # Now any MCP client can connect to proxy like to a regular MCP server
  476. # The client has NO access to the original OAuth tokens or HTTP headers
  477. # Note: localhost/127.0.0.1 URLs default to http:// (no scheme needed)
  478. mcpc connect localhost:8080 @sandboxed
  479. mcpc @sandboxed tools-call search-actors keywords:="web scraper"
  480. # Optionally protect the proxy with a bearer token (stored in the OS keychain)
  481. mcpc connect mcp.apify.com @secure-relay --proxy 8081 --proxy-bearer-token secret123
  482. # To use the proxy, the caller needs to pass the bearer token in the Authorization header
  483. mcpc connect localhost:8081 @sandboxed2 --header "Authorization: Bearer secret123"
  484. ```
  485. **Proxy options for `connect` command:**
  486. | Option | Description |
  487. | ------------------------------ | ------------------------------------------------------------------------------ |
  488. | `--proxy [host:]port` | Start proxy MCP server. Default host: `127.0.0.1` (localhost only) |
  489. | `--proxy-bearer-token <token>` | Requires `Authorization: Bearer <token>` header to access the proxy MCP server |
  490. **Security model:**
  491. - **Localhost by default**: `--proxy 8080` binds to `127.0.0.1` only, preventing network access
  492. - **Tokens hidden**: Original OAuth tokens and/or HTTP headers are never exposed to proxy clients
  493. - **Optional auth**: Use `--proxy-bearer-token` to add another layer of security
  494. - **Explicit opt-in**: Proxy only starts when `--proxy` flag is provided
  495. **Binding to network interfaces:**
  496. ```bash
  497. # Localhost only (default, most secure)
  498. mcpc connect mcp.apify.com @relay --proxy 8080
  499. # Bind to all interfaces (allows network access - use with caution!)
  500. mcpc connect mcp.apify.com @relay --proxy 0.0.0.0:8080
  501. # Bind to specific interface
  502. mcpc connect mcp.apify.com @relay --proxy 192.168.1.100:8080
  503. ```
  504. When listing sessions, proxy info is displayed prominently:
  505. ```bash
  506. mcpc
  507. # @relay → https://mcp.apify.com (HTTP, OAuth: default) [proxy: 127.0.0.1:8080]
  508. ```
  509. ## AI agents
  510. `mcpc` is designed for CLI-enabled AI agents like Claude Code or Codex CLI, supporting both
  511. interactive **tool calling** and **[code mode](https://www.anthropic.com/engineering/code-execution-with-mcp)**.
  512. **Tool calling mode** - Agents call `mcpc` commands to dynamically explore and interact with MCP servers,
  513. using the default text output. This is similar to how MCP connectors in ChatGPT or Claude work,
  514. but the CLI gives you more flexibility and longer operation timeouts.
  515. ```bash
  516. # Discover available tools
  517. mcpc @server tools-list
  518. # Get tool schema
  519. mcpc @server tools-get search
  520. # Call a tool
  521. mcpc @server tools-call search query:="hello world"
  522. ```
  523. **Code mode** - Once agents understand the server's capabilities, they can write shell
  524. scripts that compose multiple `mcpc` commands with `--json` output — see
  525. [Scripting](#scripting) below. This can be
  526. [more accurate](https://www.anthropic.com/engineering/code-execution-with-mcp) and use
  527. fewer tokens than tool calling for complex workflows. Pair with
  528. [schema validation](#schema-validation) to catch breaking changes early.
  529. ### Scripting
  530. Use `--json` for machine-readable output (stdout on success, stderr on error).
  531. JSON output of all MCP commands follows the [MCP specification](https://modelcontextprotocol.io/specification/latest) strictly.
  532. ```bash
  533. # Chain tools across sessions
  534. mcpc --json @apify tools-call search-actors keywords:="scraper" \
  535. | jq '.content[0].text | fromjson | .items[0].id' \
  536. | xargs -I {} mcpc @apify tools-call get-actor actorId:="{}"
  537. # Batch operations
  538. for tool in $(mcpc --json @server tools-list | jq -r '.[].name'); do
  539. mcpc --json @server tools-get "$tool" > "schemas/$tool.json"
  540. done
  541. ```
  542. For a complete example script, see [`docs/examples/company-lookup.sh`](./docs/examples/company-lookup.sh).
  543. ### Schema validation
  544. The `tools-get` and `tools-call` commands support `--schema` to validate a tool's schema against an expected snapshot. This helps detect breaking changes early in scripts and CI:
  545. ```bash
  546. # Save expected schema
  547. mcpc --json @apify tools-get search-actors > expected.json
  548. # Validate without calling (read-only check)
  549. mcpc @apify tools-get search-actors --schema expected.json
  550. # Validate before calling (fails if schema changed incompatibly)
  551. mcpc @apify tools-call search-actors --schema expected.json keywords:="test"
  552. ```
  553. Available schema validation modes (`--schema-mode`):
  554. - `compatible` (default)
  555. - Input schema: new optional fields OK, required fields must have the same type.
  556. - Output schema: new fields OK, removed required fields cause error.
  557. - `strict` - Both input and output schemas must match exactly, including all fields, types, and descriptions
  558. - `ignore` - Skip validation completely (YOLO)
  559. ### AI sandboxes
  560. To ensure AI coding agents don't perform destructive actions or leak credentials,
  561. it's always a good idea to run them in a code sandbox with limited access to your resources.
  562. The [proxy MCP server](#mcp-proxy) feature provides a security boundary for AI agents:
  563. 1. **Human creates authentication profile**: `mcpc login mcp.apify.com --profile ai-access`
  564. 2. **Human creates session**: `mcpc connect mcp.apify.com @ai-sandbox --profile ai-access --proxy 8080`
  565. 3. **AI runs inside a sandbox**: If the sandbox's access is limited to `localhost:8080`,
  566. it can only interact with the MCP server through the `@ai-sandbox` session,
  567. without access to the original OAuth credentials, HTTP headers, or `mcpc` configuration.
  568. This ensures AI agents operate only with pre-authorized credentials, preventing unauthorized access to MCP servers.
  569. The human controls which servers the AI can access and with what permissions (OAuth scopes).
  570. **IMPORTANT:** Beware that MCP proxy will not make an insecure MCP server secure.
  571. Local stdio servers will still have access to your local system, and HTTP servers to provided auth credentials,
  572. and both can easily perform destructive actions or leak credentials on their own, or let MCP clients do such actions.
  573. **Always use only trusted local and remote MCP servers and limit their access to the necessary minimum.**
  574. ### Agent skills
  575. `mcpc` ships a built-in agent skill that always matches the installed version:
  576. ```bash
  577. mcpc help --skill
  578. ```
  579. No setup is needed: `mcpc help` mentions `mcpc help --skill`, so an agent can discover and load
  580. the guide on its own when it needs it.
  581. If you'd rather have the skill installed persistently (e.g. for Claude Code or any agent that
  582. loads `SKILL.md` files), `mcpc help --skill` prints a valid `SKILL.md` — just redirect it into
  583. your skills directory:
  584. ```bash
  585. mkdir -p ~/.claude/skills/mcpc
  586. mcpc help --skill > ~/.claude/skills/mcpc/SKILL.md
  587. ```
  588. That copy is a snapshot; re-run it after upgrading mcpc to refresh it.
  589. Separately, `mcpc` also acts as a **client for skills served by MCP servers** — see
  590. [Skills](#skills) for the `skills-list` / `skills-get` commands.
  591. ## Agentic payments (x402)
  592. > ⚠️ **Experimental.** This feature is under active development and may change.
  593. `mcpc` has experimental support for the [x402 payment protocol](https://www.x402.org/),
  594. which enables AI agents to autonomously pay for MCP tool calls using cryptocurrency.
  595. When an MCP server charges for a tool call (HTTP 402), `mcpc` automatically signs a USDC payment
  596. on the [Base](https://base.org/) blockchain and retries the request — no human intervention needed.
  597. This is entirely **opt-in**: existing functionality is unaffected unless you explicitly pass the `--x402` flag.
  598. ### How it works
  599. Two schemes are supported, both signed by your local wallet:
  600. - **`exact`** — EIP-3009 `TransferWithAuthorization`. Settles on-chain at call-time.
  601. - **`upto`** — Permit2 `PermitWitnessTransferFrom`. You sign a max cap; the facilitator settles accumulated usage later. First use auto-grants a one-time `USDC.approve(PERMIT2, MAX_UINT256)` (needs a tiny native ETH float for gas).
  602. Flow: server returns HTTP 402 with a `PAYMENT-REQUIRED` header → `mcpc` picks the best scheme per your preference, signs, and retries with `PAYMENT-SIGNATURE` → server verifies and fulfills. Tools that advertise pricing in `_meta.x402` are signed proactively, skipping the 402 round-trip.
  603. ### Settlement receipts
  604. When the server reports the settlement result — as a `PAYMENT-RESPONSE` header or on the tool
  605. result itself — `mcpc` hands it to you at `_meta["x402/payment-response"]` of the tool result,
  606. so a paid call can be reconciled against the on-chain settlement instead of inferred from the
  607. payload. The receipt is passed through exactly as the server sent it:
  608. ```bash
  609. mcpc --json @paid tools-call search query:="web crawler" | jq '._meta["x402/payment-response"]'
  610. # { "success": true, "transaction": "0x…", "network": "eip155:8453", "payer": "0x…" }
  611. ```
  612. Servers are not required to send one, and a missing or malformed receipt never fails the call.
  613. **Run paid calls sequentially if you need every receipt.** `mcpc` holds one receipt at a time per
  614. session, so when paid calls overlap only the most recent receipt is attached — the others are
  615. dropped (and recorded in the bridge log).
  616. ### Wallet setup
  617. `mcpc` stores a single wallet in `~/.mcpc/wallets.json` (file permissions `0600`).
  618. You need to create or import a wallet before using x402 payments.
  619. ```bash
  620. # Create a new wallet (generates a random private key)
  621. mcpc x402 init
  622. # Or import an existing wallet from a private key
  623. mcpc x402 import <private-key>
  624. # Show wallet address, balances, and a funding QR code
  625. mcpc x402
  626. # Remove the wallet
  627. mcpc x402 remove
  628. ```
  629. After creating a wallet, **fund it with USDC on Base** (mainnet or Sepolia testnet) to enable payments.
  630. ### Manual payment signing
  631. You can manually sign a payment from a server's `PAYMENT-REQUIRED` header using `x402 sign`.
  632. This is useful for pre-signing payments or integrating with tools outside of `mcpc`.
  633. ```bash
  634. # Sign a payment using the base64-encoded PAYMENT-REQUIRED header
  635. mcpc x402 sign <base64-payment-required>
  636. # Override the amount (in USD, e.g. 2.50 = $2.50)
  637. mcpc x402 sign <base64-payment-required> --amount 2.50
  638. # Override the expiry (in seconds from now)
  639. mcpc x402 sign <base64-payment-required> --expiry 7200
  640. # Combine overrides and use JSON output
  641. mcpc x402 sign <base64-payment-required> --amount 1.00 --expiry 3600 --json
  642. ```
  643. **Options:**
  644. | Option | Description |
  645. | -------------------- | ----------------------------------------------------------------------- |
  646. | `--amount <usd>` | Override the payment amount in USD (e.g. `0.50` for $0.50) |
  647. | `--expiry <seconds>` | Override the payment expiry in seconds from now (e.g. `3600`) |
  648. | `--scheme <val>` | Scheme preference: `auto` (default, upto > exact), `upto`, or `exact` |
  649. | `--no-approve` | For `upto`, skip checking and auto-approving on-chain Permit2 allowance |
  650. The command outputs the signed `PAYMENT-SIGNATURE` header value and an MCP config snippet
  651. that can be used directly with other MCP clients.
  652. `x402 sign` also works for plain HTTP (non-MCP) x402 v2 endpoints. Read the challenge from the
  653. `PAYMENT-REQUIRED` response header, sign it, then send the request again with the signature:
  654. ```bash
  655. URL=https://api.example.com/paid-resource
  656. REQ=$(curl -s -D - -o /dev/null "$URL" | awk -F': ' 'tolower($1)=="payment-required"{print $2}' | tr -d '\r\n')
  657. SIG=$(mcpc x402 sign "$REQ" --json | jq -r .paymentSignature)
  658. curl -s -D - -H "PAYMENT-SIGNATURE: $SIG" "$URL" # 200 + PAYMENT-RESPONSE header with the settlement tx
  659. ```
  660. ### Using x402 with MCP servers
  661. Pass the `--x402` flag when connecting to a session. It accepts an optional scheme preference
  662. (`auto`, `upto`, or `exact`); bare `--x402` defaults to `auto`.
  663. ```bash
  664. # Create a session with x402 payment support (auto picks the best advertised scheme)
  665. mcpc connect mcp.example.com @paid --x402
  666. # Pin a specific scheme — position doesn't matter, before or after positional args
  667. mcpc connect --x402 upto mcp.example.com @paid
  668. mcpc connect mcp.example.com @paid --x402 exact
  669. # The session now automatically handles 402 responses using your preference
  670. mcpc @paid tools-call expensive-tool query:="hello"
  671. # Restart re-uses the saved scheme from sessions.json — no need to repeat the flag
  672. mcpc @paid restart
  673. ```
  674. When `--x402` is active, a fetch middleware wraps all HTTP requests to the MCP server.
  675. If any request returns HTTP 402, the middleware transparently signs and retries. Your scheme preference is persisted in `sessions.json` and reused on every reconnect or restart.
  676. ### Supported networks
  677. | Network | Status |
  678. | -------------------- | ------------ |
  679. | Base Mainnet | ✅ Supported |
  680. | Base Sepolia testnet | ✅ Supported |
  681. ### Full x402 usage example
  682. This end-to-end example pays for the [Apify MCP server](https://mcp.apify.com) with no account or API key.
  683. [Apify](https://apify.com) is the largest and most trusted marketplace of tools for AI agents,
  684. with thousands of ready-made Actors for web scraping, data extraction, and automation.
  685. [Apify AGI](https://agi.apify.com) sells a prepaid, spend-capped API token for an x402 payment
  686. (`exact` scheme, USDC on Base mainnet), and `mcpc` uses that token as a Bearer credential.
  687. Each tool call is then billed against the token's prepaid balance.
  688. ```bash
  689. # 1. Create a wallet (or import one) and send USDC on Base to the printed address or QR code.
  690. # Signing is gasless, so the wallet needs no ETH.
  691. mcpc x402 init
  692. # Once sent, check that the USDC balance has arrived.
  693. mcpc x402
  694. # 2. Fetch the payment challenge for a $1 token, the minimum (the PAYMENT-REQUIRED header).
  695. URL='https://agi.apify.com/protocols/x402/prepaid-tokens?amount=1&currency=usd'
  696. REQ=$(curl -s -D - -o /dev/null "$URL" | awk -F': ' 'tolower($1)=="payment-required"{print $2}' | tr -d '\r\n')
  697. # 3. Sign it with the wallet and resubmit; the server settles the payment and returns the token.
  698. SIG=$(mcpc x402 sign "$REQ" --scheme exact --json | jq -r .paymentSignature)
  699. TOKEN=$(curl -s -H "PAYMENT-SIGNATURE: $SIG" "$URL" | jq -r .token)
  700. # 4. Connect with the token and use the server as usual.
  701. mcpc connect mcp.apify.com @apify --header "Authorization: Bearer $TOKEN"
  702. mcpc @apify tools-list
  703. mcpc @apify tools-call search-actors keywords:="Google Maps"
  704. # 5. Check how much of the prepaid balance is left.
  705. curl -s -H "Authorization: Bearer $TOKEN" https://agi.apify.com/prepaid-tokens/balance
  706. ```
  707. ![mcpc paying for a prepaid token with x402 and using it with an MCP server](https://raw.githubusercontent.com/apify/mcpc/main/docs/vhs/x402.gif?v=1)
  708. `mcpc` keeps the token only for the `@apify` session, so save `$TOKEN` if you want to reuse it elsewhere.
  709. See [agi.apify.com/AGENTS.md](https://agi.apify.com/AGENTS.md) for current prices, limits, and terms.
  710. ## MCP support
  711. `mcpc` aims to be the most complete MCP client on the command line. It's built on the official
  712. [MCP SDK for TypeScript](https://github.com/modelcontextprotocol/typescript-sdk) and supports all the
  713. major client-facing features of the [MCP specification](https://modelcontextprotocol.io/specification/latest),
  714. from tools, resources, and prompts to the newest additions like async tasks and skills. Each is exposed as
  715. a first-class command with consistent human-readable and `--json` output.
  716. Where `mcpc` stands on each part of the MCP specification:
  717. | **Feature** | **Status** |
  718. |:-----------------------------------------------------|:-----------------------------------------------------------------|
  719. | 📜 **Protocol version** | ✅ 2026-07-28 (auto-negotiated), falls back to 2025-11-25 or older |
  720. | 🔌 **Transport** | ✅ stdio and Streamable HTTP |
  721. | 🔑 [**Authorization**](#authentication) | ✅ Bearer + OAuth 2.1 (client credentials, DCR, CIMD, auth code) |
  722. | 🔄 [**Sessions**](#sessions) | ✅ Supported (with automatic keepalive) |
  723. | 📖 [**Server instructions**](#server-instructions) | ✅ Supported |
  724. | 🔧 [**Tools**](#tools) | ✅ Supported (incl. list changed notifications) |
  725. | ⏳ [**Async tasks**](#async-tasks) | ✅ Supported (2025-11-25 core tasks and the 2026-07-28 tasks extension) |
  726. | 💬 [**Prompts**](#prompts) | ✅ Supported (incl. list changed notifications) |
  727. | 📦 [**Resources**](#resources) | ✅ Supported (incl. subscriptions and list changed notifications) |
  728. | 🧠 [**Skills**](#skills) | ✅ Supported (skills extension, 2026-07-28 servers) |
  729. | 📝 [**Logging**](#server-logs) | ⚠️ Deprecated (removed by MCP 2026-07-28) |
  730. | 🔔 [**Notifications**](#list-change-notifications) | ✅ Supported |
  731. | 📄 [**Pagination**](#pagination) | ✅ Supported |
  732. | 🏓 [**Ping**](#ping) | ✅ Supported |
  733. | 🔍 [**Server discovery**](#server-discovery) | ✅ Supported (`server/discover`, 2026-07-28 servers) |
  734. | 📁 **Roots** | ❌ Not planned (deprecated by MCP) |
  735. | ❓ **Elicitation** | 🚧 Planned |
  736. | 🔤 [**Completion**](#completion) | ✅ Supported |
  737. | 🤖 **Sampling** | ❌ Not applicable (no LLM access) |
  738. Beyond the interactive browser login, the **Authorization** row also covers the two
  739. [MCP authorization extensions](#mcp-authorization-extensions): OAuth client credentials and
  740. enterprise-managed authorization.
  741. ### MCP extensions
  742. Extensions are the optional, modular parts of MCP, negotiated through the `extensions` field of
  743. client and server capabilities. Where `mcpc` stands on the
  744. [official ones](https://modelcontextprotocol.io/extensions/client-matrix):
  745. | **Extension** | **Identifier** | **Status** |
  746. |:----------------------------------------------------------------------------------------------------------------|:------------------------------------------------------------|:--------------------------------------------------------------------------------|
  747. | [OAuth client credentials](https://modelcontextprotocol.io/extensions/auth/oauth-client-credentials) | `io.modelcontextprotocol/oauth-client-credentials` | ✅ `mcpc login <server> --grant client-credentials` |
  748. | [Enterprise-managed authorization](https://modelcontextprotocol.io/extensions/auth/enterprise-managed-authorization) | `io.modelcontextprotocol/enterprise-managed-authorization` | ✅ `mcpc login <server> --grant id-jag` |
  749. | [Skills](https://modelcontextprotocol.io/extensions/skills/overview) | `io.modelcontextprotocol/skills` | ✅ [`skills-list`, `skills-get`, `resources-directory-read`](#skills) (MCP 2026-07-28 servers) |
  750. | [MCP Apps](https://modelcontextprotocol.io/extensions/apps/overview) | `io.modelcontextprotocol/ui` | ❌ Interactive HTML interfaces have no equivalent on a terminal |
  751. | [Tasks](https://modelcontextprotocol.io/extensions/tasks/overview) | `io.modelcontextprotocol/tasks` | ✅ [`tools-call --task/--detach`, `tasks-get`, `tasks-result`, `tasks-cancel`, `tasks-list`](#async-tasks) (MCP 2026-07-28 servers) |
  752. The two auth extensions and tasks are the ones a client declares: `mcpc` declares all three to
  753. every server it connects to, so a server can tell what this client can do before any token is
  754. issued, and can answer a tool call with a task handle. Skills is declared by servers only — a
  755. client issues `skills/list` and `skills/get` once it sees that declaration. `mcpc @session` lists
  756. what a server declares in return, and says which of those `mcpc` can use.
  757. ### Server instructions
  758. MCP servers can provide instructions describing their capabilities and usage. These are displayed when you connect to a server or show its session overview:
  759. ```bash
  760. # Show server info, capabilities, and instructions
  761. mcpc @apify
  762. # JSON mode
  763. mcpc @apify --json
  764. ```
  765. In [JSON mode](#json-mode), the resulting object adheres to the schema of the server's
  766. handshake result — [`InitializeResult`](https://modelcontextprotocol.io/specification/2025-11-25/schema#initializeresult)
  767. on `2025-11-25` connections, [`DiscoverResult`](https://modelcontextprotocol.io/specification/2026-07-28/schema#discoverresult)
  768. on `2026-07-28` ones — and includes the `_mcpc` field with relevant server/session metadata.
  769. `protocolVersion` is always the version actually in use, while `supportedVersions` (every
  770. version the server offers) and `_meta` come from `server/discover` and are therefore absent
  771. on `2025-11-25` connections.
  772. ```json
  773. {
  774. "_mcpc": {
  775. "sessionName": "@apify",
  776. "profileName": "default",
  777. "server": {
  778. "url": "https://mcp.apify.com"
  779. },
  780. "notifications": {
  781. "tools": { "listChangedAt": "2026-01-01T00:42:58.049Z" }
  782. }
  783. },
  784. "protocolVersion": "2026-07-28",
  785. "supportedVersions": ["2026-07-28", "2025-11-25"],
  786. "capabilities": {
  787. "logging": {},
  788. "prompts": {},
  789. "resources": {},
  790. "tools": { "listChanged": true }
  791. },
  792. "serverInfo": {
  793. "name": "apify-mcp-server",
  794. "version": "1.0.0"
  795. },
  796. "instructions": "Apify is the largest marketplace of tools for web scraping...",
  797. "_meta": {
  798. "io.modelcontextprotocol/serverInfo": {
  799. "name": "apify-mcp-server",
  800. "version": "1.0.0"
  801. }
  802. }
  803. }
  804. ```
  805. ### Tools
  806. Tools are the heart of MCP, and `mcpc` gives you the whole toolbox to discover, inspect, validate, and call them:
  807. ```bash
  808. # List tools (compact view): names, one-line descriptions, and safety/task hints
  809. mcpc @apify tools-list
  810. # List tools with full input/output schemas and descriptions
  811. mcpc @apify tools-list --full
  812. # Inspect a single tool's schema, annotations, and a ready-to-run example
  813. mcpc @apify tools-get search-actors
  814. # Call a tool with arguments
  815. mcpc @apify tools-call search-actors keywords:="web scraper"
  816. # Pass complex JSON arguments
  817. mcpc @apify tools-call create-task '{"name": "my-task", "options": {"memory": 1024}}'
  818. # Load arguments from stdin
  819. cat data.json | mcpc @apify tools-call bulk-import
  820. ```
  821. The compact `tools-list` is built for **[progressive tool discovery](#grep-search-across-sessions)**:
  822. instead of loading every tool's full schema into an agent's context up front, list just names and
  823. summaries, use `mcpc grep` to find the right tool for the task, and pull its full schema with
  824. `tools-get` only when you need it. Fewer tokens, less context rot, better accuracy. And listings never
  825. go stale: the [session](#sessions) bridge handles `tools/list_changed`
  826. [notifications](#list-change-notifications) and refreshes its cache automatically, so you always see the
  827. server's current tools.
  828. `mcpc` surfaces everything modern MCP tools can express:
  829. - **Safety annotations**: `read-only`, `destructive`, `idempotent`, and `open-world` hints are shown
  830. right next to each tool, so a human or an agent can tell a harmless query from a dangerous mutation
  831. before calling it.
  832. - **Structured output**: tool results show `structuredContent` as JSON when no other content remains
  833. after removing duplicate text blocks. Otherwise a hint points to `--json`, which includes the full
  834. result. Output schemas are shown with `tools-list --full` and `tools-get`.
  835. - **Rich result content**: text, images, audio, and [resource links or embedded resources](#resources)
  836. in tool results are all rendered (binary is summarized, never dumped to your terminal).
  837. - **Async tasks**: long-running tools can run in the background as [async tasks](#async-tasks); each
  838. tool's task support is flagged as `[task:optional]`, `[task:required]`, or `[task:forbidden]`.
  839. - **Schema validation**: pin a tool's schema with `--schema` to catch breaking changes in CI and
  840. scripts before they bite (see [Schema validation](#schema-validation)).
  841. ### Prompts
  842. List and retrieve server-defined prompt templates:
  843. ```bash
  844. # List available prompts
  845. mcpc @apify prompts-list
  846. # Get a prompt with arguments
  847. mcpc @apify prompts-get analyze-website url:=https://example.com
  848. ```
  849. <!-- TODO: Add example of prompt templates -->
  850. ### Resources
  851. Access server-provided data sources by URI:
  852. ```bash
  853. # List available resources
  854. mcpc @apify resources-list
  855. # Read a resource (pretty view; binary content is summarized, never dumped)
  856. mcpc @apify resources-read "file:///config.json"
  857. # Print just the content for piping
  858. mcpc @apify resources-read "file:///config.json" --raw | jq .
  859. # Save a resource to a local file (binary-safe, decodes base64 blobs)
  860. mcpc @apify resources-read "file:///logo.png" -o logo.png
  861. # List resource templates
  862. mcpc @apify resources-templates-list
  863. ```
  864. Subscriptions keep a local file in sync with a server resource. On subscribe, mcpc downloads
  865. the resource to the file; afterwards the session bridge rewrites the file whenever the server
  866. sends a `notifications/resources/updated` notification for the URI (the bridge re-reads the
  867. resource, as the notification carries no content). Requires the server capability
  868. `resources.subscribe`; subscriptions are re-established automatically when the session
  869. reconnects or restarts, and are listed in `mcpc @session` output. On the wire, mcpc uses
  870. `resources/subscribe` on `2025-11-25` servers and a `subscriptions/listen` stream on
  871. `2026-07-28` servers (re-opened automatically if it drops) — the commands are identical.
  872. ```bash
  873. # Keep ./config.json in sync with the server resource
  874. mcpc @apify resources-subscribe "file:///config.json" ./config.json
  875. # Stop syncing — the local file is kept as-is
  876. mcpc @apify resources-unsubscribe "file:///config.json"
  877. ```
  878. ### Completion
  879. Servers that declare the `completions` capability can suggest values for prompt arguments and
  880. resource template variables
  881. ([`completion/complete`](https://modelcontextprotocol.io/specification/latest/server/utilities/completion)).
  882. Arguments use the `prompts-get` syntax: the last one is the argument being completed, with the text
  883. typed so far as its value (empty for none), and any arguments before it are sent as context so the
  884. server can narrow its suggestions:
  885. ```bash
  886. # Suggest values for a prompt argument from what's typed so far
  887. mcpc @apify completion-complete prompt code_review language:=py
  888. # Earlier arguments are context: complete "framework" for a Python code review
  889. mcpc @apify completion-complete prompt code_review language:=python framework:=fla
  890. # Complete a variable of a resource template
  891. mcpc @apify completion-complete resource 'file:///{path}' path:=/ho
  892. ```
  893. Servers return at most 100 suggestions ranked by relevance; `hasMore` in the `--json` output says
  894. whether there were more. Completion works the same on `2025-11-25` and `2026-07-28` servers.
  895. ### Skills
  896. Implements the [MCP Skills extension](https://github.com/modelcontextprotocol/ext-skills)
  897. (`io.modelcontextprotocol/skills`), which requires MCP `2026-07-28` or later.
  898. [Agent Skills](https://agentskills.io/) are reusable markdown workflow instructions (`SKILL.md` with YAML
  899. frontmatter, plus any supporting files) that AI agents load on demand. A server that declares the extension
  900. publishes them over `skills/list` and `skills/get`, and serves their files as ordinary `skill://` resources:
  901. ```bash
  902. # List the skills the server serves, with their file manifests
  903. mcpc @apify skills-list
  904. # Read a skill's SKILL.md by name, path, or the URI of its SKILL.md
  905. mcpc @apify skills-get git-workflow
  906. mcpc @apify skills-get acme/billing/refunds
  907. mcpc @apify skills-get skill://git-workflow/SKILL.md
  908. # Read one of the skill's supporting files
  909. mcpc @apify skills-get pdf-processing references/FORMS.md
  910. # Print just the content (no header/fences) — pipe straight to an LLM or a file
  911. mcpc @apify skills-get git-workflow --raw > /tmp/SKILL.md
  912. # JSON for scripts: [{ uri, frontmatter: { name, description, ... }, resources }]
  913. mcpc --json @apify skills-list | jq -r '.[].frontmatter.name'
  914. # List a directory inside a skill (servers that declare "directoryRead": true)
  915. mcpc @apify resources-directory-read skill://pdf-processing/templates
  916. ```
  917. ![mcpc skills-list and skills-get demo](https://raw.githubusercontent.com/apify/mcpc/main/docs/vhs/skills.gif?v=1)
  918. Every entry from `skills-list` is complete: the skill's verbatim frontmatter plus a manifest of every
  919. file with its SHA-256 digest and byte size. `skills-get` uses that manifest as the spec requires —
  920. it fetches the entry, reads the file, and checks the bytes against the declared size and digest (and, for
  921. a `SKILL.md`, that the document's frontmatter is what the entry advertised). **Content that fails any of
  922. those checks is not printed**, and a file missing from the manifest is refused rather than read. Skills
  923. whose content is generated carry `"resources": "dynamic"` instead of a manifest; `mcpc` reads them but
  924. labels them unverified.
  925. Skills appear under capabilities in `mcpc @session` output when a server declares the extension in
  926. `capabilities.extensions["io.modelcontextprotocol/skills"]`. Skill content is treated as untrusted
  927. input — `mcpc` only reads and prints it; it never executes hooks, scripts, or other frontmatter-declared
  928. behavior, and `allowed-tools` grants nothing.
  929. ### List change notifications
  930. When connected via a [session](#sessions), `mcpc` automatically handles `list_changed`
  931. notifications for tools, resources, and prompts. On `2025-11-25` servers these arrive as
  932. unsolicited notifications; on `2026-07-28` servers (where unsolicited notifications no
  933. longer exist) the session bridge opts in by opening a `subscriptions/listen` stream at
  934. connect and re-opens it automatically if it drops — the behavior is identical from the
  935. outside. As a safety net on `2026-07-28` connections, the bridge's tools cache also
  936. expires after 60 seconds, so a missed notification can never leave `tools-list` or
  937. [`grep`](#grep-search-across-sessions) stale for long.
  938. The bridge process tracks when each notification type was last received.
  939. The timestamps are available in the JSON output of `mcpc @session --json` under the `_mcpc.notifications`
  940. field - see [Server instructions](#server-instructions).
  941. ### Server logs
  942. `mcpc` supports server logging settings (`logging/setLevel`) and log messages (`notifications/message`).
  943. Log messages are printed to bridge log or stderr, subject to [verbosity level](#verbose-mode).
  944. You can instruct MCP servers to adjust their [logging level](https://modelcontextprotocol.io/specification/latest/server/utilities/logging)
  945. using the `logging-set-level` command:
  946. ```bash
  947. # Set server log level to debug for detailed output
  948. mcpc @apify logging-set-level debug
  949. # Reduce server logging to only errors
  950. mcpc @apify logging-set-level error
  951. ```
  952. Note that this sets the logging level on the **server side**.
  953. The actual log output depends on the server's implementation.
  954. > ⚠️ **Deprecated.** MCP `2026-07-28` removed `logging/setLevel`, so `logging-set-level` works
  955. > only on servers using protocol `2025-11-25` or older and will be removed in a future mcpc
  956. > release. Server log messages (`notifications/message`) are still recorded in the bridge log.
  957. ### Pagination
  958. MCP servers may return paginated results for list operations
  959. (`tools-list`, `resources-list`, `prompts-list`, `resources-templates-list`).
  960. `mcpc` handles this automatically and always fetches all available pages using the `nextCursor`
  961. token - you always get the complete list without manual iteration. Keep it simple.
  962. ### Ping
  963. Sessions automatically send periodic pings to keep the [connection alive](#session-lifecycle) and detect failures early.
  964. Send a ping to check if a server connection is alive:
  965. ```bash
  966. # Ping a session and measure round-trip time
  967. mcpc @apify ping
  968. mcpc @apify ping --json
  969. ```
  970. Protocol version `2026-07-28` removed the `ping` request, so on servers using it `mcpc`
  971. sends a `server/discover` probe instead — same round trip, same liveness signal, and the
  972. command works identically on both protocol versions. The human-readable output says so,
  973. so a `server/discover` entry in the server's access log is not a surprise.
  974. ### Server discovery
  975. On `2026-07-28` connections you can also send that request yourself and see what the server
  976. answers right now — every protocol version it supports, its capabilities, its instructions,
  977. and its `_meta`:
  978. ```bash
  979. mcpc @apify server-discover
  980. mcpc @apify server-discover --json # DiscoverResult, verbatim
  981. ```
  982. Unlike [`mcpc @apify`](#server-instructions), which reports what the connection settled on
  983. when it was created, this is a live request. Protocol `2026-07-28` introduced
  984. `server/discover`, so the command fails on `2025-11-25` (and older) connections, where the
  985. `initialize` handshake carries the same information — run `mcpc @apify` there instead.
  986. ### Async tasks
  987. MCP servers can execute tools as [async tasks](https://modelcontextprotocol.io/specification/latest/basic/utilities/tasks)
  988. that run in the background and report progress. `mcpc` supports the full task lifecycle:
  989. ```bash
  990. # Call a tool as a task (waits for completion, shows progress spinner)
  991. mcpc @apify tools-call long-running-job input:="data" --task
  992. # Start a task and return immediately with the task ID
  993. mcpc @apify tools-call long-running-job input:="data" --detach
  994. # List active tasks
  995. mcpc @apify tasks-list
  996. # Check task status
  997. mcpc @apify tasks-get <taskId>
  998. # Get the task result (blocks until the task reaches a terminal state)
  999. mcpc @apify tasks-result <taskId>
  1000. # Cancel a running task
  1001. mcpc @apify tasks-cancel <taskId>
  1002. ```
  1003. ![mcpc tools-call --task, --detach and tasks-result demo](https://raw.githubusercontent.com/apify/mcpc/main/docs/vhs/tasks.gif?v=1)
  1004. With `--task`, the CLI shows a progress spinner with elapsed time, server status messages,
  1005. and progress notifications. Press **ESC** during execution to detach and get the task ID
  1006. for later retrieval. With `--detach`, the task starts and its ID is printed immediately
  1007. (`--json` prints the whole created `Task`: ID, status, TTL, poll interval). Use
  1008. `tasks-result <taskId>` to fetch the final `CallToolResult` payload once the task completes.
  1009. Tasks exist in two forms, and `mcpc` speaks both behind the same commands:
  1010. - On MCP `2025-11-25` servers tasks are part of the core protocol. The server advertises the
  1011. `tasks` capability, `tools-list` and `tools-get` flag per-tool support as `[task:optional]`,
  1012. `[task:required]` or `[task:forbidden]`, and the client asks for a task with `--task`.
  1013. - On MCP `2026-07-28` servers tasks are the [`io.modelcontextprotocol/tasks`](https://modelcontextprotocol.io/extensions/tasks/overview)
  1014. extension, which `mcpc` declares on every request. Task creation is the **server's** call:
  1015. a server that declares the extension may answer any `tools-call` with a task, which `mcpc`
  1016. then polls (at the interval the server asks for) until the result is in — with or without
  1017. `--task`. Conversely, a `--detach` call the server chooses to run synchronously prints the
  1018. tool result instead of a task, so scripts should check for `taskId`. The extension has no
  1019. server-side listing, so `tasks-list` shows the tasks the session created and the server
  1020. still knows, and `tasks-cancel` reports the status the server shows right after
  1021. acknowledging the request (cancellation is cooperative there). A task that stops to ask
  1022. for input (`input_required`) is reported as an error — `mcpc` never prompts.
  1023. When a server offers neither, `--task`/`--detach` and the `tasks-*` commands fail with an
  1024. error saying so — they never fall back to a plain synchronous call, because the flags change
  1025. the shape of the output and `--detach` callers would be left parsing a task ID that is not
  1026. there.
  1027. ## Configuration
  1028. You can configure `mcpc` using a config file, environment variables, or command-line flags.
  1029. **Precedence** (highest to lowest):
  1030. 1. Command-line flags and config file entries (`file:entry`)
  1031. 2. Environment variables
  1032. 3. Built-in defaults
  1033. ### MCP server config file
  1034. `mcpc` supports the ["standard"](https://gofastmcp.com/integrations/mcp-json-configuration)
  1035. MCP server JSON config file, compatible with Claude Desktop, VS Code, and other MCP clients.
  1036. Use the `file:entry` syntax to reference a server from a config file:
  1037. ```bash
  1038. # Open a session to a server specified in the Visual Studio Code config
  1039. mcpc connect .vscode/mcp.json:apify @my-apify
  1040. mcpc @my-apify tools-list
  1041. ```
  1042. `mcpc` also finds these files for you: run `mcpc connect` with no arguments to auto-discover config
  1043. files in standard locations and connect every server, or pass a file without an entry to connect all
  1044. of its servers. See [Server formats](#server-formats).
  1045. **Example MCP config JSON file:**
  1046. ```json
  1047. {
  1048. "mcpServers": {
  1049. "apify": {
  1050. "url": "https://mcp.apify.com",
  1051. "headers": {
  1052. "Authorization": "Bearer ${APIFY_TOKEN}"
  1053. }
  1054. },
  1055. "filesystem": {
  1056. "command": "npx",
  1057. "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
  1058. "env": {
  1059. "DEBUG": "mcp:*"
  1060. }
  1061. },
  1062. "local-package": {
  1063. "command": "node",
  1064. "args": ["/path/to/server.js"]
  1065. }
  1066. }
  1067. }
  1068. ```
  1069. **Server configuration properties:**
  1070. For **Streamable HTTP servers:**
  1071. - `url` (required) - MCP server endpoint URL
  1072. - `headers` (optional) - HTTP headers to include with requests
  1073. - `timeout` (optional) - Request timeout in seconds
  1074. For **stdio servers:**
  1075. - `command` (required) - Command to execute (e.g., `node`, `npx`, `python`)
  1076. - `args` (optional) - Array of command arguments
  1077. - `env` (optional) - Environment variables for the process
  1078. > **Note:** Stdio servers inherit only a minimal env whitelist from the shell
  1079. > (`PATH`, `HOME`, `SHELL`, …). Other vars — `NODE_EXTRA_CA_CERTS`, `HTTPS_PROXY`,
  1080. > `SSL_CERT_FILE`, etc. — must be forwarded explicitly via the `env` block using
  1081. > `${VAR_NAME}`. Anything the server writes to stderr is captured to
  1082. > `~/.mcpc/logs/bridge-<session>.log` with a `[server stderr]` prefix, and the
  1083. > tail is appended to the error message if `mcpc connect` fails, so you can see
  1084. > why a stdio server failed to start.
  1085. **Environment variable substitution:**
  1086. Config files support environment variable substitution using `${VAR_NAME}` syntax:
  1087. ```json
  1088. {
  1089. "mcpServers": {
  1090. "secure-server": {
  1091. "url": "https://mcp.apify.com",
  1092. "headers": {
  1093. "Authorization": "Bearer ${APIFY_TOKEN}",
  1094. "X-User-ID": "${USER_ID}"
  1095. }
  1096. }
  1097. }
  1098. }
  1099. ```
  1100. ### Saved state
  1101. `mcpc` saves its state to `~/.mcpc/` directory (unless overridden by `MCPC_HOME_DIR`), in the following files:
  1102. - `~/.mcpc/sessions.json` - Active sessions with references to authentication profiles (file-locked for concurrent access)
  1103. - `~/.mcpc/profiles.json` - Authentication profiles (OAuth metadata, scopes, expiry)
  1104. - `~/.mcpc/wallets.json` - x402 wallet data (file permissions `0600`)
  1105. - `~/.mcpc/bridges/` - Unix domain socket files for each bridge process
  1106. - `~/.mcpc/logs/bridge-*.log` - Log files for each bridge process
  1107. - OS keychain - Sensitive credentials (OAuth tokens, bearer tokens, client secrets)
  1108. ### Environment variables
  1109. - `MCPC_HOME_DIR` - Directory for session and authentication profiles data (default is `~/.mcpc`)
  1110. - `MCPC_VERBOSE` - Enable verbose logging (set to `1`, `true`, or `yes`, case-insensitive)
  1111. - `MCPC_JSON` - Enable JSON output (set to `1`, `true`, or `yes`, case-insensitive)
  1112. - `HTTPS_PROXY` / `https_proxy` / `HTTP_PROXY` / `http_proxy` - Proxy URL for outbound connections (e.g. `http://proxy.example.com:8080`); `HTTPS_PROXY` takes precedence
  1113. - `NO_PROXY` / `no_proxy` - Comma-separated list of hostnames/IPs to bypass the proxy (e.g. `localhost,127.0.0.1`)
  1114. ### Cleanup
  1115. You can clean up the `mcpc` state and data using the `clean` command:
  1116. ```bash
  1117. # Safe non-destructive cleanup: remove expired sessions, delete old orphaned logs
  1118. mcpc clean
  1119. # Clean specific resources
  1120. mcpc clean sessions # Kill bridges, delete all sessions
  1121. mcpc clean profiles # Delete all authentication profiles
  1122. mcpc clean logs # Delete all log files
  1123. # Nuclear option: remove everything
  1124. mcpc clean all # Delete all sessions, profiles, logs, and sockets
  1125. ```
  1126. ## Security
  1127. `mcpc` follows [MCP security best practices](https://modelcontextprotocol.io/specification/latest/basic/security_best_practices).
  1128. MCP enables arbitrary tool execution and data access - treat servers like you treat shells:
  1129. - Use least-privilege tokens/headers
  1130. - Only use trusted servers!
  1131. - Audit tools before running them
  1132. ### Credential protection
  1133. | What | How |
  1134. | ---------------------- | ----------------------------------------------- |
  1135. | **OAuth tokens** | Stored in OS keychain (headless fallback: `credentials.json`, `0600`) |
  1136. | **HTTP headers** | Stored in OS keychain per-session |
  1137. | **Stdio server `env`** | Stored in OS keychain per-session |
  1138. | **Bridge credentials** | Passed via Unix socket IPC, kept in memory only |
  1139. | **Process arguments** | No secrets visible in `ps aux` |
  1140. | **x402 private key** | Stored in OS keychain (fallback: `wallets.json`, `0600`) |
  1141. | **Config files** | Contain only metadata, never tokens |
  1142. | **File permissions** | `0600` (user-only) for all config files |
  1143. ### Network security
  1144. - HTTPS enforced for remote servers (auto-upgraded from HTTP)
  1145. - OAuth callback binds to `127.0.0.1` only
  1146. - Credentials never logged, even in verbose mode
  1147. ### AI security
  1148. See [AI sandboxes](#ai-sandboxes) for details.
  1149. ## Errors
  1150. `mcpc` provides clear error messages for common issues:
  1151. - **Connection failures**: Displays transport-level errors with retry suggestions
  1152. - **Session timeouts**: Automatically attempts to reconnect or prompts for session recreation
  1153. - **Invalid commands**: Shows available commands and correct syntax
  1154. - **Tool execution errors**: Returns server error messages with context
  1155. - **Bridge crashes**: Detects and cleans up orphaned processes, offers restart
  1156. ### Exit codes
  1157. - `0` - Success
  1158. - `1` - Client error (invalid arguments, command not found, etc.)
  1159. - `2` - Server error (tool execution failed, resource not found, etc.)
  1160. - `3` - Network error (connection failed, timeout, etc.)
  1161. - `4` - Authentication error (invalid credentials, forbidden, etc.)
  1162. ### Verbose mode
  1163. To see what's happening, enable detailed logging with `--verbose`.
  1164. ```bash
  1165. mcpc --verbose @apify tools-list
  1166. ```
  1167. This causes `mcpc` to print detailed debug messages to stderr.
  1168. ### Logs
  1169. View the bridge log for a session with `mcpc @<session> logs` (run with
  1170. `--help` for `--follow`, `-n`, and `--since` options). The underlying file
  1171. lives at `~/.mcpc/logs/bridge-@<session>.log` and is rotated automatically
  1172. (10MB per file, max 5 files). The main `mcpc` process doesn't save log
  1173. files, but supports [verbose mode](#verbose-mode).
  1174. ### Troubleshooting
  1175. **"Cannot connect to bridge"**
  1176. - Bridge may have crashed. Try: `mcpc @<session-name> tools-list` to restart the bridge
  1177. - Check bridge is running: `ps aux | grep '[m]cpc/dist/bridge'`
  1178. - Check socket exists: `ls ~/.mcpc/bridges/`
  1179. **"Session not found"**
  1180. - List existing sessions: `mcpc`
  1181. - Create new session if expired: `mcpc @<session-name> close` and `mcpc connect <server> @<session-name>`
  1182. **"Authentication failed"**
  1183. - List saved OAuth profiles: `mcpc`
  1184. - Re-authenticate: `mcpc login <server> [--profile <name>]`
  1185. - For bearer tokens: provide `--header "Authorization: Bearer ${TOKEN}"` again
  1186. ## Development
  1187. The initial version of `mcpc` was developed and [launched by Jan Curn](https://x.com/jancurn/status/2007144080959291756) of [Apify](https://apify.com)
  1188. with the help of Claude Code, during late nights over Christmas 2025 in North Beach, San Francisco.
  1189. See [CONTRIBUTING](./CONTRIBUTING.md) for development setup, architecture overview, and contribution guidelines.
  1190. ## Related work
  1191. ### MCP CLI clients
  1192. <!-- Stars, contributors, commits, and activity as of 2026-11-05. -->
  1193. | Tool | MCP | Active | Lang | Stars | Commits | Contrib | Tools | Resources | Prompts | Tasks | Skills | Code mode | Sessions | OAuth | Client creds | Enterprise auth | Stdio | HTTP | Tool search | x402 | LLM |
  1194. | ------------------------------------------------------------------------------------------------------------------- | ---------- | ------ | ------ | ----: | ------: | ------: | ----- | --------- | ------- | ----- | ------ | --------- | -------- | ----- | ------------ | --------------- | ----- | ---- | ----------- | ---- | --- |
  1195. | **[apify/mcpc](https://github.com/apify/mcpc)** | 2026-07-28 | ✅ | TS | 1.1k | 823 | 22 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | — |
  1196. | [modelcontextprotocol/inspector (mcpdo)](https://github.com/modelcontextprotocol/inspector/tree/main/clients/mcpdo) | 2026-07-28 | ✅ | TS | 11.2k | 4815 | 140 | ✅ | ✅ | ✅ | ✅ | ✅ | — | ✅ | ✅ | — | ✅ | ✅ | ✅ | — | — | — |
  1197. | [openclaw/mcporter](https://github.com/openclaw/mcporter) | 2026-07-28 | ✅ | TS | 5.1k | 1021 | 62 | ✅ | ✅ | — | — | — | ✅ | ✅ | ✅ | — | — | ✅ | ✅ | — | — | — |
  1198. | [knowsuchagency/mcp2cli](https://github.com/knowsuchagency/mcp2cli) | 2025-11-25 | ✅ | Python | 2.4k | 195 | 26 | ✅ | ✅ | ✅ | — | — | ✅ | ✅ | ✅ | ✅ | — | ✅ | ✅ | ✅ | — | — |
  1199. | [IBM/mcp-cli](https://github.com/IBM/mcp-cli) | 2025-06-18 | ⚠️ | Python | 2.0k | 800 | 22 | ✅ | ✅ | ✅ | — | — | ✅ | ✅ | ✅ | — | — | ✅ | ✅ | — | — | ✅ |
  1200. | [f/mcptools](https://github.com/f/mcptools) | 2024-11-05 | ⚠️ | Go | 1.6k | 174 | 16 | ✅ | ✅ | ✅ | — | — | ✅ | — | — | — | — | ✅ | ✅ | — | — | — |
  1201. | [philschmid/mcp-cli](https://github.com/philschmid/mcp-cli) | 2025-11-25 | ⚠️ | TS | 1.3k | 30 | 2 | ✅ | — | — | — | — | ✅ | ✅ | — | — | — | ✅ | ✅ | ✅ | — | — |
  1202. | [adhikasp/mcp-client-cli](https://github.com/adhikasp/mcp-client-cli) | 2025-06-18 | ⚠️ | Python | 675 | 113 | 5 | ✅ | — | — | — | — | — | — | — | — | — | ✅ | — | — | — | ✅ |
  1203. | [thellimist/clihub](https://github.com/thellimist/clihub) | 2025-11-25 | ⚠️ | Go | 668 | 60 | 1 | ✅ | — | — | — | — | — | — | ✅ | ✅ | — | ✅ | ✅ | ✅ | — | — |
  1204. | [wong2/mcp-cli](https://github.com/wong2/mcp-cli) | 2025-11-25 | ⚠️ | JS | 447 | 67 | 7 | ✅ | ✅ | ✅ | — | — | — | — | ✅ | — | — | ✅ | ✅ | — | — | — |
  1205. | [activeing123/mcptoon](https://github.com/activeing123/mcptoon) | 2026-07-28 | ✅ | Python | 422 | 535 | 5 | ✅ | — | — | — | — | ✅ | — | — | — | — | ✅ | ✅ | — | — | — |
  1206. | [avelino/mcp](https://github.com/avelino/mcp) | 2026-07-28 | ✅ | Rust | 75 | 156 | 9 | ✅ | ✅ | ✅ | — | — | — | — | ✅ | — | — | ✅ | ✅ | — | — | — |
  1207. | [mcpshim/mcpshim](https://github.com/mcpshim/mcpshim) | 2025-11-25 | ✅ | Go | 66 | 17 | 1 | ✅ | — | — | — | — | ✅ | ✅ | ✅ | — | — | — | ✅ | ✅ | — | — |
  1208. | [lydakis/mcpx](https://github.com/lydakis/mcpx) | 2026-07-28 | ✅ | Go | 55 | 122 | 3 | ✅ | — | — | — | — | ✅ | ✅ | ✅ | — | — | ✅ | ✅ | — | — | — |
  1209. | [arcadeai-labs/mcpx](https://github.com/arcadeai-labs/mcpx) | 2026-07-28 | ✅ | TS | 37 | 124 | 3 | ✅ | ✅ | ✅ | ✅ | — | ✅ | — | ✅ | — | — | ✅ | ✅ | ✅ | — | — |
  1210. | [EstebanForge/mcp-cli-ent](https://github.com/EstebanForge/mcp-cli-ent) | 2026-07-28 | ✅ | Go | 15 | 66 | 2 | ✅ | — | — | — | — | ✅ | ✅ | — | — | — | ✅ | ✅ | ✅ | — | — |
  1211. | [mcp2cli/source-code](https://github.com/mcp2cli/source-code) | 2026-07-28 | ✅ | Rust | 12 | 93 | 3 | ✅ | ✅ | ✅ | ✅ | — | ✅ | ✅ | ✅ | — | — | ✅ | ✅ | — | — | — |
  1212. | [domdomegg/call-mcp](https://github.com/domdomegg/call-mcp) | 2025-11-25 | ✅ | TS | 4 | 55 | 3 | ✅ | — | — | — | — | ✅ | — | ✅ | — | — | ✅ | ✅ | — | — | — |
  1213. | [ConsulTent/mcpcli](https://github.com/ConsulTent/mcpcli) | 2026-07-28 | ✅ | Go | 0 | 95 | 3 | ✅ | ✅ | ✅ | — | — | — | — | ✅ | ✅ | — | ✅ | ✅ | — | — | — |
  1214. **Legend:** ✅ = supported, ⚠️ = stale (no commits in 3+ months), **MCP** = latest [MCP protocol version](https://modelcontextprotocol.io/specification/latest/basic/index#protocol-version) the client supports, per its pinned SDK/own implementation, **Commits** = total commits, **Contrib** = contributors, **Tasks** = [async tasks](https://modelcontextprotocol.io/specification/latest/basic/utilities/tasks), **Skills** = [skills extension](https://modelcontextprotocol.io/extensions/skills/overview), **Client creds** = [OAuth client credentials](https://modelcontextprotocol.io/extensions/auth/oauth-client-credentials) extension (machine-to-machine login, no browser), **Enterprise auth** = [enterprise-managed authorization](https://modelcontextprotocol.io/extensions/auth/enterprise-managed-authorization) extension (ID-JAG issued by a corporate IdP), **x402** = [x402 payment protocol](https://www.x402.org/) support, **LLM** = requires/uses an LLM.
  1215. **Notes:**
  1216. - [thellimist/clihub](https://github.com/thellimist/clihub) is a code generator that compiles MCP tools into standalone CLI binaries, rather than a runtime client ([HN discussion](https://news.ycombinator.com/item?id=47157398)).
  1217. - [knowsuchagency/mcp2cli](https://github.com/knowsuchagency/mcp2cli) also talks to OpenAPI and GraphQL APIs directly, and can encode output as [TOON](https://github.com/toon-format/toon) to save tokens.
  1218. - [mcp2cli/source-code](https://github.com/mcp2cli/source-code) is a Rust tool that turns each MCP server into its own named CLI app (`email send ...`), with typed flags generated from the tools' JSON Schema; unrelated to [knowsuchagency/mcp2cli](https://github.com/knowsuchagency/mcp2cli).
  1219. - [activeing123/mcptoon](https://github.com/activeing123/mcptoon) is tools-only and focuses on token efficiency: tool listings, schemas, and results are encoded as [TOON](https://github.com/toon-format/toon) or its own compact formats instead of JSON.
  1220. - [IBM/mcp-cli](https://github.com/IBM/mcp-cli) and [mcp-client-cli](https://github.com/adhikasp/mcp-client-cli) integrate an LLM (Ollama, OpenAI, etc.) for chat-style interaction, while the other tools are pure CLI clients.
  1221. - [domdomegg/call-mcp](https://github.com/domdomegg/call-mcp) can also call connectors configured in claude.ai by reusing the Claude Code OAuth token, with no separate login.
  1222. - [avelino/mcp](https://github.com/avelino/mcp) is a Rust CLI that turns configured MCP servers into terminal commands (`mcp <server> <tool>`), with a server registry and a proxy mode; it holds no persistent sessions.
  1223. - [ConsulTent/mcpcli](https://github.com/ConsulTent/mcpcli) is a Go client and inspector (`mcp`) with a REPL and a protocol-version compatibility probe.
  1224. - [lydakis/mcpx](https://github.com/lydakis/mcpx) is a Unix-composable client (`mcpx <server> <tool>`), not [arcadeai-labs/mcpx](https://github.com/arcadeai-labs/mcpx).
  1225. - [f/mcptools](https://github.com/f/mcptools) depends on a Go MCP library capable of `2025-03-26`, but its own client code hardcodes `2024-11-05` (its README notes HTTP/SSE support is limited to that version).
  1226. - MCP versions for [knowsuchagency/mcp2cli](https://github.com/knowsuchagency/mcp2cli) and [adhikasp/mcp-client-cli](https://github.com/adhikasp/mcp-client-cli) reflect their locked/tested SDK version; both allow a looser dependency range that could resolve to a newer SDK on a fresh install.
  1227. ### Code mode and dynamic tool discovery
  1228. These resources describe the "code mode" pattern (replacing many tool definitions with `search` + `execute`) and dynamic tool discovery:
  1229. - [Code mode](https://www.anthropic.com/engineering/code-execution-with-mcp) - Anthropic's blog post on code execution with MCP
  1230. - [Code mode at Cloudflare](https://blog.cloudflare.com/code-mode/) - Cloudflare's implementation of the code mode pattern
  1231. - [Advanced tool use](https://www.anthropic.com/engineering/advanced-tool-use) - Anthropic's engineering post on tool search
  1232. - [Claude tool search](https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-search-tool) - Claude platform docs
  1233. - [Dynamic context discovery](https://cursor.com/blog/dynamic-context-discovery) - Cursor's approach to dynamic tool discovery
  1234. - [cmcp](https://github.com/assimelha/cmcp) (~32 stars, Rust) - MCP proxy aggregating servers behind `search()` + `execute()`
  1235. - [cloudflare-mcp](https://github.com/mattzcarey/cloudflare-mcp) (~128 stars, TS) - MCP server for the Cloudflare API using code mode
  1236. - [infinite-mcp](https://github.com/day50-dev/infinite-mcp) (~6 stars, Python) - Meta-MCP server that exposes 1000+ pre-indexed MCP servers via semantic search and dynamic tool discovery
  1237. ### Other
  1238. - [mcpGraph](https://github.com/TeamSparkAI/mcpGraph) - MCP server that orchestrates directed graphs of MCP tool calls
  1239. ## License
  1240. Apache-2.0 - see [LICENSE](./LICENSE) for details.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.