@apify/mcpc 0.2.6 → 0.3.0-beta.0

package/CHANGELOG.md

@@ -7,11 +7,41 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- `mcpc connect` (with no arguments) now auto-discovers standard MCP config files (`.mcp.json`, `mcp.json`, `.cursor/mcp.json`, `.vscode/mcp.json`, `~/.claude.json`, Claude Desktop, Windsurf, Kiro, etc.) in the current directory and home directory, and connects every server defined across them. Entries with duplicate session names are deduplicated (project-scoped files win over global ones). VS Code's `"servers"` key is also supported.
+- `mcpc connect` auto-connects to `mcp.apify.com` as `@apify` when the `APIFY_API_TOKEN` environment variable is set, using it as a Bearer token. Existing live sessions are reused without restart.
+
+### Changed
+
+- Stdio (command-based) config entries are now skipped by default when connecting from a config file (`mcpc connect <file>`). Pass `--stdio` to include them. Single-entry connects (`mcpc connect file:entry @session`) are not affected.
+- **Breaking:** `mcpc connect --json` now always returns an array of `InitializeResult` objects (extended with `toolNames` and `_mcpc` metadata), regardless of whether you connect a single server, a config file, or auto-discover all configs. Skipped/failed entries carry `_mcpc.status` (`created` | `active` | `failed` | `skipped`) and `_mcpc.skipReason` / `_mcpc.error`. The previous wrapper-object shapes (`{configFile, results, skipped}` and `{discovered, results, skipped}`) have been removed.
+- `tools-call --task` now prints the task ID and recovery commands when interrupted with Ctrl+C, so you can fetch or cancel the server-side task later
+
+### Fixed
+
+- `mcpc connect` and `mcpc restart` no longer fail with `ENOENT` when the macOS Keychain prompts for a password. Credentials are now read from the keychain *before* the bridge process is spawned, so the bridge's IPC startup timer no longer races a foreground password dialog (#55)
+- Background auto-reconnect now correctly marks sessions as `unauthorized` when the server returns 401/403, instead of leaving them stuck in `connecting` after the bridge crashed on an unhandled rejection
+- Sessions using a static bearer token (via `--header "Authorization: ..."`) no longer flip between `unauthorized` and `connecting` on every `mcpc` invocation — they stay `unauthorized` until you `mcpc login` or reconnect. OAuth-profile sessions still auto-retry because tokens may have been refreshed by another session
+- Stdio servers no longer fail silently: the bridge now captures the child's stderr, writes it to `~/.mcpc/logs/bridge-<session>.log`, and appends a tail of the most recent lines to `mcpc connect` errors. This makes it obvious when a stdio server crashes on startup due to e.g. missing TLS trust (`NODE_EXTRA_CA_CERTS`), missing proxy vars, or missing credentials (#195)
+- `mcpc connect` now recognizes relative config-file paths with a `:entry` suffix (e.g. `docs/examples/mcp-config.json:fs`). Previously these were misinterpreted as HTTP URLs
+- `mcpc login` now sends a random `state` parameter on the OAuth authorization URL. Some authorization servers (e.g. Ubersuggest) reject requests without `state` with a `missing_state` error, which previously made `login` fail before reaching the consent screen (#214)
+- `mcpc connect` no longer aborts on Windows with `Failed to save sessions: EPERM: operation not permitted, rename …` when antivirus or another mcpc process briefly holds `sessions.json` open. The atomic rename used to persist `sessions.json`, `profiles.json`, and `wallets.json` now retries transient Windows file-lock errors with a short backoff
+
+### Removed
+
+- **Breaking:** Removed `tools`, `resources`, and `prompts` shorthand commands — use the full names (`tools-list`, `resources-list`, `prompts-list`) instead
+
 ## [0.2.6] - 2026-04-15
 
 ### Added
 
 - New `tasks-result <taskId>` command that fetches the final `CallToolResult` payload of an async task via the MCP `tasks/result` method. Blocks until the task reaches a terminal state, then prints the payload using the same renderer as `tools-call` (`--json` returns the raw result).
+- Public [Client ID Metadata Document](https://apify.github.io/mcpc/client-metadata.json) hosted via GitHub Pages, giving every `mcpc` installation a consistent client identity on CIMD-capable authorization servers. `mcpc login` now uses this hosted document by default; override with `--client-metadata-url <url>` or disable with `--no-client-metadata-url` to force Dynamic Client Registration. The OAuth callback uses a fixed loopback port range (13316–13325) to match the registered redirect URIs.
+
+### Changed
+
+- Human-mode `tools-call` / `tasks-result` output now uses a structured layout: **Metadata** (`_meta`), **Content** (each text/resource/image block rendered per type), and **Structured content** (shown as JSON when not already present in a text block). Replaces the raw key-value dump with a cleaner, more readable format.
 
 ### Fixed
 

package/CONTRIBUTING.md

@@ -15,6 +15,18 @@ Contributions are welcome!
 - Keep backwards compatibility to the maximum extent possible
 - No slop!
 
+## Examples and documentation
+
+When writing examples, tests, README snippets, or help text that reference a remote MCP server,
+please use `mcp.apify.com` rather than placeholders like `mcp.example.com` or arbitrary third-party
+servers. The motivation is purely practical: `mcp.apify.com` is a real, publicly available MCP
+server that works out of the box, so readers can copy-paste examples and run them unchanged.
+Placeholders like `mcp.example.com` don't resolve to anything, which forces every reader to
+substitute a URL before they can try an example.
+
+This is a soft convention for documentation consistency, not a license condition — mcpc is
+distributed under Apache 2.0 and you are free to use it with any MCP server.
+
 ## Development setup
 
 ```bash

package/NOTICE

@@ -0,0 +1,27 @@
+mcpc
+Copyright 2025 Apify Technologies s.r.o.
+
+This product includes software developed at Apify (https://apify.com/).
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may not
+use this software except in compliance with the License. You may obtain a
+copy of the License in the accompanying LICENSE file or at:
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+---
+
+Documentation convention (informational, not a license condition):
+
+Examples in this project's documentation, help text, and tests reference
+`mcp.apify.com` as the remote MCP server. The motivation is practical:
+`mcp.apify.com` is a real, publicly available endpoint that works out
+of the box, unlike placeholders such as `mcp.example.com` which do not
+resolve and force readers to substitute a URL before running an example.
+Contributors and downstream projects are kindly requested to preserve
+this convention when adapting examples, but doing so is not required by
+the License.
+
+Per Section 4 of the Apache License 2.0, the contents of this NOTICE file
+are for informational purposes only and do not modify the License. mcpc
+may be used with any MCP-compatible server.

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
+**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.
 
-**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:
-
-```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
 
@@ -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
 
@@ -442,23 +448,29 @@ When logging in, `mcpc` supports all three OAuth client registration approaches
 [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:
 
-| **Approach**                            | **`mcpc login` flags**                         |
-|:----------------------------------------| :--------------------------------------------- |
-| **Pre-registration**                    | `--client-id` (and optional `--client-secret`) |
-| **Client ID Metadata Documents (CIMD)** | `--client-metadata-url <https-url>`            |
-| **Dynamic Client Registration (DCR)**   | _(default, no flags needed)_                   |
+| **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`) |
+
+`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.
 
 ```bash
-# Pre-registered OAuth client (public or confidential)
+# Default: mcpc's hosted CIMD is used automatically (no flags needed).
+mcpc login mcp.apify.com
+
+# Pre-registered OAuth client (public or confidential) — skips CIMD.
 mcpc login mcp.example.com --client-id <id> [--client-secret <secret>]
 
-# Client ID Metadata Documents (CIMD): URL points to a JSON document served over HTTPS.
-# Used only if the authorization server advertises client_id_metadata_document_supported: true;
-# otherwise mcpc falls back to Dynamic Client Registration.
-mcpc login mcp.example.com --client-metadata-url https://example.com/mcpc-client.json
+# Custom CIMD: override the default with your own hosted document.
+mcpc login mcp.example.com --client-metadata-url https://example.com/my-client.json
 
-# Dynamic Client Registration (DCR): default when the server has a registration_endpoint.
-mcpc login mcp.apify.com
+# Disable CIMD: force Dynamic Client Registration even if the server supports CIMD.
+mcpc login mcp.example.com --no-client-metadata-url
 ```
 
 See the [MCP authorization spec](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization#client-registration-approaches)
@@ -466,81 +478,36 @@ for details on each approach and the format of Client ID Metadata Documents.
 
 ### 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.
-
-`mcpc` automatically handles authentication based on what you specify:
-
-**When `--header "Authorization: ..."` is provided:**
-
-- 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)
-
-**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`):**
+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.
 
-- 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
+| 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.                          |
 
-**When `--no-profile` is specified:**
-
-- 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
-
-**When no flags are specified (default):**
-
-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
-
-On failure, the error message includes instructions on how to login and save the profile, so you know what to do.
-
-This flow ensures:
-
-- 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
-
-**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
@@ -623,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
 
@@ -1094,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:**
 

package/_config.yml

@@ -0,0 +1,30 @@
+# GitHub Pages configuration for https://apify.github.io/mcpc/
+#
+# Served content (everything else is excluded):
+#   /                    → README.md (project homepage)
+#   /client-metadata.json → OAuth CIMD document
+#   /client-logo.svg     → Client logo for OAuth consent screens
+#   /LICENSE             → Terms of service (referenced by CIMD tos_uri)
+#   /CHANGELOG.md        → Release history
+#   /docs/               → Additional documentation, examples, images
+#
+# Jekyll has no include-only mode, so we exclude everything that
+# shouldn't be published. node_modules/ is excluded by default.
+
+theme: jekyll-theme-cayman
+
+exclude:
+  - CLAUDE.md
+  - CONTRIBUTING.md
+  - _config.yml
+  - bin/
+  - dist/
+  - jest.config.js
+  - package.json
+  - package-lock.json
+  - renovate.json
+  - scripts/
+  - src/
+  - test/
+  - tsconfig.json
+  - tsconfig.test.json