mcpc: a shell client for MCP, and what it assumes about your agent

The problem mcpc is aimed at: agents that treat MCP as prompt-time function calls

The README states the motivation directly. Many agents, in its words, treat tools as prompt-time function calls, repeatedly injecting tool definitions and results into the context. Tokens get wasted, context rots, and the agent gets slower. The popular conclusion from that experience is that MCP is worse than plain CLIs. mcpc is a response to that conclusion rather than an agreement with it.

The audience is therefore narrow and specific. First, engineers who want to inspect and debug an MCP server by hand without writing a client. Second, people who want repeatable MCP workflows expressed as shell scripts. Third, agent authors who want to expose the whole MCP protocol through one Bash() tool call instead of registering dozens of MCP functions. The README's own diagram shows the shape: agent to mcpc over Bash(), mcpc to MCP server over MCP, with sessions, OAuth, tools, resources, prompts, tasks and x402 handled in between.

A side benefit the README claims is that the same configuration, OAuth profiles and live sessions can be shared across many agents on one machine. Authenticate once, reuse everywhere. That is a real architectural choice: credentials and sessions live in mcpc's own state, not inside each agent process.

Persistent sessions are the mechanism, not a convenience

The central design decision is that connections outlive a single command. mcpc connect starts a named session and keeps it alive; later invocations address it by name, as in mcpc @test tools-list. The README says sessions can be kept alive in parallel across multiple servers, and that this works whether the server protocol is stateful or stateless.

That matters because MCP servers vary in how much they remember. A stateless server can be reconnected per call with little cost. A stateful one cannot, and a CLI that spawns a fresh process per invocation would lose whatever the server had accumulated. Keeping the session in a background process is the only way a shell command can behave like a long-lived client.

The cost is state you now have to manage. There is a close command, a restart command that the help text explicitly says loses all state, and a clean command that removes sessions, profiles, logs or all of them. A stale session is a failure mode you inherit: if the session process died, the next command against @name has nothing to talk to. The README does not describe automatic reconnection behaviour, so treat recovery as manual until you confirm otherwise.

Progressive tool discovery is the other half of the token argument. Instead of loading every tool definition up front, mcpc offers grep, which the help text describes as searching tools and instructions across all active sessions. An agent can search first and fetch definitions only for what it needs.

Getting it running: install paths, connect syntax, and the config file form

Installation is either Homebrew, which the README notes brings its own Node.js, or a global npm or Bun install:

brew install apify/tap/mcpc npm install -g @apify/mcpc bun install -g @apify/mcpc

The quickstart sequence shows the intended loop. mcpc with no arguments lists active sessions and saved authentication profiles. mcpc login mcp.apify.com performs an OAuth login and saves credentials for reuse. mcpc connect mcp.apify.com @test opens a named session. Bare mcpc @test prints server info and capabilities. mcpc @test tools-list lists tools, and mcpc @test tools-call search-actors keywords:="website crawler" calls one. Note the := syntax for named arguments; that is the form the README uses.

For a local stdio server, the server reference can point into an existing config file: mcpc connect ./.vscode/mcp.json:filesystem @fs. That means you can reuse a VS Code MCP configuration rather than maintaining a second one, which is a small but genuinely useful detail for teams that already have those files checked in.

Global options worth knowing: --json for machine-readable output, --verbose for debug logging, --profile to select an OAuth profile (default is named "default"), --timeout in seconds with a default of 60, --max-chars to truncate output, and --insecure to skip TLS verification for self-signed certificates. The README notes --max-chars is ignored in --json mode, which is the right call: truncating JSON would produce invalid documents.

Where credentials live, and why headless Linux changes the threat model

The README says mcpc uses the OS keychain for credential storage. On Linux that means the Secret Service API, and GNOME or KDE desktops work out of the box. On headless or CI systems there is a fallback: a file-based store at ~/.mcpc/credentials.json with mode 0600.

This is the sharpest trade-off in the project and the README is honest about it. A file with mode 0600 is protected by filesystem permissions and nothing else. Anything running as the same user can read it. On a CI runner that is often acceptable because the machine is ephemeral and single-tenant. On a shared build host it is not. The README gives a way to force the keychain instead, involving libsecret and gnome-keyring installed via apt-get, dnf or pacman, then running under dbus-run-session with gnome-keyring-daemon --unlock. That is a real workaround with real setup cost, and it is the kind of thing that breaks quietly when a container image changes.

The proxy feature addresses a different credential problem. The README describes proxying MCP server connections to protect credentials from AI-generated code. The reasoning is sound: if an agent's generated shell commands talk to mcpc rather than directly to a server, the agent never handles the token. That is a meaningful boundary, though it only holds if the agent cannot read the underlying credential store or bypass the proxy by other means.

