@apify/mcpc 0.1.4 → 0.1.6

package/README.md

@@ -1,29 +1,22 @@
 # `mcpc`: Universal MCP command-line client
 
-`mcpc` is a CLI for the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/),
-which maps MCP operations to intuitive commands for interactive shell use, scripts, and AI coding agents.
+`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` can connect to any MCP server over Streamable HTTP or stdio transports,
-securely login via OAuth credentials and store credentials,
-and keep long-term sessions to multiple servers.
-It supports all major MCP features, including tools, resources, prompts, asynchronous tasks, and notifications.
+`mcpc` is useful for inspecting MCP 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.
 
-`mcpc` is handy for manual testing of MCP servers, scripting,
-and AI coding agents to use MCP in ["code mode"](https://www.anthropic.com/engineering/code-execution-with-mcp),
-for better accuracy and lower token compared to traditional tool function calling.
-After all, UNIX-compatible shell script is THE most universal coding language, for people and LLMs alike.
+![mcpc screenshot](https://raw.githubusercontent.com/apify/mcpc/main/docs/images/mcpc-screenshot.png)
 
-Note that `mcpc` does not use LLMs on its own; that's a job for the higher layer.
-
-**Key features**
-
-- 🔌 **Super compatible** - Works with any MCP server over Streamable HTTP or stdio.
+**Key features:**
+- 🌎 **Highly compatible** - Works with any MCP server over Streamable HTTP or stdio.
 - 🔄 **Persistent sessions** - Keep multiple server connections alive simultaneously.
 - 🚀 **Zero setup** - Connect to remote servers instantly with just a URL.
-- 🔧 **Full protocol support** - Tools, resources, prompts, dynamic discovery, and async notifications.
-- 📊 **JSON output** - Easy integration with `jq`, scripts, and other CLI tools.
-- 🤖 **AI-friendly** - Designed for code generation and automated workflows.
-- 🔒 **Secure** - OS keychain integration for credentials, encrypted auth storage.
+- 🔧 **Strong MCP support** - Instructions, tools, resources, prompts, dynamic discovery.
+- 🔌 **JSON output** - Easy integration with `jq`, scripts, and other CLI tools.
+- 🤖 **AI-friendly** - Designed for both function calling and code mode with sandboxing.
+- 🔒 **Secure** - Full OAuth 2.1 support, OS keychain for credentials storage.
 
 
 ## Table of contents
@@ -34,48 +27,15 @@ Note that `mcpc` does not use LLMs on its own; that's a job for the higher layer
 - [Install](#install)
 - [Quickstart](#quickstart)
 - [Usage](#usage)
-  - [MCP command arguments](#mcp-command-arguments)
-  - [Global flags](#global-flags)
-- [Authentication](#authentication)
-  - [No authentication](#no-authentication)
-  - [Bearer token authentication](#bearer-token-authentication)
-  - [OAuth authentication](#oauth-authentication)
-    - [Authentication profiles](#authentication-profiles)
-    - [Authentication behavior](#authentication-behavior)
-    - [Multiple accounts for the same server](#multiple-accounts-for-the-same-server)
-  - [Authentication precedence](#authentication-precedence)
-  - [Authentication profiles storage format](#authentication-profiles-storage-format)
 - [Sessions](#sessions)
-  - [Managing sessions](#managing-sessions)
-  - [Piping between sessions](#piping-between-sessions)
-  - [Output format](#output-format)
-    - [Human-readable (default)](#human-readable-default)
-    - [JSON mode](#json-mode)
-  - [Scripting](#scripting)
-    - [MCP server schema changes](#mcp-server-schema-changes)
-  - [Session failover](#session-failover)
-- [Logging](#logging)
-- [Cleanup](#cleanup)
+- [Authentication](#authentication)
+- [MCP proxy](#mcp-proxy)
+- [AI agents](#ai-agents)
+- [MCP support](#mcp-support)
 - [Configuration](#configuration)
-  - [MCP config JSON file](#mcp-config-json-file)
-  - [Environment variables](#environment-variables)
-- [MCP protocol notes](#mcp-protocol-notes)
 - [Security](#security)
-  - [Authentication](#authentication-1)
-  - [Credential storage](#credential-storage)
-  - [Bridge process authentication](#bridge-process-authentication)
-  - [File permissions](#file-permissions)
-  - [Network security](#network-security)
-- [Error handling](#error-handling)
-  - [Exit codes](#exit-codes)
-  - [Retry strategy](#retry-strategy)
-- [Interactive shell](#interactive-shell)
-- [Claude Code skill](#claude-code-skill)
-- [Troubleshooting](#troubleshooting)
-  - [Logs](#logs)
-  - [Common issues](#common-issues)
-- [Contributing](#contributing)
-- [Authors](#authors)
+- [Errors](#errors)
+- [Development](#development)
 - [License](#license)
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
@@ -87,6 +47,21 @@ Note that `mcpc` does not use LLMs on its own; that's a job for the higher layer
 npm install -g @apify/mcpc
 ```
 
+**Linux users:** `mcpc` uses the OS keychain for secure credential storage, which requires the [Libsecret](https://wiki.gnome.org/Projects/Libsecret) 
+library. Install it with:
+
+```bash
+# Debian/Ubuntu
+sudo apt-get update
+sudo apt-get install libsecret-1-0
+
+# Fedora/RHEL/CentOS
+sudo dnf install libsecret
+
+# Arch Linux
+sudo pacman -S libsecret
+```
+
 ## Quickstart
 
 ```bash
@@ -103,8 +78,8 @@ mcpc mcp.apify.com
 mcpc mcp.apify.com tools-list --json
 
 # Create and use persistent MCP session
-mcpc mcp.apify.com session @test
-mcpc @test tools-call search-actors --args keywords="web crawler"
+mcpc mcp.apify.com connect @test
+mcpc @test tools-call search-actors keywords:="website crawler"
 mcpc @test shell
 
 # Interact with a local MCP server package (stdio) referenced from config file
@@ -113,135 +88,327 @@ mcpc --config ~/.vscode/mcp.json filesystem tools-list
 
 ## Usage
 
-```bash
-Usage: mcpc [options] [target] [command]
+<!-- AUTO-GENERATED: mcpc --help -->
+
+```
+Usage: mcpc [options] <target> [command]
+
+Universal command-line client for the Model Context Protocol (MCP).
 
 Options:
-  -v, --version           Output the version number
-  -j, --json              Output in JSON format for scripting
-  --verbose               Enable verbose logging
-  -c, --config <file>     Path to MCP config JSON file (e.g. ".vscode/mcp.json")
-  -H, --header <header>   Add HTTP header (can be repeated)
-  --timeout <seconds>     Request timeout in seconds (default: 300)
-  --profile <name>        Authentication profile to use (default: "default")
-  --schema <file>         Validate against expected tool/prompt schema
-  --schema-mode <mode>    Schema validation mode: "strict", "compatible" (default), or "ignore"
-  --clean[=types]         Clean up mcpc data (types: "sessions,logs,profiles,all")
-  -h, --help              Display general help
+  -j, --json                    Output in JSON format for scripting
+  -c, --config <file>           Path to MCP config JSON file (e.g. ".vscode/mcp.json")
+  -H, --header <header>         HTTP header for remote MCP server (can be repeated)
+  -v, --version                 Output the version number
+  --verbose                     Enable debug logging
+  --profile <name>              OAuth profile for the server (default: "default")
+  --schema <file>               Validate tool/prompt schema against expected schema
+  --schema-mode <mode>          Schema validation mode: strict, compatible (default), ignore
+  --timeout <seconds>           Request timeout in seconds (default: 300)
+  --proxy <[host:]port>         Start proxy MCP server (with "connect" command)
+  --proxy-bearer-token <token>  Require bearer token for proxy server
+  --clean[=types]               Clean up mcpc data (types: sessions, logs, profiles, all)
+  -h, --help                    Display general help
 
 Targets:
-  <server-url>            Remote MCP server URL (e.g. "mcp.apify.com")
-  <config-entry>          Entry from MCP config file specified in --config (e.g. "fs")
-  @<session>              Named persistent session (e.g. "@apify")
+  @<session>             Named persistent session (e.g. "@apify")
+  <config-entry>         Entry in MCP config file specified by --config (e.g. "fs")
+  <server-url>           Remote MCP server URL (e.g. "mcp.apify.com")
+
+Management commands (<target> missing):
+  login                  Create OAuth profile with credentials to access remote server
+  logout                 Remove OAuth profile for remote server
+  connect @<session>     Connect to server and create named persistent session
+  restart @<session>     Kill and restart a session
+  close @<session>       Close a session
+
+MCP commands (<target> provided):
+  help                   Show server info ("help" can be omitted)
+  shell                  Open interactive shell
+  tools-list             Send "tools/list" MCP request...
+  tools-get <tool-name>
+  tools-call <tool-name> [<args-json> | arg1:=val1 arg2:=val2 ...]
+  prompts-list
+  prompts-get <prompt-name> [<args-json> | arg1:=val1 arg2:=val2 ...]
+  resources
+  resources-list
+  resources-read <uri>
+  resources-subscribe <uri>
+  resources-unsubscribe <uri>
+  resources-templates-list
+  logging-set-level <level>
+  ping
+
+```
 
-Commands:
-  help                    Show server info, instructions, and capabilities
-  shell                   Open interactive shell to run MCP commands)
-  login                   Create OAuth profile with credentials to access remote server
-  logout                  Remove OAuth profile
-  session @<session>      Create a named persistent session
-  restart @<session>      Kill and restart a session  
-  close @<session>        Close a session
+### Management commands
+
+When `<target>` is missing, `mcpc` provides general management commands.
+
+```bash
+# List all sessions and OAuth profiles (also in JSON mode)
+mcpc
+mcpc --json
+
+# Show command help or version
+mcpc --help
+mcpc --version
+
+# Clean expired sessions and old log files
+mcpc --clean
 ```
 
-where `<target>` can be one of (in this order of precedence):
+For additional management commands, see [OAuth profiles](#oauth-profiles) and [Cleanup](#cleanup).
+
+### Targets
 
-- **Named session** prefixed with `@` (e.g. `@apify`) - persisted connection via bridge process
-- **Named entry** in a config file, when used with `--config` (e.g. `filesystem`) - local or remote server
-- **Remote MCP endpoint** URL (e.g. `mcp.apify.com` or `https://mcp.apify.com`) - direct HTTP connection
+To connect to an MCP server, you need to specify a `<target>`, which can be one of (in order of precedence):
 
-For local MCP servers (stdio transport), use a config file to specify the command, arguments, and environment variables. See [Configuration](#configuration) below.
+- **Entry in a config file** (e.g. `--config .vscode/mcp.json filesystem`) - see [Config file](#mcp-server-config-file)
+- **Remote MCP server URL** (e.g. `https://mcp.apify.com`)
+- **Named session** (e.g. `@apify`) - see [Sessions](#sessions)
 
-`mcpc` automatically selects the transport protocol:
-- HTTP/HTTPS URLs use the MCP Streamable HTTP transport (current standard; HTTP with SSE is not supported)
-- Config file entries use the transport specified in the config (stdio for local servers, HTTP for remote)
+`mcpc` automatically selects the transport protocol based on the server (stdio or Streamable HTTP),
+connects, and enables you to interact with it.
 
-### MCP command arguments
+**URL handling:**
+- URLs without a scheme (e.g. `mcp.apify.com`) default to `https://`
+- `localhost` and `127.0.0.1` addresses without a scheme default to `http://` (for local dev/proxy servers)
+- To override the default, specify the scheme explicitly (e.g. `http://example.com`)
 
-`mcpc` supports multiple ways to pass arguments to `tools-call` and `prompts-get` commands:
+### MCP commands
+
+Examples of sending MCP commands to various targets:
 
 ```bash
-# Inline JSON object (most convenient)
-... --args '{"query":"hello","count":10}'
+# Server from config file (stdio)
+mcpc --config .vscode/mcp.json fileSystem
+mcpc --config .vscode/mcp.json fileSystem tools-list
+mcpc --config .vscode/mcp.json fileSystem tools-call list_directory path:=/
+
+# Remote server (Streamable HTTP)
+mcpc mcp.apify.com\?tools=docs
+mcpc mcp.apify.com\?tools=docs tools-list
+mcpc mcp.apify.com\?tools=docs tools-call search-apify-docs query:="What are Actors?"
+
+# Session
+mcpc mcp.apify.com\?tools=docs connect @apify
+mcpc @apify tools-list
+mcpc @apify tools-call search-apify-docs query:="What are Actors?"
+```
+
+See [MCP feature support](#mcp-feature-support) for details about all supported MCP features and commands.
 
-# String values (default) - use = for strings
-... --args name=value query="hello world"
+#### Command arguments
 
-# JSON literals - use := for JSON types
-... --args count:=123 enabled:=true value:=null
-... --args config:='{"key":"value"}' items:='[1,2,3]'
+The `tools-call` and `prompts-get` commands accept arguments as positional parameters after the tool/prompt name:
 
-# Mixed strings and JSON
-... --args query="search term" limit:=10 verbose:=true
+```bash
+# Key:=value pairs (auto-parsed: tries JSON, falls back to string)
+mcpc <target> tools-call <tool-name> greeting:="hello world" count:=10 enabled:=true
+mcpc <target> tools-call <tool-name> config:='{"key":"value"}' items:='[1,2,3]'
+
+# Force string type with JSON quotes
+mcpc <target> tools-call <tool-name> id:='"123"' flag:='"true"'
 
-# Load all arguments from JSON file
-... --args-file tool-arguments.json
+# Inline JSON object (if first arg starts with { or [)
+mcpc <target> tools-call <tool-name> '{"greeting":"hello world","count":10}'
 
-# Read from stdin (automatic when piped, no flag needed)
-echo '{"query":"hello","count":10}' | mcpc @server tools-call my-tool
+# Read from stdin (automatic when no positional args and input is piped)
+echo '{"greeting":"hello","count":10}' | mcpc <target> tools-call <tool-name>
+cat args.json | mcpc <target> tools-call <tool-name>
 ```
 
 **Rules:**
-- Use only one method: `--args` (inline JSON or key=value pairs), `--args-file`, or stdin (piped input)
-- Inline JSON: If first argument starts with `{` or `[`, it's parsed as JSON object/array
-- Key=value pairs: After `--args`, all `key=value` or `key:=json` pairs are consumed until next flag
-- `=` assigns as string, `:=` parses as JSON
-- Stdin is automatically detected when input is piped (not interactive terminal)
+- 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:
+```bash
+# Wrong - spaces around :=
+mcpc @server tools-call search query := "hello world"
+
+# Correct - no spaces around :=
+mcpc @server tools-call search "query:=hello world"
+```
+
+### Interactive shell
+
+`mcpc` provides an interactive shell for discovery and testing of MCP servers.
+
+```bash
+mcpc mcp.apify.com shell    # Direct connection
+mcpc @apify shell           # Use existing session
+```
+
+Shell commands: `help`, `exit`/`quit`/Ctrl+D, Ctrl+C to cancel.
+Arrow keys navigate history (saved to `~/.mcpc/history`).
+
+### JSON mode
+
+By default, `mcpc` prints output in Markdown-ish text format with colors, making it easy to read by both humans and AIs.
+
+With `--json` option, `mcpc` always emits only a single JSON object (or array), to enable [scripting](#scripting).
+**For all MCP commands, the returned objects are always consistent with the
+[MCP specification](https://modelcontextprotocol.io/specification/latest).**
+On success, the JSON object is printed to stdout, on error to stderr.
+
+Note that `--json` is not available for `shell`, `login`, and `mcpc --help` commands.
+
+## Sessions
+
+MCP is a [stateful protocol](https://modelcontextprotocol.io/specification/latest/basic/lifecycle):
+clients and servers negotiate protocol version and capabilities, and then communicate within a persistent session.
+To support these sessions, `mcpc` can start a lightweight **bridge process** that maintains the connection and state.
+This is more efficient than forcing every MCP command to reconnect and reinitialize,
+and enables long-term stateful sessions.
+
+The sessions are given names prefixed with `@` (e.g. `@apify`),
+which then serve as unique reference in commands.
+
+```bash
+# Create a persistent session
+mcpc mcp.apify.com\?tools=docs connect @apify
+
+# List all sessions and OAuth profiles
+mcpc
+
+# Run MCP commands in the session
+mcpc @apify tools-list
+mcpc @apify shell
+
+# Restart the session (kills and restarts the bridge process)
+mcpc @apify restart
+
+# Close the session, terminates bridge process
+mcpc @apify close
+
+# ...now session name "@apify" is forgotten and available for future use
+```
+
+### 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 states:**
+
+| State            | Meaning                                                                                       |
+|------------------|-----------------------------------------------------------------------------------------------|
+| 🟢 **`live`**    | Bridge process is running; server might or might not be operational                           |
+| 🟡 **`crashed`** | Bridge process crashed or was killed; will auto-restart on next use                           |
+| 🔴 **`expired`** | Server rejected the session (auth failed, session ID invalid); requires `close` and reconnect |
+
+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 bridge will keep trying to reconnect in the background.
+  - If **server negatively responds** to indicate `MCP-Session-Id` is no longer valid
+    or authentication permanently failed (HTTP 401 or 403),
+    the bridge process will flag the session as 🔴 **`expired`** and **terminate** to avoid wasting resources.
+    Any future attempt to use the session (`mcpc @my-session ...`) will fail.
+- If the **bridge process crashes**, `mcpc` will mark the session as 🟡 **`crashed`** on first use.
+  Next time you run `mcpc @my-session ...`, it will attempt to restart the bridge process.
+  - If bridge **restart succeeds**, everything starts again (see above).
+  - If bridge **restart fails**, `mcpc @my-session ...` returns error, and session remains marked 🟡 **`crashed`**.
+
+Note that `mcpc` never automatically removes sessions from the list.
+Instead, it keeps them flagged as 🟡 **`crashed`** or 🔴 **`expired`**,
+and any future attempts to use them will fail.
+
+To **remove the session from the list**, you need to explicitly close it:
+
+```bash
+mcpc @apify close
+```
+
+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
+```
+
 
 ## Authentication
 
-`mcpc` supports all standard [authentication methods](https://modelcontextprotocol.io/specification/latest/basic/authorization) for MCP servers,
-including the `WWW-Authenticate` discovery mechanism and OAuth 2.1 with PKCE.
+`mcpc` supports all standard [MCP authorization methods](https://modelcontextprotocol.io/specification/latest/basic/authorization).
 
-### No authentication
+### Anonymous access
 
 For local servers (stdio) or remote servers (Streamable HTTP) which do not require credentials,
 `mcpc` can be used without authentication:
 
 ```bash
-# Remote server which enables anonymous access
-mcpc https://mcp.apify.com\?tools=docs tools-list
+# One-shot command
+mcpc mcp.apify.com\?tools=docs tools-list
+
+# Session command
+mcpc mcp.apify.com\?tools=docs connect @test
+mcpc @test tools-list
 ```
 
 ### Bearer token authentication
 
-For remote servers that require a bearer token (but not OAuth), use the `--header` flag.
-All headers are stored securely in the OS keychain for the session, but **not** saved as a reusable authentication profile:
+For remote servers that require a Bearer token (but not OAuth), use the `--header` flag to pass the token.
+All headers are stored securely in the OS keychain for the session, but they are **not** saved as reusable
+[OAuth profiles](#oauth-profiles). This means `--header` needs to be provided whenever
+running a one-shot command or connecting new session.
 
 ```bash
-# One-time command with bearer token
+# One-time command with Bearer token
 mcpc --header "Authorization: Bearer ${APIFY_TOKEN}" https://mcp.apify.com tools-list
 
-# Create session with bearer token (saved to keychain for this session only)
-mcpc --header "Authorization: Bearer ${APIFY_TOKEN}" https://mcp.apify.com session @apify
+# Create session with Bearer token (saved to keychain for this session only)
+mcpc --header "Authorization: Bearer ${APIFY_TOKEN}" https://mcp.apify.com connect @apify
 
-# Use the session (token loaded from keychain automatically)
+# Use the session (Bearer token is loaded from keychain automatically)
 mcpc @apify tools-list
 ```
 
-### OAuth authentication
-
-For OAuth-enabled remote MCP servers, `mcpc` implements the full OAuth 2.1 flow with PKCE, including:
-- `WWW-Authenticate` header discovery
-- Authorization server metadata discovery (RFC 8414)
-- Client ID metadata documents (SEP-991)
-- Dynamic client registration (RFC 7591)
-- Automatic token refresh
+### OAuth profiles
 
-The OAuth authentication is **always** initiated by the user calling the `login` command,
-which opens a web browser with login screen. `mcpc` doesn't open web browser in any other case.
+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.
 
-`mcpc` uses OS keychain to securely store OAuth authentication tokens.
+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.
 
-#### Authentication profiles
-
-For OAuth-enabled servers, `mcpc` uses **authentication profiles** - reusable credentials that can be shared across multiple sessions.
-This allows you to:
-- Authenticate once, create multiple sessions
+The OAuth credentials to specific servers are securely stored as **authentication profiles** - reusable
+credentials that allow you to:
+- Authenticate once, use credentials across multiple commands or sessions
 - Use different accounts (profiles) with the same server
 - Manage credentials independently from sessions
 
-**Key concepts:**
+Key concepts:
 - **Authentication profile**: Named set of OAuth credentials for a specific server (stored in `~/.mcpc/profiles.json` + OS keychain)
 - **Session**: Active connection to a server that may reference an authentication profile (stored in `~/.mcpc/sessions.json`)
 - **Default profile**: When `--profile` is not specified, `mcpc` uses the authentication profile named `default`
@@ -250,20 +417,36 @@ This allows you to:
 
 ```bash
 # Login to server and save 'default' authentication profile for future use
-mcpc https://mcp.apify.com login
+mcpc mcp.apify.com login
 
 # Use named authentication profile instead of 'default'
-mcpc https://mcp.apify.com login --profile personal
+mcpc mcp.apify.com login --profile work
 
-# Re-authenticate existing profile (e.g., to refresh or change scopes)
-mcpc https://mcp.apify.com login --profile personal
+# Create two sessions using the two different credentials
+mcpc https://mcp.apify.com connect @apify-personal
+mcpc https://mcp.apify.com connect @apify-work --profile work
+
+# Both sessions now work independently
+mcpc @apify-personal tools-list  # Uses personal account
+mcpc @apify-work tools-list      # Uses work account
 
-# Delete an authentication profile
-mcpc https://mcp.apify.com logout --profile personal
+# Re-authenticate existing profile (e.g., to refresh or change scopes)
+mcpc mcp.apify.com login --profile work
 
+# Delete "default" and "work" authentication profiles
+mcpc mcp.apify.com logout
+mcpc mcp.apify.com logout --profile work
 ```
 
-#### Authentication behavior
+### 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
+
 
 `mcpc` automatically handles authentication based on whether you specify a profile:
 
@@ -283,9 +466,9 @@ mcpc https://mcp.apify.com logout --profile personal
    - 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 the users know what to do.
+On failure, the error message includes instructions on how to login and save the profile, so you know what to do.
 
-**This flow ensures:**
+This flow ensures:
 - You only authenticate when necessary
 - 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
@@ -294,258 +477,347 @@ On failure, the error message includes instructions on how to login and save the
 
 ```bash
 # With specific profile - always authenticated:
-# - Uses 'personal' if it exists
+# - Uses 'work' if it exists
 # - Fails if it doesn't exist
-mcpc https://mcp.apify.com session @apify1 --profile personal
+mcpc mcp.apify.com connect @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
-mcpc https://mcp.apify.com session @apify2
+mcpc mcp.apify.com connect @apify-personal
 
 # Public server - no authentication needed:
-mcpc https://mcp.apify.com\?tools=docs tools-list
+mcpc mcp.apify.com\?tools=docs tools-list
 ```
 
-#### Multiple accounts for the same server
 
-Authentication profiles enable using multiple accounts with the same MCP server:
+## MCP proxy
+
+For stronger isolation, `mcpc` can expose an MCP session under a new local proxy MCP server using the `--proxy` option.
+The proxy forwards all MCP requests to the upstream server but **never exposes the original authentication tokens** to the client.
+This is useful when you want to give someone or something MCP access without revealing your credentials.
+See also [AI sandboxes](#ai-sandboxes).
 
 ```bash
-# Authenticate with personal account
-mcpc https://mcp.apify.com login --profile personal
+# Human authenticates to a remote server
+mcpc mcp.apify.com login
 
-# Authenticate with work account
-mcpc https://mcp.apify.com login --profile work
+# Create authenticated session with proxy server on localhost:8080
+mcpc mcp.apify.com connect @open-relay --proxy 8080
 
-# Create sessions using the two different credentials
-mcpc https://mcp.apify.com session @apify-personal --profile personal
-mcpc https://mcp.apify.com session @apify-work --profile work
+# Now any MCP client can connect to proxy like to a regular MCP server
+# The client has NO access to the original OAuth tokens or HTTP headers
+# Note: localhost/127.0.0.1 URLs default to http:// (no scheme needed)
+mcpc localhost:8080 tools-list
+mcpc 127.0.0.1:8080 tools-call search-actors keywords:="web scraper"
 
-# Both sessions work independently
-mcpc @apify-personal tools-list  # Uses personal account
-mcpc @apify-work tools-list      # Uses work account
+# Or create a new session from the proxy for convenience
+mcpc localhost:8080 connect @sandboxed
+mcpc @sandboxed tools-call search-actors keywords:="web scraper"
+
+# Optionally protect proxy with bearer token for better security (stored in OS keychain)
+mcpc mcp.apify.com connect @secure-relay --proxy 8081 --proxy-bearer-token secret123
+# To use the proxy, caller needs to pass the bearer token in HTTP header
+mcpc localhost:8081 connect @sandboxed2 --header "Authorization: Bearer secret123"
 ```
 
-### Authentication precedence
+**Proxy options for `connect` command:**
 
-When multiple authentication methods are available, `mcpc` uses this precedence order:
+| Option                         | Description                                                                    |
+|--------------------------------|--------------------------------------------------------------------------------|
+| `--proxy [host:]port`          | Start proxy MCP server. Default host: `127.0.0.1` (localhost only)             |
+| `--proxy-bearer-token <token>` | Requires `Authorization: Bearer <token>` header to access the proxy MCP server |
 
-1. **Command-line `--header` flag** (highest priority) - Always used if provided
-2. **Session's stored credentials** - Bearer tokens or OAuth tokens from profile
-3. **Config file headers** - Headers from `--config` file for the server
-4. **No authentication** - Attempts unauthenticated connection
+**Security model:**
+
+- **Localhost by default**: `--proxy 8080` binds to `127.0.0.1` only, preventing network access
+- **Tokens hidden**: Original OAuth tokens and/or HTTP headers are never exposed to proxy clients
+- **Optional auth**: Use `--proxy-bearer-token` to add another layer of security
+- **Explicit opt-in**: Proxy only starts when `--proxy` flag is provided
+
+**Binding to network interfaces:**
 
-**Example:**
 ```bash
-# Config file has: "headers": {"Authorization": "Bearer ${TOKEN1}"}
-# Session uses profile with different OAuth token
-# Command provides: --header "Authorization: Bearer ${TOKEN2}"
-# Result: Uses TOKEN2 (command-line flag wins)
-```
+# Localhost only (default, most secure)
+mcpc mcp.apify.com connect @relay --proxy 8080
 
-### Authentication profiles storage format
+# Bind to all interfaces (allows network access - use with caution!)
+mcpc mcp.apify.com connect @relay --proxy 0.0.0.0:8080
 
-By default, authentication profiles are stored in the `~/.mcpc/profiles.json` file with the following structure:
+# Bind to specific interface
+mcpc mcp.apify.com connect @relay --proxy 192.168.1.100:8080
+```
 
-```json
-{
-  "profiles": {
-    "https://mcp.apify.com": {
-      "personal": {
-        "name": "personal",
-        "serverUrl": "https://mcp.apify.com",
-        "authType": "oauth",
-        "oauthIssuer": "https://auth.apify.com",
-        "scopes": ["tools:read", "tools:write", "resources:read"],
-        "createdAt": "2025-12-14T10:00:00Z",
-        "authenticatedAt": "2025-12-14T10:00:00Z"
-      },
-      "work": {
-        "name": "work",
-        "serverUrl": "https://mcp.apify.com",
-        "authType": "oauth",
-        "oauthIssuer": "https://auth.apify.com",
-        "scopes": ["tools:read"],
-        "createdAt": "2025-12-10T15:30:00Z",
-        "authenticatedAt": "2025-12-10T15:30:00Z"
-      }
-    }
-  }
-}
+When listing sessions, proxy info is displayed prominently:
+
+```bash
+mcpc
+# @relay → https://mcp.apify.com (HTTP, OAuth: default) [proxy: 127.0.0.1:8080]
 ```
 
-**OS Keychain entries:**
-- OAuth tokens: `mcpc:auth:https://mcp.apify.com:personal:tokens`
-- OAuth client info: `mcpc:auth:https://mcp.apify.com:personal:client`
-- HTTP headers (per-session): `mcpc:session:apify:headers`
 
-## Sessions
+## AI agents
 
-MCP is a [stateful protocol](https://modelcontextprotocol.io/specification/latest/basic/lifecycle): clients and servers perform an initialization handshake
-to negotiate protocol version and capabilities, then communicate within a persistent session.
-Each session maintains:
-- Negotiated protocol version and capabilities (which tools/resources/prompts/notifications are supported)
-- For Streamable HTTP transport: persistent connection with bidirectional streaming, with automatic reconnection
-- For stdio transport: persistent bidirectional pipe to subprocess
+`mcpc` is designed for CLI-enabled AI agents like Claude Code or Codex CLI, supporting both
+interactive **tool calling** and **[code mode](https://www.anthropic.com/engineering/code-execution-with-mcp)**.
 
-Instead of forcing every command to reconnect and reinitialize (which is slow and loses state),
-`mcpc` uses a lightweight **bridge process** per session that:
+**Tool calling mode** - Agents call `mcpc` commands to dynamically explore and interact with MCP servers,
+using the default text output. This is similar to how MCP connectors in ChatGPT or Claude work,
+but CLI gives you more flexibility and longer operation timeouts.
 
-- Maintains the MCP session (protocol version, capabilities, connection state)
-- For Streamable HTTP: Manages persistent connections with automatic reconnection and resumption
-- Multiplexes multiple concurrent requests (up to 10 concurrent, 100 queued)
-- Enables piping data between multiple MCP servers simultaneously
+```bash
+# Discover available tools
+mcpc @server tools-list
 
-`mcpc` saves its state to `~/.mcpc/` directory (unless overridden by `MCPC_HOME_DIR`), in the following files:
+# Get tool schema
+mcpc @server tools-get search
 
-- `~/.mcpc/sessions.json` - Active sessions with references to authentication profiles (file-locked for concurrent access)
-- `~/.mcpc/profiles.json` - Authentication profiles (OAuth metadata, scopes, expiry)
-- `~/.mcpc/bridges/` - Unix domain socket files for each bridge process
-- `~/.mcpc/logs/bridge-*.log` - Log files for each bridge process
-- OS keychain - Sensitive credentials (OAuth tokens, bearer tokens, client secrets)
+# Call a tool
+mcpc @server tools-call search query:="hello world"
+```
 
-### Managing sessions
+**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
-# Create a persistent session (with default authentication profile, if available)
-mcpc https://mcp.apify.com session @apify
-
-# Create session with specific authentication profile
-mcpc https://mcp.apify.com session @apify --profile personal
+# 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:="{}"
+```
 
-# List all active sessions and saved authentication profiles
-mcpc
+With [schema validation](#schema-validation), agents can ensure stability of integrations and faster failure recovery.
+Agents, make no harm!
 
-# Active sessions:
-#   @apify → https://mcp.apify.com (http, profile: personal)
-#
-# Saved authentication profiles:
-#   https://mcp.apify.com
-#     • personal (authenticated: 2 days ago)
-#     • work (authenticated: 1 week ago)
+See an [example](./docs/examples/company-lookup.sh) of an AI-generated shell script.
 
-# Use the session
-mcpc @apify tools-list
-mcpc @apify shell
+### Scripting
 
-# Restart the session (kills and restarts the bridge process)
-mcpc @apify restart
+Use `--json` for machine-readable output (stdout on success, stderr on error).
+JSON output of all MCP commands follows the [MCP specification](https://modelcontextprotocol.io/specification/latest) strictly.
 
-# Close the session (terminates bridge process, but keeps authentication profile)
-mcpc @apify close
+```bash
+# Chain tools across sessions
+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:="{}"
+
+# Batch operations
+for tool in $(mcpc --json @server tools-list | jq -r '.[].name'); do
+  mcpc --json @server tools-get "$tool" > "schemas/$tool.json"
+done
 ```
 
-### Piping between sessions
+For a complete example script, see [`docs/examples/company-lookup.sh`](./docs/examples/company-lookup.sh).
+
+### Schema validation
+
+Validate tool/prompt schemas using the `--schema` option to detect breaking changes early:
 
 ```bash
-mcpc --json @apify tools-call search-actors --args query="tiktok scraper" \
-  | jq '.data.results[0]' \
-  | mcpc @playwright tools-call run-browser
+# Save expected schema
+mcpc --json @apify tools-get search-actors > expected.json
+
+# Validate before calling (fails if schema changed incompatibly)
+mcpc @apify tools-call search-actors --schema expected.json keywords:="test"
 ```
 
-### Output format
+Available schema validation modes (`--schema-mode`):
+- `compatible` (default)
+  - Input schema: new optional fields OK, required fields must have the same type.
+  - Output schema: new fields OK, removed required fields cause error.
+- `strict` - Both input and output schemas must match exactly, including all fields, types, and descriptions
+- `ignore` - Skip validation completely (YOLO)
 
-#### Human-readable (default)
+### AI sandboxes
 
-Default output is formatted for human and AI readability with plain text, colors, and Markdown-like formatting.
-The text is formatted in Markdown-compatible format for AIs with colors for easy human readability.
+To ensure AI coding agents don't perform destructive actions or leak credentials,
+it's always a good idea to run them in a code sandbox with limited access to your resources.
 
-#### JSON mode
+The [proxy MCP server](#mcp-proxy) feature provides a security boundary for AI agents:
 
-If `--json` option is provided, `mcpc` always emits only a single JSON object, in order to enable scripting.
-For MCP commands, the returned objects are always consistent with the [MCP protocol specification](https://modelcontextprotocol.io/specification/latest).
-On success, the JSON object is printed to stdout, otherwise to stderr.
+1. **Human creates authentication profile**: `mcpc mcp.apify.com login --profile ai-access`
+2. **Human creates session**: `mcpc mcp.apify.com connect @ai-sandbox --profile ai-access --proxy 8080`
+3. **AI runs inside a sandbox**: If sandbox has access limited to `localhost:8080`,
+   it can only interact with the MCP server through the `@ai-sandbox` session,
+   without access to the original OAuth credentials, HTTP headers, or `mcpc` configuration.
 
-### Scripting
+This ensures AI agents operate only with pre-authorized credentials, preventing unauthorized access to MCP servers.
+The human controls which servers the AI can access and with what permissions (OAuth scopes).
+
+**IMPORTANT:** Beware that MCP proxy will not make an insecure MCP server secure.
+Local stdio servers will still have access to your local system, and HTTP servers to provided auth credentials,
+and both can easily perform destructive actions or leak credentials on their own, or let MCP clients do such actions.
+**Always use only trusted local and remote MCP servers and limit their access to the necessary minimum.**
+
+### Agent skills
+
+To help Claude Code use `mcpc`, you can install this [Claude skill](./docs/claude-skill/README.md):
+
+<!-- TODO: Add also AGENTS.md, GitHub skills etc. -->
 
-`mcpc` is designed for us in (AI-generated) scripts.
-With the `--json` option, `mcpc` returns a single JSON object (object or array) as follows:
+## MCP support
 
-- On success, the JSON object is printed to stdout
-- On error, the JSON object is printed to stderr
+`mcpc` is built on the official [MCP SDK for TypeScript](https://github.com/modelcontextprotocol/typescript-sdk) and supports most [MCP protocol features](https://modelcontextprotocol.io/specification/latest).
 
-You can use tools like `jq` to process the output.
+### Transport
 
-Note that `--json` option has no effect on `--help` command,
-or if there are invalid arguments, as those take precedence.
+- **stdio**: Direct bidirectional JSON-RPC communication over
+  stdio server from the [config file](#mcp-server-config-file).
+- **Streamable HTTP**: Fully supported.
+- **HTTP with SSE** (deprecated): Legacy mode, not supported.
 
-For all MCP operations, the **returned JSON is and always will be strictly consistent
-with the [MCP specification](https://modelcontextprotocol.io/specification/latest)**,
-based to the protocol version negotiated between client and server in the initial handshake.
+### Authorization
 
-Additionally, one of the core [design principles](CONTRIBUTING.md#design-principles) of `mcpc` 
-is to keep backwards compatibility to maximum extent possible, to ensure the scripts using `mcpc`
-will not break over time.
+- [Anonymous access](#anonymous-access)
+- [HTTP header authorization](#bearer-token-authentication)
+- [OAuth 2.1](#oauth-profiles)
 
-#### MCP server schema changes
+### MCP session
 
-MCP is a fluid protocol, and MCP servers can change operations and their schema at any time. 
-To ensure your scripts fail fast whenever such schema change occurs, rather than fail silently later,
-you can use the `--schema <file>` option to pass `mcpc` the expected operation schema.
-If the MCP server's current schema is incompatible, the command returns an error.
+The bridge process manages the full MCP session lifecycle:
+- Performs initialization handshake (`initialize` → `initialized`)
+- Negotiates protocol version and capabilities
+- Fetches server-provided `instructions`
+- Maintains persistent HTTP connections with bidirectional streaming, or stdio bidirectional pipe to subprocess
+- Handles `MCP-Protocol-Version` and `MCP-Session-Id` headers automatically
+- Handles multiple concurrent requests
+- Recovers transparently from network disconnections and bridge process crashes
+
+### 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**                                  | 🚧 Planned                         |
+| 📁 **Roots**                                       | 🚧 Planned                         |
+| ❓ **Elicitation**                                  | 🚧 Planned                         |
+| 🔤 **Completion**                                  | 🚧 Planned                         |
+| 🤖 **Sampling**                                    | ❌ Not applicable (no LLM access)   |
+
+#### Server instructions
+
+MCP servers can provide instructions describing their capabilities and usage. These are displayed when you connect to a server or run the `help` command:
 
 ```bash
-# Save tool schema for future validation
-mcpc --json @apify tools-get search-actors > search-actors-schema.json
+# Show server info, capabilities, and instructions (both commands behave the same)
+mcpc @apify
+mcpc @apify help
 
-# Use schema to ensure compatibility (fails if schema changed)
-mcpc @apify tools-call search-actors \
-  --schema search-actors-schema.json \
-  --schema-mode strict \
-  --args keywords="tiktok scraper"
+# JSON mode
+mcpc @apify --json
+```
+
+In [JSON mode](#json-mode), the resulting object adheres
+to [`InitializeResult`](https://modelcontextprotocol.io/specification/latest/schema#initializeresult) object schema,
+and includes the `_mcpc` field with relevant server/session metadata.
+
+```json
+{
+  "_mcpc": {
+    "sessionName": "@apify",
+    "profileName": "default",
+    "server": {
+      "url": "https://mcp.apify.com"
+    },
+    "notifications": {
+      "tools": { "listChangedAt": "2026-01-01T00:42:58.049Z" }
+    }
+  },
+  "protocolVersion": "2025-06-18",
+  "capabilities": {
+    "logging": {},
+    "prompts": {},
+    "resources": {},
+    "tools": { "listChanged": true }
+  },
+  "serverInfo": {
+    "name": "apify-mcp-server",
+    "version": "1.0.0"
+  },
+  "instructions": "Apify is the largest marketplace of tools for web scraping..."
+}
 ```
 
-The `--schema-mode <mode>` parameter determines how `mcpc` validates the schema:
+#### Tools
 
-- `compatible` (default) - Backwards compatible (new optional fields OK, types of required 
-  fields and passed arguments must match, descriptions are ignored). For tools, the output schema
-  is ignored.
-- `strict` - Exact schema match required (all fields, their types and descriptions must be 
-  identical). For tools, the output schema must match exactly.
-- `ignore` - Skip schema validation altogether
+List, inspect, and call server-provided tools:
 
-### Session failover
+```bash
+# List available tools
+mcpc @apify tools-list
 
-`mcpc` bridge process attempts to keep sessions alive by sending periodic ping messages to the MCP server.
-But even then, the session can fail for a number of reasons:
+# Get tool schema details
+mcpc @apify tools-get search-actors
 
-- Network disconnects
-- Server drops the session for inactivity or other reasons
-- Bridge process crashes
+# Call a tool with arguments
+mcpc @apify tools-call search-actors keywords:="web scraper"
 
-Here's how `mcpc` handles these situations:
+# Pass complex JSON arguments
+mcpc @apify tools-call create-task '{"name": "my-task", "options": {"memory": 1024}}'
+
+# Load arguments from stdin
+cat data.json | mcpc @apify tools-call bulk-import
+```
 
-- If the bridge process is running, it will automatically try to reconnect to the server if the connection fails
-and establish the keep-alive pings.
-- If the server response indicates the `MCP-Session-Id` is no longer valid or authentication permanently failed (HTTP error 401 or 402),
-the bridge process will flag the session as **expired** in `~/.mcpc/sessions.json` and terminate.
-- If the bridge process crashes, `mcpc` attempts to restart it next time you use the specific session.
+#### Prompts
 
-Note that `mcpc` never automatically removes sessions from the list, but rather flags the session as **expired**,
-and any attempts to use it will fail.
-To remove the session from the list, you need to explicitly close it:
+List and retrieve server-defined prompt templates:
 
 ```bash
-mcpc @apify close
+# List available prompts
+mcpc @apify prompts-list
+
+# Get a prompt with arguments
+mcpc @apify prompts-get analyze-website url:=https://example.com
 ```
 
-or reconnect it using the `session` command (if the session exists but bridge is dead, it will be automatically reconnected):
+<!-- TODO: Add example of prompt templates -->
+
+#### Resources
+
+Access server-provided data sources by URI:
 
 ```bash
-mcpc https://mcp.apify.com session @apify
+# List available resources
+mcpc @apify resources-list
+
+# Read a resource
+mcpc @apify resources-read "file:///config.json"
+
+# Subscribe to resource changes (in shell mode)
+mcpc @apify resources-subscribe "https://api.example.com/data"
+
+# List resource templates
+mcpc @apify resources-templates-list
 ```
 
-## Logging
+#### List change notifications
+
+When connected via a [session](#sessions), `mcpc` automatically handles `list_changed`
+notifications for tools, resources, and prompts.
+The bridge process tracks when each notification type was last received.
+In [shell mode](#interactive-shell), notifications are displayed in real-time.
+The timestamps are available in JSON output of `mcpc <target> --json` under the `_mcpc.notifications`
+field - see [Server instructions](#server-instructions).
 
-TODO: Move this to MPC features section
+#### Server logs
 
-The background bridge process logs to `~/.mcpc/logs/bridge-<session-name>.log`.
-The main `mcpc` process doesn't save log files, but you can use `--verbose` flag to print all logs to stderr.
+`mcpc` supports server logging settings (`logging/setLevel`) and log messages (`notifications/message`).
+Log messages are printed to bridge log or stderr, subject to [verbosity level](#verbose-mode).
 
-MCP servers can be instructed to adjust their [logging level](https://modelcontextprotocol.io/specification/latest/server/utilities/logging)
-using the `logging/setLevel` command:
+You can instruct MCP servers to adjust their [logging level](https://modelcontextprotocol.io/specification/latest/server/utilities/logging)
+using the `logging-set-level` command:
 
 ```bash
 # Set server log level to debug for detailed output
@@ -555,47 +827,37 @@ mcpc @apify logging-set-level debug
 mcpc @apify logging-set-level error
 ```
 
-**Available log levels** (from most to least verbose):
-- `debug` - Detailed debugging information
-- `info` - General informational messages
-- `notice` - Normal but significant events
-- `warning` - Warning messages
-- `error` - Error messages
-- `critical` - Critical conditions
-- `alert` - Action must be taken immediately
-- `emergency` - System is unusable
+Note that this sets the logging level on the **server side**.
+The actual log output depends on the server's implementation.
 
-**Note:** This sets the logging level on the **server side**. The actual log output depends on the server's implementation.
+#### Pagination
 
+MCP servers may return paginated results for list operations
+(`tools-list`, `resources-list`, `prompts-list`, `resources-templates-list`).
+`mcpc` handles this automatically and always fetches all available pages using the `nextCursor`
+token - you always get the complete list without manual iteration. Keep it simple.
 
-## Cleanup
+#### Ping
 
-You can clean up the `mcpc` state and data using the `--clean` option:
+Sessions automatically send periodic pings to keep the [connection alive](#session-lifecycle) and detect failures early.
+Send a ping to check if a server connection is alive:
 
 ```bash
-# Safe non-destructive cleanup: remove expired sessions, delete old orphaned logs
-mcpc --clean
-
-# Clean specific resources (comma-separated)
-mcpc --clean=sessions      # Kill bridges, delete all sessions
-mcpc --clean=profiles      # Delete all authentication profiles
-mcpc --clean=logs          # Delete all log files
-mcpc --clean=sessions,logs # Clean multiple resource types
-
-# Nuclear option: remove everything
-mcpc --clean=all           # Delete all sessions, profiles, logs, and sockets
+# Ping a session and measure round-trip time
+mcpc @apify ping
+mcpc @apify ping --json
 ```
 
 ## Configuration
 
-Configuration can be provided via file, environment variables, or command-line flags.
+You can configure `mcpc` using a config file, environment variables, or command-line flags.
 
 **Precedence** (highest to lowest):
 1. Command-line flags (including `--config` option)
 2. Environment variables
 3. Built-in defaults
 
-### MCP config JSON file
+### MCP server config file
 
 `mcpc` supports the ["standard"](https://gofastmcp.com/integrations/mcp-json-configuration)
 MCP server JSON config file, compatible with Claude Desktop, VS Code, and other MCP clients.
@@ -606,7 +868,7 @@ You can point to an existing config file with `--config`:
 mcpc --config .vscode/mcp.json apify tools-list
 
 # Open a session to a server specified in the custom config file
-mcpc --config .vscode/mcp.json apify session @my-apify
+mcpc --config .vscode/mcp.json apify connect @my-apify
 ```
 
 **Example MCP config JSON file:**
@@ -637,7 +899,7 @@ mcpc --config .vscode/mcp.json apify session @my-apify
 
 **Server configuration properties:**
 
-For **HTTP/HTTPS servers:**
+For **Streamable HTTP servers:**
 - `url` (required) - MCP server endpoint URL
 - `headers` (optional) - HTTP headers to include with requests
 - `timeout` (optional) - Request timeout in seconds
@@ -653,10 +915,10 @@ When `--config` is provided, you can reference servers by name:
 
 ```bash
 # With config file, use server names directly
-mcpc --config .vscode/mcp.json filesystem resources-list
+mcpc --config .vscode/mcp.json filesystem tools-list
 
 # Create a named session from server in config
-mcpc --config .vscode/mcp.json filesystem session @fs
+mcpc --config .vscode/mcp.json filesystem connect @fs
 mcpc @fs tools-call search
 ```
 
@@ -678,120 +940,71 @@ Config files support environment variable substitution using `${VAR_NAME}` synta
 }
 ```
 
+### Saved state
+
+`mcpc` saves its state to `~/.mcpc/` directory (unless overridden by `MCPC_HOME_DIR`), in the following files:
+
+- `~/.mcpc/sessions.json` - Active sessions with references to authentication profiles (file-locked for concurrent access)
+- `~/.mcpc/profiles.json` - Authentication profiles (OAuth metadata, scopes, expiry)
+- `~/.mcpc/bridges/` - Unix domain socket files for each bridge process
+- `~/.mcpc/logs/bridge-*.log` - Log files for each bridge process
+- OS keychain - Sensitive credentials (OAuth tokens, bearer tokens, client secrets)
+
 ### Environment variables
 
 - `MCPC_HOME_DIR` - Directory for session and authentication profiles data (default is `~/.mcpc`)
 - `MCPC_VERBOSE` - Enable verbose logging (set to `1`, `true`, or `yes`, case-insensitive)
 - `MCPC_JSON` - Enable JSON output (set to `1`, `true`, or `yes`, case-insensitive)
 
-## MCP protocol notes
-
-TODO: explain in detail how MCP concepts work in mcpc
-
-**Protocol initialization:**
-- `mcpc` follows the MCP initialization handshake: sends `initialize` request with protocol version and capabilities, receives server capabilities and instructions, then sends `initialized` notification
-- Protocol version negotiation: client proposes latest supported version (currently `2025-11-25`), server responds with version to use
-
-**Transport handling:**
-- **Streamable HTTP**: `mcpc` supports only the Streamable HTTP transport (the current standard). The deprecated HTTP with SSE transport is not supported. The bridge manages persistent HTTP connections with bidirectional streaming for server-to-client communication, with automatic reconnection using exponential backoff (1s → 30s max)
-  - Includes `MCP-Protocol-Version` header on all HTTP requests (per MCP spec)
-  - Handles `MCP-Session-Id` for stateful server sessions
-- During reconnection, new requests are queued (fails after 3 minutes of disconnection)
-- **Stdio**: Direct bidirectional JSON-RPC communication over standard input/output
-
-**Protocol features:**
-- `mcpc` supports all MCP primitives in both Streamable HTTP and stdio transports:
-  - **Instructions**: Fetches and stores MCP server-provided `instructions`
-  - **Tools**: Executable functions with JSON Schema-validated arguments. 
-  - **Resources**: Data sources identified by URIs (e.g., `file:///path/to/file`, `https://example.com/data`), with optional subscriptions for change notifications
-  - **Prompts**: Reusable message templates with customizable arguments
-  - **Completion**: Provides access to Completion API for tools and resources
-  - **Asynchronous tasks**: Not implemented yet
-  - **Roots**: Not implemented yet
-- Supports server logging settings (`logging/setLevel`) and messages (`notifications/message`), and prints them to stderr or stdout based on verbosity level.
-- Handles server notifications: progress tracking, logging, and change notifications (`notifications/tools/list_changed`, `notifications/resources/list_changed`, `notifications/prompts/list_changed`)
-- Request multiplexing: supports up to 10 concurrent requests, queues up to 100 additional requests
-- Pagination: List operations automatically fetch all pages when the server returns paginated results
-- Pings: `mcpc` periodically issues the MCP `ping` request to keep the connection alive
-- Sampling is not supported as `mcpc` has no access to an LLM
-
-## Security
+### Cleanup
 
-`mcpc` implements the [MCP security best practices](https://modelcontextprotocol.io/specification/2025-11-25/basic/security_best_practices) specification. MCP enables arbitrary tool execution and data access; treat servers like you treat shells:
-
-* Use least-privilege tokens/headers
-* Prefer trusted endpoints
-* Audit what tools do before running them
-* Review server permissions in interactive mode
-
-### Authentication
-
-**OAuth 2.1 with PKCE:**
-- Full OAuth 2.1 flow with PKCE (Proof Key for Code Exchange) via the MCP SDK
-- OAuth callback server binds to `127.0.0.1` only (not `0.0.0.0`)
-- Warning displayed for OAuth over plain HTTP (except localhost)
-- Dynamic client registration supported
-
-**Input validation:**
-- Session names validated: `^@[a-zA-Z0-9_-]{1,64}$`
-- Profile names validated: `^[a-zA-Z0-9_-]{1,64}$`
-- URLs normalized and validated (HTTPS enforced, credentials stripped)
+You can clean up the `mcpc` state and data using the `--clean` option:
 
-### Credential storage
+```bash
+# Safe non-destructive cleanup: remove expired sessions, delete old orphaned logs
+mcpc --clean
 
-**OS keychain integration:**
-- OAuth refresh tokens are stored in the OS keychain (access tokens are kept in memory only)
-- OAuth client credentials (client_id, client_secret from dynamic registration) are stored in the keychain
-- All HTTP headers from `--header` flags are stored per-session in the keychain (as JSON)
-- The `~/.mcpc/profiles.json` file only contains metadata (server URL, scopes, timestamps) - never tokens
+# Clean specific resources (comma-separated)
+mcpc --clean=sessions      # Kill bridges, delete all sessions
+mcpc --clean=profiles      # Delete all authentication profiles
+mcpc --clean=logs          # Delete all log files
+mcpc --clean=sessions,logs # Clean multiple resource types
 
-**Keychain entries:**
-- OAuth tokens: `mcpc:auth-profile:<host>:<profileName>:tokens`
-- OAuth client: `mcpc:auth-profile:<host>:<profileName>:client`
-- HTTP headers: `mcpc:session:<sessionName>:headers`
+# Nuclear option: remove everything
+mcpc --clean=all           # Delete all sessions, profiles, logs, and sockets
+```
 
-### Bridge process authentication
+## Security
 
-Background bridge processes need access to credentials for making authenticated requests. To maintain security while allowing token refresh:
+`mcpc` follows [MCP security best practices](https://modelcontextprotocol.io/specification/latest/basic/security_best_practices).
+MCP enables arbitrary tool execution and data access - treat servers like you treat shells:
 
-**For OAuth profiles:**
-1. **CLI retrieves refresh token** from OS keychain when creating or restarting a session
-2. **CLI sends refresh token to bridge** via Unix socket IPC (not command line arguments)
-3. **Bridge stores refresh token in memory only** - never written to disk
-4. **Bridge refreshes access tokens** periodically using the refresh token
-5. **Access tokens are kept in bridge memory** - never persisted to disk
+- Use least-privilege tokens/headers
+- Only use trusted servers!
+- Audit tools before running them
 
-**For HTTP headers (from `--header` flags):**
-1. **All headers are treated as potentially sensitive** - not just `Authorization`
-2. **CLI stores all headers in OS keychain** per-session (as JSON)
-3. **CLI sends headers to bridge** via Unix socket IPC (not command line arguments)
-4. **Bridge stores headers in memory only** - never written to disk
-5. **Headers are deleted from keychain** when session is closed
-6. **On bridge crash/restart**, CLI retrieves headers from keychain and resends via IPC
+### Credential protection
 
-This architecture ensures:
-- Credentials are never stored in plaintext on disk
-- Headers are not visible in process arguments (`ps aux`)
-- Bridge processes don't need direct keychain access (which may require user interaction)
-- Credentials are securely transmitted via Unix socket (local IPC only)
-- Failover works correctly - headers are preserved across bridge restarts
+| What                   | How                                             |
+|------------------------|-------------------------------------------------|
+| **OAuth tokens**       | Stored in OS keychain, never on disk            |
+| **HTTP headers**       | Stored in OS keychain per-session               |
+| **Bridge credentials** | Passed via Unix socket IPC, kept in memory only |
+| **Process arguments**  | No secrets visible in `ps aux`                  |
+| **Config files**       | Contain only metadata, never tokens             |
+| **File permissions**   | `0600` (user-only) for all config files         |
 
-### File permissions
+### Network security
 
-- `~/.mcpc/sessions.json` is created with `0600` permissions (user-only read/write)
-- `~/.mcpc/profiles.json` is created with `0600` permissions (user-only read/write)
-- Bridge sockets in `~/.mcpc/bridges/` use default umask (typically user-only)
-- File locking via `proper-lockfile` prevents race conditions on concurrent access
+- HTTPS enforced for remote servers (auto-upgraded from HTTP)
+- OAuth callback binds to `127.0.0.1` only
+- Credentials never logged, even in verbose mode
 
-### Network security
+### AI security
 
-- HTTPS enforced for remote servers (HTTP auto-upgraded when no scheme provided)
-- URL normalization removes username, password, and hash from URLs
-- Local OAuth callback server binds to `127.0.0.1` only
-- No credentials logged even in verbose mode
-- `MCP-Protocol-Version` and `MCP-Session-Id` headers handled per MCP spec
+See [AI sandboxes](#ai-sandboxes) for details.
 
-## Error handling
+## Errors
 
 `mcpc` provides clear error messages for common issues:
 
@@ -801,8 +1014,6 @@ This architecture ensures:
 - **Tool execution errors**: Returns server error messages with context
 - **Bridge crashes**: Detects and cleans up orphaned processes, offers restart
 
-Use `--verbose` to print detailed debugging information to stderr (includes JSON-RPC messages, streaming events, and protocol negotiation).
-
 ### Exit codes
 
 - `0` - Success
@@ -811,88 +1022,23 @@ Use `--verbose` to print detailed debugging information to stderr (includes JSON
 - `3` - Network error (connection failed, timeout, etc.)
 - `4` - Authentication error (invalid credentials, forbidden, etc.)
 
-### Retry strategy
-
-- **Network errors**: Automatic retry with exponential backoff (3 attempts)
-- **Stream reconnection**: Starts at 1s, doubles to max 30s
-- **Bridge restart**: Automatic on crash detection (recreates session on next command)
-- **Timeouts**: Configurable per-request timeout (default: 5 minutes)
+### Verbose mode
 
-## Interactive shell
-
-The interactive shell provides a REPL-style interface for MCP servers:
-
-```bash
-mcpc @apify shell
-```
-
-**Features:**
-- Command history with arrow key navigation (saved to `~/.mcpc/history`, last 1000 commands)
-- Real-time server notifications displayed during session
-- Prompt shows session name: `mcpc(@apify)> `
-
-**Shell-specific commands:**
-- `help` - Show available commands
-- `exit` or `quit` or Ctrl+D - Exit shell
-- Ctrl+C - Cancel current operation
-
-**Example session:**
-```
-$ mcpc @apify shell
-Connected to apify (https://mcp.apify.com)
-MCP version: 2025-11-25
-
-mcpc(@apify)> tools-list
-Available tools:
-  - search-actors
-  - get-actor
-  - run-actor
-
-mcpc(@apify)> tools-call search-actors --args query="tiktok scraper"
-[results...]
-
-mcpc(@apify)> exit
-```
-
-## Claude Code skill
-
-For AI coding agents using [Claude Code](https://claude.ai/code), we provide a skill that teaches Claude how to use mcpc effectively.
-
-**Installation:**
-```bash
-mkdir -p ~/.claude/skills/mcpc
-cp claude-skill/SKILL.md ~/.claude/skills/mcpc/
-```
-
-Then restart Claude Code. The skill enables Claude to interact with MCP servers via mcpc commands instead of function calling, which is more efficient and uses fewer tokens.
-
-See [`claude-skill/README.md`](./claude-skill/README.md) for details.
-
-
-## Troubleshooting
-
-To see what's happening, enable detailed logging with `--verbose`:
+To see what's happening, enable detailed logging with `--verbose`.
 
 ```bash
 mcpc --verbose @apify tools-list
 ```
 
-This shows:
-- Protocol negotiation details
-- JSON-RPC request/response messages
-- Streaming events and reconnection attempts
-- Bridge communication (socket messages)
-- File locking operations
-- Prints server log messages with severity `debug`, `info`, and `notice` to standard output
+This causes `mcpc` to print detailed debug messages to stderr.
 
 ### Logs
 
-Bridge processes log to:
-- `~/.mcpc/logs/bridge-<session-name>.log`
-
-Log rotation: Keep last 10MB per session, max 5 files.
+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.
 
-### Common issues
+### Troubleshooting
 
 **"Cannot connect to bridge"**
 - Bridge may have crashed. Try: `mcpc @<session-name> tools-list` to restart the bridge
@@ -901,7 +1047,7 @@ Log rotation: Keep last 10MB per session, max 5 files.
 
 **"Session not found"**
 - List existing sessions: `mcpc`
-- Create new session if expired: `mcpc @<session-name> close` and `mcpc <target> session @<session-name>`
+- Create new session if expired: `mcpc @<session-name> close` and `mcpc <target> connect @<session-name>`
 
 **"Authentication failed"**
 - List saved OAuth profiles: `mcpc`
@@ -909,13 +1055,12 @@ Log rotation: Keep last 10MB per session, max 5 files.
 - For bearer tokens: provide `--header "Authorization: Bearer ${TOKEN}"` again
 
 
-## Contributing
-
-See [CONTRIBUTING.md](./CONTRIBUTING.md) for development setup, architecture overview, and contribution guidelines.
+## Development
 
-## Authors
+The initial version of `mcpc` was developed by [Jan Curn](https://x.com/jancurn) of [Apify](https://apify.com)
+with the help of Claude Code, during late nights over Christmas 2025 in North Beach, San Francisco.
 
-Built by [Jan Curn](https://x.com/jancurn) / [Apify](https://apify.com).
+See [CONTRIBUTING](./CONTRIBUTING.md) for development setup, architecture overview, and contribution guidelines.
 
 ## License