@apify/mcpc 0.3.0 → 0.3.1

package/CHANGELOG.md

@@ -7,22 +7,56 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.1] - 2026-06-08
+
+### Added
+
+- `mcpc @<session>` now reports the negotiated MCP protocol version and whether the connection is stateful (a stdio process, or an HTTP server that assigned a session id) or stateless (an HTTP server that assigned none — the upcoming `2026-07-28` model). A `stateless` field is exposed under `_mcpc` in the `--json` output of `mcpc @<session>` and `mcpc connect`, and on each session in the session list: `true` when stateless, `false` when stateful, and `null` while the mode is not yet known. Stateless sessions are never marked `expired` on a transient `404` (they hold no session to lose).
+- `mcpc @<session> logs` command to show or follow the bridge log file. Supports `-n/--tail <n>` (default 50), `--follow` to stream new lines, and `--since <duration|iso>` (e.g. `1h`, `30m`, `2026-04-28T12:00:00Z`). Transparently spans rotated files (`.log.1` … `.log.5`) when more lines are needed. With `--json`, returns parsed `{ time, level, context?, msg }` records (continuation lines such as stack traces fold into the preceding entry's `msg`; lines that aren't standard log entries become `{ raw }`); combined with `--follow`, output is JSONL. `mcpc @<session> --json` now also exposes `_mcpc.logPath`. Error messages that previously pointed users to a raw log file path now suggest `mcpc @<session> logs` instead (#205).
+
+### Changed
+
+- `mcpc connect` now waits for every connection to finish before reporting status. Bulk and auto-discovery connects (`mcpc connect`, `mcpc connect <file>`) previously returned immediately with an optimistic `connecting` status in human mode; they now behave like single-server connects and `--json`, showing each server as connected or failed (bounded by `--timeout`) with a progress spinner while connecting.
+
+### Deprecated
+
+- The `shell` command (`mcpc shell @<session>` and `mcpc @<session> shell`) is deprecated and will be removed in a future release. It is now hidden from `--help` output and prints a deprecation warning when invoked
+
+### Removed
+
+- `mcpc connect` no longer auto-connects to `mcp.apify.com` as `@apify` when the `APIFY_API_TOKEN` environment variable is set. Connect to it like any other server — `mcpc connect mcp.apify.com` — authenticating with `mcpc login` or `--header "Authorization: Bearer ..."`.
+
+### Fixed
+
+- `--timeout` now bounds the wait while a session connects to its server. The bridge health check that runs as a session starts previously ignored `--timeout`, so connecting to a slow or unreachable server could block for up to the 3-minute default regardless of a shorter `--timeout`.
+- `mcpc connect` (with no arguments) no longer silently ignores config files it can't use. Files with an empty servers object are listed as `0 servers`, and files that fail to load — invalid JSON, a project config missing a `mcpServers`/`servers` property, or an unreadable file — are listed as `(invalid)` with the reason, instead of being dropped or misreported as `No MCP config files found`.
+- `mcpc connect` now prints config file paths so they can be copy-pasted directly: paths containing spaces (e.g. macOS `Library/Application Support/...`) are quoted instead of being split when pasted into a shell.
+- `mcpc connect` no longer fails with `socket file not created within timeout` when the bridge is slow to start (CPU-constrained machines, many parallel connects). The startup window is more generous, and a bridge that crashes on startup now reports its exit code immediately instead of stalling until the timeout
+- Sessions no longer fail to start with `Bridge process exited during startup` when the mcpc home directory (or `MCPC_HOME_DIR`) resolves to a deep path — notably macOS temp dirs like `/var/folders/...` — or when a session name is very long. The bridge's Unix socket path was exceeding the operating system limit (104 bytes on macOS, 108 on Linux); such paths now fall back to a short location under the system temp directory
+- `mcpc @<session> restart` (and other session startups) no longer intermittently fail with `Failed to connect to bridge: connect ECONNREFUSED` during rapid restarts. The CLI now briefly retries the first connection to a freshly started bridge while it is still (re)creating its socket
+
 ## [0.3.0] - 2026-05-20
 
 ### Added
 
+- New **[EXPERIMENTAL]** `skills-list` and `skills-get` commands implementing the draft MCP skills extension (`io.modelcontextprotocol/skills`, [SEP-2640](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2640)). Marked experimental because the spec is still in draft and the index shape, recognized types, and capability key may change. Skills are discovered via the well-known `skill://index.json` resource, falling back to scanning `skill://*/SKILL.md` URIs. Supports all three SEP-2640 index entry types: `skill-md`, `archive` (`.tar.gz`/`.zip` bundles), and `mcp-resource-template`. Entries with unrecognized `type` values are skipped per spec. `skills-get <name>` reads a skill's `SKILL.md`; pass `--raw` to print just the markdown for piping to LLMs or files. The session overview lists `skills` under capabilities when a server advertises the extension under either `capabilities.extensions` (per spec) or `capabilities.experimental` (the SDK-preserved escape hatch). JSON shape: `[{ name, description, type, url }]` for `skills-list`, full `ReadResourceResult` for `skills-get`.
 - `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.
+- `mcpc x402 sign` supports the x402 `upto` scheme alongside `exact`. Use `--scheme <auto|upto|exact>` to pick a preference (default `auto` prefers `upto`, falls back to `exact`). The signer auto-grants a one-time `USDC.approve(PERMIT2, MAX_UINT256)` allowance on first upto sign; pass `--no-approve` to skip.
+- `mcpc connect --x402 [auto|upto|exact]` enables x402 auto-payment with an optional scheme preference. Bare `--x402` defaults to `auto` (prefer upto, fall back to exact). The choice is persisted to `sessions.json` and reused on `mcpc restart`. Flag position is unrestricted — `mcpc connect --x402 mcp.apify.com @s` and `mcpc connect mcp.apify.com @s --x402` both work.
+- Sessions using x402 auto-payment now show a yellow `[x402]` marker in session listings, alongside the existing OAuth and proxy markers.
 
 ### 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.
+- x402 debug logs now announce the selected scheme (`scheme=upto` / `scheme=exact`) up front and print USD amounts with 6-decimal precision (USDC atomic unit). Enable with `--verbose` or `MCPC_VERBOSE=1`.
 - **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
+- Human-mode `tools-call` / `tasks-result` output no longer prints the **Structured content** section when **Content** already has at least one visible block. The JSON dump was redundant verbose output (especially for LLMs) whenever a server returned both. The section is still shown when `content` is empty or contains only a JSON-dump duplicate of `structuredContent`; use `--json` to always get the full payload
 
 ### 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)
+- `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)
@@ -271,7 +305,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Interactive shell mode
 - JSON output mode for scripting
 