JSON output, jq pipelines, and what code mode actually implies

The README frames code mode as JSON output that composes with jq, xargs and shell pipelines, so MCP workflows become shell scripts. The --json flag is the switch. This is the least glamorous feature and probably the most durable one, because it does not depend on any agent framework or protocol version.

The implication is that mcpc expects you to treat MCP results as data in a pipeline rather than as text to read. That works well for listing and filtering. It works less well for anything requiring structured reasoning about a result, where you are back to writing logic in shell or handing the JSON to something else.

There is also a token argument buried here. If an agent calls mcpc --json and pipes through jq, the agent sees only the filtered output, not the full server response. Combined with grep for discovery, this is the concrete mechanism behind the claim that mcpc saves context. Whether it saves more than it costs depends on how much shell the agent has to write to get what it wants, which the README does not quantify and neither can I.

Transports, protocol coverage, and the limits the README sets

The feature list names tools, prompts, resources, async tasks, skills, notifications and logging, over stdio and Streamable HTTP. Those are the two transports. If your server only speaks something else, mcpc is not the client for you, and the README does not suggest a plugin path for adding transports.

Async tasks are worth calling out because they change the interaction shape. A tool call that returns a task identifier rather than a result requires polling or resumption, and a CLI has to model that somehow. The README lists tasks as supported but does not, in the material available, describe the command surface for them. That is a gap: you will need to read the generated help output to learn the actual subcommands.

The x402 payment support is labelled experimental in both the feature list and the command list, and it is scoped to the Base network. Experimental means exactly that. Do not build a payment flow on it without reading the current source, and consider whether an experimental payments path belongs in the same binary you use for routine debugging. There is an x402 subcommand for configuring a wallet, which implies key material is involved; the README does not detail how that wallet is stored, and that is the first thing I would check before using it with real funds.

The alternative: an in-process MCP client library

The obvious alternative is the official MCP SDKs, which give you a typed client you import into your own program. The difference in approach is not cosmetic. With an SDK, the connection lives inside your process, you control its lifetime, you handle errors as exceptions or typed results, and you never serialize anything to a subprocess boundary. With mcpc, every interaction crosses a process boundary and comes back as text or JSON, and session lifetime is managed by a separate daemon-like process that you start with connect and end with close.

That boundary is the whole point for the agent use case, and it is pure overhead for the application use case. If you are writing a service that talks to one MCP server on a fixed schedule, an SDK is less machinery. If you are writing an agent that already has shell access and you want it to reach arbitrary servers without a code change per server, mcpc is the smaller integration.

There is a middle option worth naming: for pure inspection, the MCP Inspector is the tool most people reach for, and it is interactive rather than scriptable. mcpc's advantage over it is that commands compose in pipelines and can be committed to a repository as scripts. Its disadvantage is that you get no GUI, so browsing a large tool catalogue means reading text.

Maintenance cost, licence, and what to check before depending on it

The project is Apache-2.0, which permits commercial use and modification and includes an explicit patent grant. That is a permissive licence with fewer obligations than a copyleft one; it is not legal advice, and if you redistribute a modified mcpc you should read the NOTICE and attribution requirements in the licence text yourself.

On maintenance, the material shows releases at v0.5.0, v0.5.1 and v0.6.0 within roughly a month, and a last push date of 2026-09-10. The version number is still 0.x, which conventionally signals that the command surface can change without a major-version bump. For a tool you invoke from scripts and agent prompts, that is the main upgrade risk: a renamed subcommand or a changed flag breaks callers silently. Pinning the npm version and reading release notes before upgrading is the concrete mitigation.

The dependency footprint is described as minimal, which matters if you install globally and then call it from an agent sandbox. The README also states mcpc does not use LLMs on its own, so there is no hidden inference cost or outbound model call in the tool itself.

Before adopting, verify three things against your own environment. Whether your Linux hosts have a working Secret Service, because the file fallback is weaker. Whether the specific MCP server you care about speaks stdio or Streamable HTTP. And whether the OAuth flow you need is covered, since the README names OAuth 2.1 with CIMD and DCR but does not enumerate which providers have been tested. Run mcpc help and the per-command help first; the README says the CLI is designed to be picked up from --help alone, so that is the intended way to learn the current surface.

Editorial conclusion

Adopt mcpc if you debug MCP servers by hand, script MCP workflows in shell, or give an agent a single Bash tool instead of injecting tool definitions into context. Do not adopt it if you need an in-process typed MCP client, or if you cannot tolerate an experimental payments path in your dependency tree. Verify two things first: that your platform has a working Secret Service or gnome-keyring setup, since headless Linux falls back to ~/.mcpc/credentials.json in plain file storage, and that your target server works over stdio or Streamable HTTP, because those are the transports the README lists.

Official sources

1. apify/mcpc on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases