@apify/mcpc 0.2.4 → 0.3.0-beta.0

package/README.md

@@ -1,30 +1,38 @@
-# `mcpc`: Universal MCP command-line client
+# mcpc — a universal MCP CLI client
 
-`mcpc` is a CLI for the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/)
-that maps MCP operations to intuitive commands for interactive shell use, scripts, and AI coding agents.
+![mcpc logo](https://apify.github.io/mcpc/client-logo.svg?v=2)
 
-`mcpc` is a Swiss Army knife for MCP. It is useful for inspecting servers, scripting,
-and enabling AI coding agents to use MCP ["code mode"](#ai-agents) in shell.
-After all, UNIX-compatible shell script is THE most universal coding language.
+[![npm version](https://img.shields.io/npm/v/@apify/mcpc.svg)](https://www.npmjs.com/package/@apify/mcpc)
+[![npm downloads](https://img.shields.io/npm/dm/@apify/mcpc.svg)](https://www.npmjs.com/package/@apify/mcpc)
+[![CI](https://github.com/apify/mcpc/actions/workflows/ci.yml/badge.svg)](https://github.com/apify/mcpc/actions/workflows/ci.yml)
+[![License](https://img.shields.io/npm/l/@apify/mcpc.svg)](https://github.com/apify/mcpc/blob/main/LICENSE)
 
-![mcpc screenshot](https://raw.githubusercontent.com/apify/mcpc/main/docs/images/mcpc-demo.gif)
+`mcpc` is a command-line client for the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/)
+that maps MCP operations to intuitive commands for interactive shell use, scripting, and AI agents.
+
+`mcpc` is your new Swiss Army knife for MCP. It's great for manual inspection and debugging of MCP servers,
+as well as for agents to leverage all modern MCP capabilities through the most universal
+coding interface: the UNIX shell.
 
 **Key features:**
 
-- 🌎 **Compatible** - Works with any MCP server over Streamable HTTP or stdio.
-- 🔄 **Persistent sessions** - Keep multiple server connections alive simultaneously.
-- 🔧 **Strong MCP support** - Instructions, tools, resources, prompts, async tasks, dynamic discovery.
-- 🔌 **Code mode** - JSON output enables integration with CLI tools like `jq` and scripting.
-- 🤖 **AI sandboxing** - MCP proxy server to securely access authenticated sessions from AI-generated code.
-- 🔒 **Secure** - Full OAuth 2.1 support, OS keychain for credentials storage.
+- 🔧 **Full MCP support** - HTTP/stdio transports, instructions, tools, async tasks, resources, prompts, ...
+- 🔄 **Persistent sessions** - Keep multiple stateful connections alive simultaneously.
+- 🗺️ **Progressive tool discovery** - Find relevant MCP tools on the fly to save tokens and increase accuracy.
+- 🔌 **Code mode** - JSON output composes with `jq`, `xargs`, and shell pipelines for MCP workflows as shell scripts.
+- 🔒 **Secure** - Full OAuth 2.1 support with CMID and DCR, uses OS keychain for credentials storage.
+- 🤖 **AI sandboxing** - Proxy MCP server connections to protect credentials from AI-generated code.
 - 🪶 **Lightweight** - Minimal dependencies, works on Mac/Win/Linux, doesn't use LLMs on its own.
-- 💸 **[Agentic payments (x402)](#agentic-payments-x402)** - Experimental support for the [x402](https://www.x402.org/) payment protocol, enabling AI agents to pay for MCP tool calls with USDC on [Base](https://www.base.org/).
+- 💸 **Agentic payments** - Experimental support for the [x402](https://www.x402.org/) protocol on [Base](https://www.base.org/).
+
+![mcpc screenshot](https://raw.githubusercontent.com/apify/mcpc/main/docs/images/mcpc-demo.gif)
 
 ## Table of contents
 
 <!-- START doctoc generated TOC please keep comment here to allow auto update -->
 <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
 
+- [Motivation](#motivation)
 - [Install](#install)
 - [Quickstart](#quickstart)
 - [Usage](#usage)
@@ -43,6 +51,33 @@ After all, UNIX-compatible shell script is THE most universal coding language.
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
 
+## Motivation
+
+Many AI agents misuse MCP. They treat tools as prompt-time function calls, repeatedly injecting
+tool definitions and results into the context. Tokens get wasted, context rots, the
+agent gets slower and less reliable, and popular conclusion that: _"MCP sucks, CLIs are better"_.
+
+`mcpc` challenges that narrative. It maps every MCP operation to an intuitive CLI command that
+agents pick up from `--help` alone. Any agent with shell access gets full MCP support without
+wiring up dozens of MCP functions. Just one `Bash()` tool, and `mcpc` handles the rest:
+
+```
+
+  ┌──────────┐         Bash()         ┌──────────┐           MCP          ┌────────────┐
+  │ AI agent │  ────────────────────► │   mcpc   │  ────────────────────► │ MCP server │
+  └──────────┘                        └──────────┘    Sessions, OAuth,    └────────────┘
+                                                      Tools, Resources,
+                                                      Prompts, Tasks,
+                                                      x402, ...
+```
+
+CLI is the perfect _local_ interface between agents and MCP, while MCP remains the
+standard _remote_ interface for server discovery, authentication, payments, and access control.
+The two aren't exclusive – they're complementary.
+
+As a bonus, the same `mcpc` configuration, OAuth profiles, and live sessions can be shared across
+many AI agents on the same machine. Authenticate once, reuse everywhere.
+
 ## Install
 
 ```bash
@@ -52,28 +87,14 @@ npm install -g @apify/mcpc
 bun install -g @apify/mcpc
 ```
 
-**Linux users:** `mcpc` uses the OS keychain for secure credential storage via the
-[Secret Service API](https://specifications.freedesktop.org/secret-service/).
-On desktop systems (GNOME, KDE) this works out of the box. On headless/server/CI environments
-without a keyring daemon, `mcpc` automatically falls back to a file-based credential store
-(`~/.mcpc/credentials`, mode `0600`).
+**Linux:** credentials use the OS keychain via the [Secret Service API](https://specifications.freedesktop.org/secret-service/).
+GNOME/KDE desktops work out of the box. On headless/CI systems, `mcpc` falls back to a
+file-based store (`~/.mcpc/credentials`, mode `0600`).
 
-To use the OS keychain on a headless system, install `libsecret` and a secret service daemon:
+To force the keychain on headless systems, install `libsecret` + `gnome-keyring`
+(via `apt-get`, `dnf`, or `pacman`) and run:
 
 ```bash
-# Debian/Ubuntu
-sudo apt-get install libsecret-1-0 gnome-keyring
-
-# Fedora/RHEL/CentOS
-sudo dnf install libsecret gnome-keyring
-
-# Arch Linux
-sudo pacman -S libsecret gnome-keyring
-```
-
-And then run `mcpc` as follows:
-
-```
 dbus-run-session -- bash -c "echo -n 'password' | gnome-keyring-daemon --unlock && mcpc ..."
 ```
 
@@ -106,6 +127,54 @@ mcpc @fs tools-list
 <!-- AUTO-GENERATED: mcpc --help -->
 
 ```
+Usage: mcpc [<@session>] [<command>] [options]
+
+Universal command-line client for the Model Context Protocol (MCP).
+
+Commands:
+  connect <server> [@session]  Connect to an MCP server and start a new named @session
+  close <@session>             Close a session
+  restart <@session>           Restart a session (losing all state)
+  shell <@session>             Open interactive shell for a session
+  login <server>               Interactively login to a server using OAuth and save profile
+  logout <server>              Delete an OAuth profile for a server
+  clean [resources...]         Clean up mcpc data (sessions, profiles, logs, all)
+  grep <pattern>               Search tools and instructions across all active sessions
+  x402 [subcommand] [args...]  Configure an x402 payment wallet (EXPERIMENTAL)
+  help [command] [subcommand]  Show help for a specific command
+
+Options:
+  --json                       Output in JSON format for scripting
+  --verbose                    Enable debug logging
+  --profile <name>             OAuth profile for the server ("default" if not provided)
+  --timeout <seconds>          Request timeout in seconds (default: 300)
+  --max-chars <n>              Truncate output to n characters (ignored in --json mode)
+  --insecure                   Skip TLS certificate verification (for self-signed certs)
+  -v, --version                Output the version number
+  -h, --help                   Display help
+
+MCP session commands (after connecting):
+  <@session>                   Show MCP server info, capabilities, and tools overview
+  <@session> grep <pattern>    Search tools and instructions
+  <@session> tools-list        List all server tools
+  <@session> tools-get <name>  Get tool details and schema
+  <@session> tools-call <name> [arg:=val ... | <json> | <stdin]
+  <@session> prompts-list
+  <@session> prompts-get <name> [arg:=val ... | <json> | <stdin]
+  <@session> resources-list
+  <@session> resources-read <uri>
+  <@session> resources-subscribe <uri>
+  <@session> resources-unsubscribe <uri>
+  <@session> resources-templates-list
+  <@session> tasks-list
+  <@session> tasks-get <taskId>
+  <@session> tasks-result <taskId>
+  <@session> tasks-cancel <taskId>
+  <@session> logging-set-level <level>
+  <@session> ping
+
+Run "mcpc" without arguments to show active sessions and OAuth profiles.
+Run "mcpc --json" to get the same data as `{ sessions: [...], profiles: [...] }`.
 ```
 
 ### General actions
@@ -170,44 +239,15 @@ echo '{"greeting":"hello","count":10}' | mcpc @session tools-call <tool-name>
 cat args.json | mcpc @session tools-call <tool-name>
 ```
 
-**Rules:**
-
-- All arguments use `:=` syntax: `key:=value`
-- Values are auto-parsed: valid JSON becomes that type, otherwise treated as string
-  - `count:=10` → number `10`
-  - `enabled:=true` → boolean `true`
-  - `greeting:=hello` → string `"hello"` (not valid JSON, so string)
-  - `id:='"123"'` → string `"123"` (JSON string literal)
-- Inline JSON: If first argument starts with `{` or `[`, it's parsed as a JSON object/array
-- Stdin: When no positional args are provided and input is piped, reads JSON from stdin
-
-**Using shell variables:**
-
-When using shell variables that may contain spaces, use double quotes around the entire argument:
-
-```bash
-# Variable with spaces - use double quotes
-QUERY="hello world"
-mcpc @server tools-call search "query:=${QUERY}"
-
-# Multiple variables
-CITY="New York"
-TYPE="restaurants"
-mcpc @server tools-call search "query:=${CITY} ${TYPE}"
-
-# For complex inputs, consider using JSON via stdin
-echo "{\"query\": \"${QUERY}\", \"limit\": 10}" | mcpc @server tools-call search
-```
-
-**Common pitfall:** Don't put spaces around `:=` - it won't work:
+**Auto-parsing rules** for `key:=value`: valid JSON keeps its type
+(`count:=10` → number, `enabled:=true` → boolean, `cfg:='{"k":"v"}'` → object); anything
+else is a string (`greeting:=hello` → `"hello"`). Force a string literal with JSON quotes:
+`id:='"123"'`. Inline JSON is detected when the first arg starts with `{` or `[`. Stdin is
+read when no positional args are given and input is piped.
 
-```bash
-# Wrong - spaces around :=
-mcpc @server tools-call search query := "hello world"
-
-# Correct - no spaces around :=
-mcpc @server tools-call search "query:=hello world"
-```
+**Pitfalls:** no spaces around `:=` (use `query:=hello world`, not `query := ...`); quote
+the whole argument when it contains shell expansions (`"query:=${VAR}"`). For complex
+inputs, prefer piping JSON via stdin.
 
 ### Interactive shell
 
@@ -251,7 +291,7 @@ By default, `grep` searches only tools. Use `--resources` or `--prompts` to sear
 (combine with `--tools` to include tools too). Sessions that are crashed or unavailable are shown
 with their status rather than silently skipped.
 
-The `grep` command is useful for **dynamic tool discovery**, 
+The `grep` command is useful for **dynamic tool discovery**,
 also called [Tool search tool](https://www.anthropic.com/engineering/advanced-tool-use) by Anthropic
 or [Dynamic context discovery](https://cursor.com/blog/dynamic-context-discovery) by Cursor.
 Rather than loading all tools into AI agent's context, the agent can use `grep` to discover the right tool
@@ -303,59 +343,25 @@ mcpc @apify close      # or: mcpc close @apify
 
 ### Session lifecycle
 
-The sessions are persistent: metadata is saved in `~/.mcpc/sessions.json` file,
-[authentication tokens](#authentication) in OS keychain.
-The `mcpc` bridge process keeps the session alive by sending periodic [ping messages](#ping) to the MCP server.
-Still, sessions can fail due to network disconnects, bridge process crash, or server dropping it.
+Session metadata is saved in `~/.mcpc/sessions.json`, [authentication tokens](#authentication)
+in the OS keychain. The bridge process keeps the session alive with periodic [pings](#ping)
+and auto-reconnects on network failures or its own crashes (10s cooldown on failed retries).
 
 **Session states:**
 
-| State                 | Meaning                                                                                            |
-| --------------------- | -------------------------------------------------------------------------------------------------- |
-| 🟢**`live`**          | Bridge process running and server responding                                                       |
-| 🟡**`connecting`**   | Initial bridge startup in progress (`mcpc connect`)                                                |
-| 🟡**`reconnecting`** | Bridge crashed or lost auth; auto-reconnecting in the background                                   |
-| 🟡**`disconnected`** | Bridge process running but server unreachable; auto-recovers when server responds                  |
-| 🟡**`crashed`**      | Bridge process crashed or was killed; auto-reconnects in the background                            |
-| 🔴**`unauthorized`** | Server rejected authentication (401/403) or token refresh failed; auto-reconnects or needs `login` |
-| 🔴**`expired`**      | Server rejected session ID (404); requires `restart`                                               |
-
-Here's how `mcpc` handles various bridge process and server connection states:
-
-- While the **bridge process is running**:
-  - If **server positively responds** to pings, the session is marked 🟢 **`live`**, and everything is fine.
-  - If **server stops responding**, the session is marked 🟡 **`disconnected`**.
-    The bridge will keep trying to reconnect in the background and will return to 🟢 **`live`** once the server responds again.
-  - If **server rejects authentication** (HTTP 401 or 403) or token refresh fails,
-    the session is marked 🔴 **`unauthorized`**.
-    `mcpc` will auto-reconnect in the background if another session sharing the same OAuth profile has refreshed the tokens.
-    Otherwise, re-authenticate with `mcpc login <server>` and then `mcpc @my-session restart`.
-  - If **server rejects the session ID** (HTTP 404), indicating the MCP session is no longer valid,
-    the session is marked 🔴 **`expired`**.
-    You need to restart the session with `mcpc @my-session restart` to establish a new connection.
-- If the **bridge process crashes**, `mcpc` will mark the session as 🟡 **`crashed`**
-  and auto-reconnect the bridge in the background. You can also trigger reconnection manually
-  by running any `mcpc @my-session ...` command.
-  - If reconnection **succeeds** and the server resumes the MCP session, the session returns to 🟢 **`live`**.
-  - If the server issues a **new session ID** instead of resuming, the session is marked 🔴 **`expired`**.
-  - If reconnection **fails**, the session remains 🟡 **`crashed`** and retries after a 10-second cooldown.
-
-Note that `mcpc` never automatically removes sessions from the list.
-Instead, it keeps them flagged as 🟡 **`crashed`**, 🔴 **`unauthorized`**, or 🔴 **`expired`**,
-and any future attempts to use them will show the appropriate error with recovery instructions.
-
-To **remove the session from the list**, you need to explicitly close it:
+| State             | Meaning                                                                                         |
+| ----------------- | ----------------------------------------------------------------------------------------------- |
+| 🟢 `live`         | Bridge process running and server responding                                                    |
+| 🟡 `connecting`   | Initial bridge startup in progress (`mcpc connect`)                                             |
+| 🟡 `reconnecting` | Bridge crashed or lost auth; auto-reconnecting in the background                                |
+| 🟡 `disconnected` | Bridge process running but server unreachable; auto-recovers when server responds               |
+| 🟡 `crashed`      | Bridge process crashed or was killed; auto-reconnects in the background                         |
+| 🔴 `unauthorized` | Server rejected authentication (401/403) or token refresh failed; re-run `login` then `restart` |
+| 🔴 `expired`      | Server rejected session ID (404); requires `restart`                                            |
 
-```bash
-mcpc @apify close    # or: mcpc close @apify
-```
-
-You can restart a session anytime, which kills the bridge process
-and opens new connection with new `MCP-Session-Id`, by running:
-
-```bash
-mcpc @apify restart  # or: mcpc restart @apify
-```
+`mcpc` never removes sessions automatically — failed ones stay flagged with a recovery hint
+in the error message. Use `mcpc @apify restart` to kill the bridge and open a fresh
+`MCP-Session-Id`, or `mcpc @apify close` to remove the session entirely.
 
 ## Authentication
 
@@ -388,9 +394,12 @@ mcpc @apify tools-list
 
 ### OAuth profiles
 
-For OAuth-enabled remote MCP servers, `mcpc` implements the full OAuth 2.1 flow with PKCE,
-including `WWW-Authenticate` header discovery, server metadata discovery, client ID metadata documents,
-dynamic client registration, and automatic token refresh.
+For OAuth-enabled remote MCP servers, `mcpc` implements the full OAuth 2.1 flow with PKCE as
+mandated by the [MCP authorization spec](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization):
+`WWW-Authenticate` 401 challenges, Protected Resource Metadata and authorization server metadata
+discovery, all three [client registration approaches](#client-registration-approaches),
+[resource indicators (RFC 8707)](https://www.rfc-editor.org/rfc/rfc8707), and automatic
+refresh-token rotation.
 
 The OAuth authentication **always** needs to be initiated by the user calling the `login` command,
 which opens a web browser with login screen. `mcpc` never opens the web browser on its own.
@@ -433,83 +442,72 @@ mcpc logout mcp.apify.com
 mcpc logout mcp.apify.com --profile work
 ```
 
-### Authentication precedence
-
-When multiple authentication methods are available, `mcpc` uses this precedence order:
-
-1. **Command-line `--header` flag** (highest priority) - Always used if provided
-2. **Saved authentication profiles** - OAuth tokens from saved profile
-3. **Config file headers** - Headers from `--config` file for the server
-4. **No authentication** - Attempts unauthenticated connection
-
-**Note:** `--profile` and `--header "Authorization: ..."` cannot be combined — they are mutually
-exclusive. Providing both will result in a clear error. Use one or the other.
+### Client registration approaches
 
-`mcpc` automatically handles authentication based on what you specify:
+When logging in, `mcpc` supports all three OAuth client registration approaches defined in the
+[MCP authorization spec](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization#client-registration-approaches),
+picking the one the authorization server advertises in its OAuth metadata:
 
-**When `--header "Authorization: ..."` is provided:**
+| **Approach**                            | **`mcpc login` flags**                              |
+| :-------------------------------------- | :-------------------------------------------------- |
+| **Pre-registration**                    | `--client-id` (and optional `--client-secret`)      |
+| **Client ID Metadata Documents (CIMD)** | default (or `--client-metadata-url <url>`)          |
+| **Dynamic Client Registration (DCR)**   | fallback (or force with `--no-client-metadata-url`) |
 
-- The explicit header is always used, and OAuth profile auto-detection is skipped entirely
-- This works even if a `default` profile exists for the server
-- Cannot be combined with `--profile` (returns an error)
+`mcpc` ships with a hosted [Client ID Metadata Document](https://apify.github.io/mcpc/client-metadata.json)
+so every installation presents the same client identity to CIMD-capable authorization servers.
+When the authorization server advertises `client_id_metadata_document_supported: true`, the CIMD
+URL is used as the `client_id`; otherwise mcpc falls back to Dynamic Client Registration.
 
-**When `--profile <name>` is specified:**
-
-1. **Profile exists for the server**: Use its stored credentials
-   - If authentication succeeds → Continue with command/session
-   - If authentication fails (expired/invalid) → Fail with an error
-2. **Profile doesn't exist**: Fail with an error
-
-**When `--x402` is specified (without `--profile`):**
-
-- OAuth profile auto-detection is skipped, since x402 serves as the payment/auth mechanism
-- If you also pass `--profile`, the specified profile is still used alongside x402
+```bash
+# Default: mcpc's hosted CIMD is used automatically (no flags needed).
+mcpc login mcp.apify.com
 
-**When `--no-profile` is specified:**
+# Pre-registered OAuth client (public or confidential) — skips CIMD.
+mcpc login mcp.example.com --client-id <id> [--client-secret <secret>]
 
-- Skip all OAuth profile detection and connect anonymously
-- Useful when a `default` profile exists but you want an unauthenticated session
-- Can be combined with `--header "Authorization: ..."` for explicit bearer token without profile
+# Custom CIMD: override the default with your own hosted document.
+mcpc login mcp.example.com --client-metadata-url https://example.com/my-client.json
 
-**When no flags are specified (default):**
+# Disable CIMD: force Dynamic Client Registration even if the server supports CIMD.
+mcpc login mcp.example.com --no-client-metadata-url
+```
 
-1. **`default` profile exists for the server**: Use its stored credentials
-   - If authentication succeeds → Continue with command/session
-   - If authentication fails (expired/invalid) → Fail with an error
-2. **`default` profile doesn't exist**: Attempt unauthenticated connection
-   - If server accepts (no auth required) → Continue without creating profile
-   - If server rejects with 401 + `WWW-Authenticate` → Fail with an error
+See the [MCP authorization spec](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization#client-registration-approaches)
+for details on each approach and the format of Client ID Metadata Documents.
 
-On failure, the error message includes instructions on how to login and save the profile, so you know what to do.
+### Authentication precedence
 
-This flow ensures:
+When connecting, `mcpc` picks one auth source based on the flags you pass — explicit flags
+always win over stored profiles, and credentials are never silently downgraded. If a profile
+is missing, expired, or invalid, `mcpc` fails with an error that includes the right
+`mcpc login` command to recover.
 
-- Explicit CLI flags always take precedence over stored profiles
-- Credentials are never silently mixed up (personal → work) or downgraded (authenticated → unauthenticated)
-- You can mix authenticated sessions (with named profiles) and public access on the same server
+| Flag                            | Behavior                                                                                    |
+| ------------------------------- | ------------------------------------------------------------------------------------------- |
+| `--header "Authorization: ..."` | Use explicit header; skip OAuth auto-detection. Cannot combine with `--profile`.            |
+| `--profile <name>`              | Require the named profile to exist.                                                         |
+| `--no-profile`                  | Connect anonymously even if a `default` profile exists.                                     |
+| `--x402`                        | Skip OAuth auto-detection; use x402 payments instead. Combine with `--profile` to use both. |
+| _(none)_                        | Use `default` profile if it exists; otherwise connect anonymously.                          |
 
-**Examples:**
+Config file headers (from `--config`) apply to servers loaded from that file.
 
 ```bash
-# With specific profile - always authenticated:
-# - Uses 'work' if it exists
-# - Fails if it doesn't exist
-mcpc connect mcp.apify.com @apify-work --profile work
-
-# Without profile - opportunistic authentication:
-# - Uses 'default' if it exists
-# - Tries unauthenticated if 'default' doesn't exist
-# - Fails if the server requires authentication
+# Default: 'default' profile if it exists, else anonymous
 mcpc connect mcp.apify.com @apify-personal
 
-# Explicit bearer token - skips profile auto-detection:
-mcpc connect mcp.apify.com @apify --header "Authorization: Bearer ${APIFY_TOKEN}"
+# Specific profile (fails if missing)
+mcpc connect mcp.apify.com @apify-work --profile work
 
-# x402 payment - skips default profile auto-detection:
-mcpc connect mcp.apify.com @apify --x402
+# Explicit bearer token (no profile)
+mcpc connect mcp.apify.com @apify --header "Authorization: Bearer ${APIFY_TOKEN}"
 
-# Anonymous - skips default profile even if it exists:
+# Skip default profile, connect anonymously
 mcpc connect mcp.apify.com @apify-anon --no-profile
+
+# x402 micropayments instead of OAuth
+mcpc connect mcp.apify.com @apify --x402
 ```
 
 ## MCP proxy
@@ -592,22 +590,12 @@ mcpc @server tools-get search
 mcpc @server tools-call search query:="hello world"
 ```
 
-**Code mode** - Once agents understand the server's capabilities, they can write shell scripts
-that compose multiple `mcpc` commands with `--json` output. This can be
-[more accurate](https://www.anthropic.com/engineering/code-execution-with-mcp)
-and use fewer tokens than tool calling for complex workflows.
-
-```bash
-# AI-generated script using --json for structured data
-mcpc --json @apify tools-call search-actors keywords:="scraper" \
-  | jq '.content[0].text | fromjson | .items[0].id' \
-  | xargs -I {} mcpc @apify tools-call get-actor actorId:="{}"
-```
-
-With [schema validation](#schema-validation), agents can ensure stability of integrations and faster failure recovery.
-Agents, make no harm!
-
-See an [example](./docs/examples/company-lookup.sh) of an AI-generated shell script.
+**Code mode** - Once agents understand the server's capabilities, they can write shell
+scripts that compose multiple `mcpc` commands with `--json` output — see
+[Scripting](#scripting) below. This can be
+[more accurate](https://www.anthropic.com/engineering/code-execution-with-mcp) and use
+fewer tokens than tool calling for complex workflows. Pair with
+[schema validation](#schema-validation) to catch breaking changes early.
 
 ### Scripting
 
@@ -630,12 +618,15 @@ For a complete example script, see [`docs/examples/company-lookup.sh`](./docs/ex
 
 ### Schema validation
 
-Validate tool/prompt schemas using the `--schema` option to detect breaking changes early:
+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:
 
 ```bash
 # Save expected schema
 mcpc --json @apify tools-get search-actors > expected.json
 
+# Validate without calling (read-only check)
+mcpc @apify tools-get search-actors --schema expected.json
+
 # Validate before calling (fails if schema changed incompatibly)
 mcpc @apify tools-call search-actors --schema expected.json keywords:="test"
 ```
@@ -738,10 +729,10 @@ mcpc x402 sign <base64-payment-required> --amount 1.00 --expiry 3600 --json
 
 **Options:**
 
-| Option              | Description                                                      |
-| ------------------- | ---------------------------------------------------------------- |
-| `--amount <usd>`    | Override the payment amount in USD (e.g. `0.50` for $0.50)       |
-| `--expiry <seconds>`| Override the payment expiry in seconds from now (e.g. `3600`)    |
+| Option               | Description                                                   |
+| -------------------- | ------------------------------------------------------------- |
+| `--amount <usd>`     | Override the payment amount in USD (e.g. `0.50` for $0.50)    |
+| `--expiry <seconds>` | Override the payment expiry in seconds from now (e.g. `3600`) |
 
 The command outputs the signed `PAYMENT-SIGNATURE` header value and an MCP config snippet
 that can be used directly with other MCP clients.
@@ -812,7 +803,7 @@ The bridge process manages the full MCP session lifecycle:
 | 🔔 [**Notifications**](#list-change-notifications) | ✅ Supported                      |
 | 📄 [**Pagination**](#pagination)                   | ✅ Supported                      |
 | 🏓 [**Ping**](#ping)                               | ✅ Supported                      |
-| ⏳ [**Async tasks**](#async-tasks)                  | ✅ Supported                      |
+| ⏳ [**Async tasks**](#async-tasks)                 | ✅ Supported                      |
 | 📁 **Roots**                                       | 🚧 Planned                        |
 | ❓ **Elicitation**                                 | 🚧 Planned                        |
 | 🔤 **Completion**                                  | 🚧 Planned                        |
@@ -982,6 +973,9 @@ mcpc @apify tasks-list
 # Check task status
 mcpc @apify tasks-get <taskId>
 
+# Get the task result (blocks until the task reaches a terminal state)
+mcpc @apify tasks-result <taskId>
+
 # Cancel a running task
 mcpc @apify tasks-cancel <taskId>
 ```
@@ -989,6 +983,8 @@ mcpc @apify tasks-cancel <taskId>
 With `--task`, the CLI shows a progress spinner with elapsed time, server status messages,
 and progress notifications. Press **ESC** during execution to detach and get the task ID
 for later retrieval. With `--detach`, the task starts and returns the task ID immediately.
+Use `tasks-result <taskId>` to fetch the final `CallToolResult` payload once the task
+completes.
 
 `tools-list` and `tools-get` show task support annotations per tool:
 `[task:optional]`, `[task:required]`, or `[task:forbidden]`.
@@ -1055,16 +1051,13 @@ For **stdio servers:**
 - `args` (optional) - Array of command arguments
 - `env` (optional) - Environment variables for the process
 
-**Using servers from config file:**
-
-Reference servers by their name using the `file:entry` syntax:
-
-```bash
-# Create a named session from a server in the config
-mcpc connect .vscode/mcp.json:filesystem @fs
-mcpc @fs tools-list
-mcpc @fs tools-call search
-```
+> **Note:** Stdio servers inherit only a minimal env whitelist from the shell
+> (`PATH`, `HOME`, `SHELL`, …). Other vars — `NODE_EXTRA_CA_CERTS`, `HTTPS_PROXY`,
+> `SSL_CERT_FILE`, etc. — must be forwarded explicitly via the `env` block using
+> `${VAR_NAME}`. Anything the server writes to stderr is captured to
+> `~/.mcpc/logs/bridge-<session>.log` with a `[server stderr]` prefix, and the
+> tail is appended to the error message if `mcpc connect` fails, so you can see
+> why a stdio server failed to start.
 
 **Environment variable substitution:**
 
@@ -1218,19 +1211,19 @@ See [CONTRIBUTING](./CONTRIBUTING.md) for development setup, architecture overvi
 <!-- Stars, contributors, commits, and activity as of March 2026. -->
 
 | Tool                                                                    | Lang   | Stars | Contrib / Commits | Active | Tools | Resources | Prompts | Tasks | Code mode | Sessions | OAuth | Stdio | HTTP | Tool search | x402 | LLM |
-| ----------------------------------------------------------------------- | ------ | ----: | -----------------: | ------ | ----- | --------- | ------- | ----- | --------- | -------- | ----- | ----- | ---- | ----------- | ---- | --- |
-| **[apify/mcpc](https://github.com/apify/mcpc)**                         | TS     |  ~420 |           7 / ~510 | ✅     | ✅    | ✅        | ✅      | ✅    | ✅        | ✅       | ✅    | ✅    | ✅   | ✅          | ✅   | —   |
-| [steipete/mcporter](https://github.com/steipete/mcporter)               | TS     | ~3.5k |          24 / ~570 | ✅     | ✅    | —         | —       | —     | ✅        | ✅       | ✅    | ✅    | ✅   | —           | —    | —   |
-| [IBM/mcp-cli](https://github.com/IBM/mcp-cli)                           | Python | ~1.9k |          22 / ~790 | ✅     | ✅    | ✅        | ✅      | —     | ✅        | ✅       | ✅    | ✅    | ✅   | —           | —    | ✅  |
-| [knowsuchagency/mcp2cli](https://github.com/knowsuchagency/mcp2cli)     | Python | ~1.8k |           5 / ~76  | ✅     | ✅    | ✅        | ✅      | —     | ✅        | ✅       | ✅    | ✅    | ✅   | ✅          | —    | —   |
-| [f/mcptools](https://github.com/f/mcptools)                             | Go     | ~1.5k |          15 / ~170 | ⚠️     | ✅    | ✅        | ✅      | —     | ✅        | —        | —     | ✅    | ✅   | —           | —    | —   |
-| [philschmid/mcp-cli](https://github.com/philschmid/mcp-cli)             | TS     | ~1.1k |           2 / ~30  | ✅     | ✅    | —         | —       | —     | ✅        | ✅       | —     | ✅    | ✅   | ✅          | —    | —   |
-| [adhikasp/mcp-client-cli](https://github.com/adhikasp/mcp-client-cli)   | Python |  ~670 |          6 / ~110  | ⚠️     | ✅    | ✅        | ✅      | —     | —         | —        | —     | ✅    | —    | —           | —    | ✅  |
-| [thellimist/clihub](https://github.com/thellimist/clihub)               | Go     |  ~640 |           1 / ~60  | ✅     | ✅    | —         | —       | —     | —         | —        | ✅    | ✅    | ✅   | ✅          | —    | —   |
-| [wong2/mcp-cli](https://github.com/wong2/mcp-cli)                       | JS     |  ~430 |           4 / ~63  | ⚠️     | ✅    | ✅        | ✅      | —     | —         | —        | ✅    | —     | ✅   | —           | —    | —   |
-| [mcpshim/mcpshim](https://github.com/mcpshim/mcpshim)                   | Go     |   ~54 |           1 / ~13  | ✅     | ✅    | —         | —       | —     | ✅        | ✅       | ✅    | —     | ✅   | ✅          | —    | —   |
-| [evantahler/mcpx](https://github.com/evantahler/mcpx)                   | TS     |   ~28 |           1 / ~64  | ✅     | ✅    | ✅        | ✅      | ✅    | ✅        | —        | ✅    | ✅    | ✅   | ✅          | —    | —   |
-| [EstebanForge/mcp-cli-ent](https://github.com/EstebanForge/mcp-cli-ent) | Go     |   ~15 |          ~2 / ~46  | ✅     | ✅    | —         | —       | —     | ✅        | ✅       | —     | ✅    | ✅   | ✅          | —    | —   |
+| ----------------------------------------------------------------------- | ------ | ----: | ----------------: | ------ | ----- | --------- | ------- | ----- | --------- | -------- | ----- | ----- | ---- | ----------- | ---- | --- |
+| **[apify/mcpc](https://github.com/apify/mcpc)**                         | TS     |  ~420 |          7 / ~510 | ✅     | ✅    | ✅        | ✅      | ✅    | ✅        | ✅       | ✅    | ✅    | ✅   | ✅          | ✅   | —   |
+| [steipete/mcporter](https://github.com/steipete/mcporter)               | TS     | ~3.5k |         24 / ~570 | ✅     | ✅    | —         | —       | —     | ✅        | ✅       | ✅    | ✅    | ✅   | —           | —    | —   |
+| [IBM/mcp-cli](https://github.com/IBM/mcp-cli)                           | Python | ~1.9k |         22 / ~790 | ✅     | ✅    | ✅        | ✅      | —     | ✅        | ✅       | ✅    | ✅    | ✅   | —           | —    | ✅  |
+| [knowsuchagency/mcp2cli](https://github.com/knowsuchagency/mcp2cli)     | Python | ~1.8k |           5 / ~76 | ✅     | ✅    | ✅        | ✅      | —     | ✅        | ✅       | ✅    | ✅    | ✅   | ✅          | —    | —   |
+| [f/mcptools](https://github.com/f/mcptools)                             | Go     | ~1.5k |         15 / ~170 | ⚠️     | ✅    | ✅        | ✅      | —     | ✅        | —        | —     | ✅    | ✅   | —           | —    | —   |
+| [philschmid/mcp-cli](https://github.com/philschmid/mcp-cli)             | TS     | ~1.1k |           2 / ~30 | ✅     | ✅    | —         | —       | —     | ✅        | ✅       | —     | ✅    | ✅   | ✅          | —    | —   |
+| [adhikasp/mcp-client-cli](https://github.com/adhikasp/mcp-client-cli)   | Python |  ~670 |          6 / ~110 | ⚠️     | ✅    | ✅        | ✅      | —     | —         | —        | —     | ✅    | —    | —           | —    | ✅  |
+| [thellimist/clihub](https://github.com/thellimist/clihub)               | Go     |  ~640 |           1 / ~60 | ✅     | ✅    | —         | —       | —     | —         | —        | ✅    | ✅    | ✅   | ✅          | —    | —   |
+| [wong2/mcp-cli](https://github.com/wong2/mcp-cli)                       | JS     |  ~430 |           4 / ~63 | ⚠️     | ✅    | ✅        | ✅      | —     | —         | —        | ✅    | —     | ✅   | —           | —    | —   |
+| [mcpshim/mcpshim](https://github.com/mcpshim/mcpshim)                   | Go     |   ~54 |           1 / ~13 | ✅     | ✅    | —         | —       | —     | ✅        | ✅       | ✅    | —     | ✅   | ✅          | —    | —   |
+| [evantahler/mcpx](https://github.com/evantahler/mcpx)                   | TS     |   ~28 |           1 / ~64 | ✅     | ✅    | ✅        | ✅      | ✅    | ✅        | —        | ✅    | ✅    | ✅   | ✅          | —    | —   |
+| [EstebanForge/mcp-cli-ent](https://github.com/EstebanForge/mcp-cli-ent) | Go     |   ~15 |          ~2 / ~46 | ✅     | ✅    | —         | —       | —     | ✅        | ✅       | —     | ✅    | ✅   | ✅          | —    | —   |
 
 **Legend:** ✅ = supported, ⚠️ = stale (no commits in 3+ months), **Contrib / Commits** = contributors / total commits, **Tasks** = [async tasks](https://modelcontextprotocol.io/specification/latest/server/utilities/tasks), **x402** = [x402 payment protocol](https://www.x402.org/) support, **LLM** = requires/uses an LLM.