-[Unreleased]: https://github.com/apify/mcpc/compare/v0.3.0...HEAD
+[Unreleased]: https://github.com/apify/mcpc/compare/v0.3.1...HEAD
+[0.3.1]: https://github.com/apify/mcpc/compare/v0.3.0...v0.3.1
 [0.3.0]: https://github.com/apify/mcpc/compare/v0.2.6...v0.3.0
 [0.2.6]: https://github.com/apify/mcpc/compare/v0.2.5...v0.2.6
 [0.2.5]: https://github.com/apify/mcpc/compare/v0.2.4...v0.2.5

package/README.md

@@ -63,12 +63,12 @@ wiring up dozens of MCP functions. Just one `Bash()` tool, and `mcpc` handles th
 
 ```
 
-  ┌──────────┐         Bash()         ┌──────────┐           MCP          ┌────────────┐
-  │ AI agent │  ────────────────────► │   mcpc   │  ────────────────────► │ MCP server │
-  └──────────┘                        └──────────┘    Sessions, OAuth,    └────────────┘
-                                                      Tools, Resources,
-                                                      Prompts, Tasks,
-                                                      x402, ...
+ ┌──────────┐   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
@@ -80,6 +80,8 @@ many AI agents on the same machine. Authenticate once, reuse everywhere.
 
 ## Install
 
+Requires a JavaScript runtime — install the latest [Node.js](https://nodejs.org/en/download) or [Bun](https://bun.sh) if you don't have one yet.
+
 ```bash
 npm install -g @apify/mcpc
 
@@ -127,6 +129,56 @@ 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)
+  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> skills-list
+  <@session> skills-get <name> [--raw]
+  <@session> tasks-list
+  <@session> tasks-get <taskId>
+  <@session> tasks-result <taskId>
+  <@session> tasks-cancel <taskId>
+  <@session> logging-set-level <level>
+  <@session> ping
+  <@session> logs [-n N] [--follow] [--since 1h]
+
+Run "mcpc" without arguments to show active sessions and OAuth profiles.
+Run "mcpc --json" to get the same data as `{ sessions: [...], profiles: [...] }`.
 ```
 
 ### General actions
@@ -153,6 +205,26 @@ The `connect`, `login`, and `logout` commands accept a `<server>` argument in th
 - **Remote URL** (e.g. `mcp.apify.com` or `https://mcp.apify.com`) — scheme defaults to `https://`
 - **Config file entry** (e.g. `~/.vscode/mcp.json:filesystem`) — `file:entry-name` syntax
 
+`connect` additionally supports two **bulk** forms that connect many servers at once:
+
+- **Config file** without an entry (e.g. `~/.vscode/mcp.json`) — connect every server in the file
+- **No argument** (`mcpc connect`) — auto-discover MCP config files in the current directory and
+  your home dir (`.mcp.json`, `mcp.json`, `.cursor/mcp.json`, `.vscode/mcp.json`, `~/.claude.json`,
+  Claude Desktop, Windsurf, Kiro, …) and connect everything found (run `mcpc connect --help` for the
+  full list).
+
+```bash
+mcpc connect                      # discover standard config files and connect all servers
+mcpc connect ~/.vscode/mcp.json   # connect every server in one file
+```
+
+Bulk connects auto-generate session names (so they don't take an `@session`) and **skip local
+stdio servers by default** — pass `--stdio` to include them. Each discovered config file is listed
+with its servers and their status (`● live`, `● connecting`); files that can't be used are shown as
+`(0 servers)` or `(invalid)` with the reason, rather than silently ignored. Without `--json` the
+command returns right away without waiting for every connection to finish (still-connecting sessions
+show `● connecting`); `--json` waits and reports each server's details.
+
 ### MCP commands
 
 All MCP commands go through a named session created with `connect`:
@@ -302,7 +374,7 @@ and auto-reconnects on network failures or its own crashes (10s cooldown on fail
 **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                                |
@@ -437,13 +509,13 @@ always win over stored profiles, and credentials are never silently downgraded.
 is missing, expired, or invalid, `mcpc` fails with an error that includes the right
 `mcpc login` command to recover.
 
-| 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.                          |
+| 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 [scheme]`               | Skip OAuth auto-detection; use x402 payments instead. Optional scheme: `auto` (default), `upto`, `exact`. Combine with `--profile` to use both. |
+| _(none)_                        | Use `default` profile if it exists; otherwise connect anonymously.                                                                              |
 
 Config file headers (from `--config`) apply to servers loaded from that file.
 
@@ -620,6 +692,9 @@ To help Claude Code use `mcpc`, you can install this [Claude skill](./docs/claud
 
 <!-- TODO: Add also AGENTS.md, GitHub skills etc. -->
 
+`mcpc` also acts as a **client for skills served by MCP servers** (experimental, SEP-2640) — see
+[Skills](#skills) for the `skills-list` / `skills-get` commands.
+
 ## Agentic payments (x402)
 
 > ⚠️ **Experimental.** This feature is under active development and may change.
@@ -633,13 +708,12 @@ This is entirely **opt-in**: existing functionality is unaffected unless you exp
 
 ### How it works
 
-1. **Server returns HTTP 402** with a `PAYMENT-REQUIRED` header describing the price and payment details.
-2. `mcpc` parses the header, signs an [EIP-3009](https://eips.ethereum.org/EIPS/eip-3009) `TransferWithAuthorization` using your local wallet.
-3. `mcpc` retries the request with a `PAYMENT-SIGNATURE` header containing the signed payment.
-4. The server verifies the signature and fulfills the request.
+Two schemes are supported, both signed by your local wallet:
+
+- **`exact`** — EIP-3009 `TransferWithAuthorization`. Settles on-chain at call-time.
+- **`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).
 
-For tools that advertise pricing in their `_meta.x402` metadata, `mcpc` can **proactively sign** payments
-on the first request, avoiding the 402 round-trip entirely.
+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.
 
 ### Wallet setup
 
@@ -683,31 +757,38 @@ 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`)           |
+| `--scheme <val>`     | Scheme preference: `auto` (default, upto > exact), `upto`, or `exact`   |
+| `--no-approve`       | For `upto`, skip checking and auto-approving on-chain Permit2 allowance |
 
 The command outputs the signed `PAYMENT-SIGNATURE` header value and an MCP config snippet
 that can be used directly with other MCP clients.
 
 ### Using x402 with MCP servers
 
-Pass the `--x402` flag when connecting to a session or running direct commands:
+Pass the `--x402` flag when connecting to a session. It accepts an optional scheme preference
+(`auto`, `upto`, or `exact`); bare `--x402` defaults to `auto`.
 
 ```bash
-# Create a session with x402 payment support
+# Create a session with x402 payment support (auto picks the best advertised scheme)
 mcpc connect mcp.apify.com @apify --x402
 
-# The session now automatically handles 402 responses
+# Pin a specific scheme — position doesn't matter, before or after positional args
+mcpc connect --x402 upto mcp.apify.com @apify
+mcpc connect mcp.apify.com @apify --x402 exact
+
+# The session now automatically handles 402 responses using your preference
 mcpc @apify tools-call expensive-tool query:="hello"
 
-# Restart a session with x402 enabled
-mcpc @apify restart --x402
+# Restart re-uses the saved scheme from sessions.json — no need to repeat the flag
+mcpc @apify restart
 ```
 
 When `--x402` is active, a fetch middleware wraps all HTTP requests to the MCP server.
-If any request returns HTTP 402, the middleware transparently signs and retries.
+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.
 
 ### Supported networks
 
@@ -747,21 +828,22 @@ The bridge process manages the full MCP session lifecycle:
 
 ### MCP feature support
 
-| **Feature**                                        | **Status**                        |
-| :------------------------------------------------- | :-------------------------------- |
-| 📖 [**Instructions**](#server-instructions)        | ✅ Supported                      |
-| 🔧 [**Tools**](#tools)                             | ✅ Supported                      |
-| 💬 [**Prompts**](#prompts)                         | ✅ Supported                      |
-| 📦 [**Resources**](#resources)                     | ✅ Supported                      |
-| 📝 [**Logging**](#server-logs)                     | ✅ Supported                      |
-| 🔔 [**Notifications**](#list-change-notifications) | ✅ Supported                      |
-| 📄 [**Pagination**](#pagination)                   | ✅ Supported                      |
-| 🏓 [**Ping**](#ping)                               | ✅ Supported                      |
-| ⏳ [**Async tasks**](#async-tasks)                 | ✅ Supported                      |
-| 📁 **Roots**                                       | 🚧 Planned                        |
-| ❓ **Elicitation**                                 | 🚧 Planned                        |
-| 🔤 **Completion**                                  | 🚧 Planned                        |
-| 🤖 **Sampling**                                    | ❌ Not applicable (no LLM access) |
+| **Feature**                                        | **Status**                         |
+| :------------------------------------------------- | :--------------------------------- |
+| 📖 [**Instructions**](#server-instructions)        | ✅ Supported                       |
+| 🔧 [**Tools**](#tools)                             | ✅ Supported                       |
+| 💬 [**Prompts**](#prompts)                         | ✅ Supported                       |
+| 📦 [**Resources**](#resources)                     | ✅ Supported                       |
+| 🧠 [**Skills**](#skills)                           | 🧪 Experimental (SEP-2640)         |
+| 📝 [**Logging**](#server-logs)                     | ✅ Supported (deprecated by MCP)   |
+| 🔔 [**Notifications**](#list-change-notifications) | ✅ Supported                       |
+| 📄 [**Pagination**](#pagination)                   | ✅ Supported                       |
+| 🏓 [**Ping**](#ping)                               | ✅ Supported                       |
+| ⏳ [**Async tasks**](#async-tasks)                 | ✅ Supported                       |
+| 📁 **Roots**                                       | ❌ Not planned (deprecated by MCP) |
+| ❓ **Elicitation**                                 | 🚧 Planned                         |
+| 🔤 **Completion**                                  | 🚧 Planned                         |
+| 🤖 **Sampling**                                    | ❌ Not applicable (no LLM access)  |
 
 #### Server instructions
 
@@ -863,6 +945,41 @@ mcpc @apify resources-subscribe "https://api.example.com/data"
 mcpc @apify resources-templates-list
 ```
 
+#### Skills
+
+> 🧪 **Experimental.** Implements the draft [MCP skills extension (SEP-2640)](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2640).
+> The spec is in active iteration; the index shape, recognized entry types, and capability key may change.
+
+[Agent Skills](https://agentskills.io/) are reusable markdown workflow instructions (`SKILL.md` with YAML frontmatter)
+that AI agents load on demand. `mcpc` lets you discover and pull skills served by any MCP server that exposes
+them under the `skill://` URI convention — no SDK changes required, since skills are just resources:
+
+```bash
+# List skills exposed by the server (tries skill://index.json, falls back to scanning skill://*/SKILL.md)
+mcpc @apify skills-list
+
+# Read a skill's SKILL.md by bare name, nested path, or full URI
+mcpc @apify skills-get git-workflow
+mcpc @apify skills-get acme/billing/refunds
+mcpc @apify skills-get skill://git-workflow/SKILL.md
+
+# Print just the markdown (no header/fences) — pipe straight to an LLM or a file
+mcpc @apify skills-get git-workflow --raw > /tmp/skill.md
+
+# JSON for scripts: [{ name, description, type, url }]
+mcpc --json @apify skills-list | jq '.[].name'
+```
+
+Recognized index entry types (per SEP-2640): `skill-md` (concrete skill), `mcp-resource-template`
+(parameterized namespace), and `archive` (`.tar.gz`/`.zip` bundle — fetch the URL via `resources-read`).
+Entries with an unrecognized `type` are silently skipped.
+
+Skills appear under capabilities in `mcpc @session` output when a server advertises the extension
+under either `capabilities.extensions["io.modelcontextprotocol/skills"]` (per spec) or
+`capabilities.experimental["io.modelcontextprotocol/skills"]` (the SDK-preserved escape hatch some
+SDKs still use). Skill content is treated as untrusted input — `mcpc` only reads and prints it; it
+never executes hooks, scripts, or other frontmatter-declared behavior.
+
 #### List change notifications
 
 When connected via a [session](#sessions), `mcpc` automatically handles `list_changed`
@@ -965,6 +1082,10 @@ mcpc connect .vscode/mcp.json:apify @my-apify
 mcpc @my-apify tools-list
 ```
 
+`mcpc` also finds these files for you: run `mcpc connect` with no arguments to auto-discover config
+files in standard locations and connect every server, or pass a file without an entry to connect all
+of its servers. See [Server formats](#server-formats).
+
 **Example MCP config JSON file:**
 
 ```json
@@ -1128,9 +1249,11 @@ This causes `mcpc` to print detailed debug messages to stderr.
 
 ### Logs
 
-The background bridge processes log to `~/.mcpc/logs/bridge-@<session>.log`.
-The main `mcpc` process doesn't save log files, but supports [verbose mode](#verbose-mode).
-`mcpc` automatically rotates log files: keep last 10MB per session, max 5 files.
+View the bridge log for a session with `mcpc @<session> logs` (run with
+`--help` for `--follow`, `-n`, and `--since` options). The underlying file
+lives at `~/.mcpc/logs/bridge-@<session>.log` and is rotated automatically
+(10MB per file, max 5 files). The main `mcpc` process doesn't save log
+files, but supports [verbose mode](#verbose-mode).
 
 ### Troubleshooting
 

package/dist/bridge/index.js

@@ -2,10 +2,11 @@
 import { initProxy, proxyFetch } from '../lib/proxy.js';
 import { createServer } from 'net';
 import { unlink } from 'fs/promises';
-import { createMcpClient } from '../core/index.js';
-import { KEEPALIVE_INTERVAL_MS } from '../lib/types.js';
+import { dirname } from 'path';
+import { createMcpClient, buildClientCapabilities } from '../core/index.js';
+import { KEEPALIVE_INTERVAL_MS, X402_SCHEME_PREFERENCES } from '../lib/types.js';
 import { createLogger, setVerbose, initFileLogger, closeFileLogger } from '../lib/index.js';
-import { fileExists, getBridgesDir, getSocketPath, ensureDir, cleanupOrphanedLogFiles, isSessionExpiredError, } from '../lib/index.js';
+import { fileExists, getSocketPath, ensureDir, cleanupOrphanedLogFiles, isSessionExpiredError, StderrTail, } from '../lib/index.js';
 import { ClientError, ServerError, NetworkError, AuthError, isAuthenticationError, } from '../lib/index.js';
 import { getSession, loadSessions, updateSession } from '../lib/sessions.js';
 import { OAuthTokenManager } from '../lib/auth/oauth-token-manager.js';
@@ -43,10 +44,7 @@ class BridgeProcess {
     mcpClientReady;
     mcpClientReadyResolver;
     mcpClientReadyRejecter;
-    stderrTail = [];
-    stderrTailChars = 0;
-    static STDERR_TAIL_MAX_LINES = 50;
-    static STDERR_TAIL_MAX_CHARS = 8_000;
+    stderrTail = new StderrTail();
     constructor(options) {
         this.options = options;
         this.socketPath = getSocketPath(options.sessionName, process.pid);
@@ -252,9 +250,8 @@ class BridgeProcess {
                 if (isAuthenticationError(errorMsg) && !(error instanceof AuthError)) {
                     classifiedError = new AuthError(errorMsg);
                 }
-                if (this.stderrTail.length > 0) {
-                    const tail = this.stderrTail.map((l) => `  ${l}`).join('\n');
-                    classifiedError.message = `${classifiedError.message}\n\nRecent server stderr:\n${tail}`;
+                if (this.stderrTail.count > 0) {
+                    classifiedError.message = `${classifiedError.message}\n\nRecent server stderr:\n${this.stderrTail.format()}`;
                 }
                 this.mcpClientReadyRejecter(classifiedError);
                 if (isSessionExpiredError(errorMsg, {
@@ -295,18 +292,9 @@ class BridgeProcess {
         }
     }
     recordServerStderr(line) {
-        const trimmed = line.length > BridgeProcess.STDERR_TAIL_MAX_CHARS
-            ? line.slice(0, BridgeProcess.STDERR_TAIL_MAX_CHARS) + '…'
-            : line;
-        logger.info(`[server stderr] ${trimmed}`);
-        this.stderrTail.push(trimmed);
-        this.stderrTailChars += trimmed.length + 1;
-        while (this.stderrTail.length > BridgeProcess.STDERR_TAIL_MAX_LINES ||
-            (this.stderrTail.length > 1 && this.stderrTailChars > BridgeProcess.STDERR_TAIL_MAX_CHARS)) {
-            const removed = this.stderrTail.shift();
-            if (removed === undefined)
-                break;
-            this.stderrTailChars -= removed.length + 1;
+        const stored = this.stderrTail.add(line);
+        if (stored !== null) {
+            logger.info(`[server stderr] ${stored}`);
         }
     }
     broadcastNotification(method, params) {
@@ -370,22 +358,13 @@ class BridgeProcess {
                 wallet,
                 getToolByName,
                 paymentCache: this.x402PaymentCache,
+                ...(this.options.x402 && { schemePreference: this.options.x402 }),
             });
         }
         const clientConfig = {
             clientInfo: { name: 'mcpc', version: mcpcVersion },
             serverConfig,
-            capabilities: {
-                roots: { listChanged: true },
-                sampling: {},
-                tasks: {
-                    list: {},
-                    cancel: {},
-                    requests: {
-                        sampling: { createMessage: {} },
-                    },
-                },
-            },
+            capabilities: buildClientCapabilities(),
             ...(this.authProvider && { authProvider: this.authProvider }),
             ...(this.options.mcpSessionId && { mcpSessionId: this.options.mcpSessionId }),
             ...(customFetch && { customFetch }),
@@ -462,6 +441,9 @@ class BridgeProcess {
         if (serverDetails.protocolVersion) {
             sessionUpdate.protocolVersion = serverDetails.protocolVersion;
         }
+        if (serverDetails.connectionMode) {
+            sessionUpdate.connectionMode = serverDetails.connectionMode;
+        }
         if (serverDetails.serverInfo) {
             sessionUpdate.serverInfo = serverDetails.serverInfo;
         }
@@ -551,8 +533,9 @@ class BridgeProcess {
                 return;
             }
         }
+        const hadActiveSession = !!(this.options.mcpSessionId || this.client?.getMcpSessionId());
         let status = null;
-        if (isSessionExpiredError(error.message, { hadActiveSession: true })) {
+        if (isSessionExpiredError(error.message, { hadActiveSession })) {
             logger.warn('Session appears to be expired, marking as expired and shutting down');
             status = 'expired';
         }
@@ -599,7 +582,7 @@ class BridgeProcess {
     }
     async createSocketServer() {
         if (process.platform !== 'win32') {
-            await ensureDir(getBridgesDir());
+            await ensureDir(dirname(this.socketPath));
             if (await fileExists(this.socketPath)) {
                 logger.debug(`Removing existing socket: ${this.socketPath}`);
                 await unlink(this.socketPath);
@@ -712,7 +695,7 @@ class BridgeProcess {
         const paymentRequired = extractPaymentRequiredFromResult(toolResult);
         if (!paymentRequired)
             return { handled: false };
-        const parsed = extractAcceptFromPaymentRequired(paymentRequired);
+        const parsed = extractAcceptFromPaymentRequired(paymentRequired, this.options.x402);
         if (!parsed) {
             logger.warn('Payment-required tool result but could not extract supported payment terms');
             return { handled: false };
@@ -726,7 +709,7 @@ class BridgeProcess {
                 resource: parsed.resource,
             });
             this.x402PaymentCache.signature = signed.paymentSignatureBase64;
-            logger.debug(`Fresh payment signed for retry: $${signed.amountUsd.toFixed(4)} to ${signed.to} on ${signed.networkLabel}`);
+            logger.debug(`Fresh payment signed for retry: $${signed.amountUsd.toFixed(6)} to ${signed.to} on ${signed.networkLabel}`);
         }
         catch (signError) {
             logger.warn('Failed to sign fresh payment for 402 retry:', signError);
@@ -1084,7 +1067,7 @@ class BridgeProcess {
 async function main() {
     const args = process.argv.slice(2);
     if (args.length < 2) {
-        console.error('Usage: mcpc-bridge <sessionName> <transportConfigJson> [--verbose] [--profile <name>] [--proxy-host <host>] [--proxy-port <port>] [--mcp-session-id <id>] [--x402] [--insecure]');
+        console.error('Usage: mcpc-bridge <sessionName> <transportConfigJson> [--verbose] [--profile <name>] [--proxy-host <host>] [--proxy-port <port>] [--mcp-session-id <id>] [--x402 <auto|upto|exact>] [--insecure]');
         process.exit(1);
     }
     const sessionName = args[0];
@@ -1110,7 +1093,16 @@ async function main() {
     if (mcpSessionIdIndex !== -1 && args[mcpSessionIdIndex + 1]) {
         mcpSessionId = args[mcpSessionIdIndex + 1];
     }
-    const x402 = args.includes('--x402');
+    let x402;
+    const x402Index = args.indexOf('--x402');
+    if (x402Index !== -1) {
+        const value = args[x402Index + 1];
+        if (value === undefined || !X402_SCHEME_PREFERENCES.includes(value)) {
+            console.error(`--x402 requires a scheme: ${X402_SCHEME_PREFERENCES.join('|')} (got ${value ?? '<missing>'})`);
+            process.exit(1);
+        }
+        x402 = value;
+    }
     const insecure = args.includes('--insecure');
     initProxy({ insecure });
     try {
@@ -1129,7 +1121,7 @@ async function main() {
             bridgeOptions.mcpSessionId = mcpSessionId;
         }
         if (x402) {
-            bridgeOptions.x402 = true;
+            bridgeOptions.x402 = x402;
         }
         if (insecure) {
             bridgeOptions.insecure = true;