@webhooks-cc/mcp 1.14.0 → 1.15.0

package/README.md

@@ -2,12 +2,14 @@
 
 MCP server for [webhooks.cc](https://webhooks.cc). It gives coding agents direct access to webhook testing workflows: create endpoints, send signed test webhooks, inspect captures, compare attempts, verify signatures, and read recent webhook context through MCP resources.
 
-It works with Claude Code, Cursor, VS Code, Codex, Windsurf, and Claude Desktop.
+It works with Claude Code, Cursor, VS Code, Codex, Windsurf, and Claude Desktop. Hosted agents such as claude.ai and ChatGPT use the [remote server](#remote-server) at `https://webhooks.cc/mcp` instead.
 
 ## Install
 
-The server reads `WHK_API_KEY` from the environment. It also supports:
+No API key is needed. Without one, the server starts with the full tools for the account a human connected the agent to before, or else in the keyless [agent sandbox](#without-an-api-key-the-agent-sandbox). It reads:
 
+- `WHK_API_KEY` (optional) for an API key, which always wins over a saved connection
+- `WHK_AGENT_FILE` for where the sandbox and the connection are saved (default `~/.config/whk/agent.json`, see [the agent credential file](#the-agent-credential-file))
 - `WHK_BASE_URL` for a custom API base URL
 - `WHK_WEBHOOK_URL` for a custom receiver base URL
 
@@ -21,33 +23,45 @@ The plugin installs the server together with a webhook testing skill that tells
 
 For other agents, `npx skills add kroqdotdev/webhooks-cc` installs the same skill. See [Agent skill](https://webhooks.cc/docs/mcp/skills).
 
+### Remote server
+
+`https://webhooks.cc/mcp` serves the same tools over streamable HTTP, with nothing to install. The client opens webhooks.cc in the browser once; the human signs in and clicks Connect (OAuth 2.1 with PKCE, no code to type), and can disconnect it later under Account, Connected agents.
+
+- **claude.ai and Claude Desktop**: Settings, Connectors, add a custom connector with the URL `https://webhooks.cc/mcp`
+- **ChatGPT**: add it as a custom connector (developer mode)
+- **Claude Code**: `claude mcp add --transport http webhooks-cc https://webhooks.cc/mcp`
+- **Cursor** (`.cursor/mcp.json`): `{ "mcpServers": { "webhooks-cc": { "url": "https://webhooks.cc/mcp" } } }`
+- **VS Code** (`.vscode/mcp.json`): `{ "servers": { "webhooks-cc": { "type": "http", "url": "https://webhooks.cc/mcp" } } }`
+
+A client that can send headers may use an API key instead: `Authorization: Bearer whcc_...`. The remote server has 44 tools: `send_to` and `replay_request` are left out and `targetUrl` is refused, because a hosted server cannot reach your machine, and waits are capped at 50 seconds. It needs an account (no sandbox), and serves tools only, without prompts or resources.
+
 ### One-click
 
 - **Cursor**: [Add to Cursor](https://cursor.com/en/install-mcp?name=webhooks-cc&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkB3ZWJob29rcy1jYy9tY3AiXSwiZW52Ijp7IldIS19BUElfS0VZIjoid2hjY18uLi4ifX0=)
 - **VS Code**: [Add to VS Code](https://insiders.vscode.dev/redirect/mcp/install?name=webhooks-cc&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40webhooks-cc%2Fmcp%22%5D%2C%22env%22%3A%7B%22WHK_API_KEY%22%3A%22%24%7Binput%3Awhk_api_key%7D%22%7D%7D&inputs=%5B%7B%22id%22%3A%22whk_api_key%22%2C%22type%22%3A%22promptString%22%2C%22description%22%3A%22webhooks.cc%20API%20key%20%28get%20yours%20at%20webhooks.cc%2Faccount%29%22%2C%22password%22%3Atrue%7D%5D)
 
+Both links set `WHK_API_KEY`; to start without a key, use the commands below.
+
 ### CLI
 
 ```bash
 # Claude Code
-claude mcp add -s user --transport stdio webhooks-cc -e WHK_API_KEY=whcc_... -- npx -y @webhooks-cc/mcp
+claude mcp add -s user --transport stdio webhooks-cc -- npx -y @webhooks-cc/mcp
 
 # OpenAI Codex
-codex mcp add webhooks-cc -e WHK_API_KEY=whcc_... -- npx -y @webhooks-cc/mcp
-
-# Cursor
-npx @webhooks-cc/mcp setup cursor --api-key whcc_...
-
-# VS Code
-npx @webhooks-cc/mcp setup vscode --api-key whcc_...
-
-# Windsurf
-npx @webhooks-cc/mcp setup windsurf --api-key whcc_...
-
-# Claude Desktop
-npx @webhooks-cc/mcp setup claude-desktop --api-key whcc_...
+codex mcp add webhooks-cc -- npx -y @webhooks-cc/mcp
+
+# Or let setup write the config
+npx @webhooks-cc/mcp setup claude-code
+npx @webhooks-cc/mcp setup cursor
+npx @webhooks-cc/mcp setup vscode
+npx @webhooks-cc/mcp setup codex
+npx @webhooks-cc/mcp setup windsurf
+npx @webhooks-cc/mcp setup claude-desktop
 ```
 
+To start with an API key, add `-e WHK_API_KEY=whcc_...` to the `mcp add` commands, or `--api-key whcc_...` to `setup`.
+
 ### Manual config
 
 ```json
@@ -64,11 +78,11 @@ npx @webhooks-cc/mcp setup claude-desktop --api-key whcc_...
 }
 ```
 
-Get your API key at [webhooks.cc/account/api-keys](https://webhooks.cc/account/api-keys).
+Leave out `env` to start without a key. Get your API key at [webhooks.cc/account/api-keys](https://webhooks.cc/account/api-keys).
 
 ## What it exposes
 
-The server exposes `46` tools, `3` prompts, and `3` resource surfaces with an API key, and `11` sandbox tools without one.
+The server exposes `46` tools, `3` prompts, and `3` resource surfaces with an API key, the same `46` tools and the prompts with a saved connection, and `11` sandbox tools otherwise. The remote server exposes `44` tools.
 
 ### Endpoint tools
 
@@ -147,13 +161,19 @@ Endpoints shared with you already appear in `list_endpoints` (with `fromTeam`) a
 
 ### Without an API key: the agent sandbox
 
-Started without `WHK_API_KEY`, the server registers sandbox tools instead ([auth.md](https://webhooks.cc/auth.md)):
+Started without `WHK_API_KEY`, the server starts with the full tools when [the agent credential file](#the-agent-credential-file) holds a live connection to a human's account. Otherwise it registers sandbox tools instead ([auth.md](https://webhooks.cc/auth.md)):
 
 - `create_endpoint`, `list_endpoints`, `get_endpoint`, `delete_endpoint`, `list_requests`, `get_request`, `wait_for_request`, `generate_payload_schema`: the same names and arguments as the full tools, in a sandbox of up to 3 endpoints, 25 captured requests each and 100 in all, for 24 hours. The first `create_endpoint` registers it (a few seconds of proof of work).
-- `connect_account`: returns a link and a 6-digit code for a human to connect the agent to their account.
-- `wait_for_connection`: waits for the human, then replaces the sandbox tools with the full tools for that account (`notifications/tools/list_changed`).
+- `connect_account`: returns a link and a 6-digit code for a human to connect the agent to their account. Pass the email they sign in to webhooks.cc with.
+- `wait_for_connection`: waits for the human, then replaces the sandbox tools with the full tools for that account (`notifications/tools/list_changed`) and saves the connection.
 - `about_sandbox`: the limits and how to connect, without a network call.
 
+The human approves the agent once: later sessions start connected, for 90 days. When they disconnect the agent under Account, Connected agents, the sandbox tools come back. A sandbox made in an earlier session cannot move into the account, because only the process that registered holds the claim token; `connect_account` then connects through a new registration and says so, and the old endpoints stay in the sandbox until they expire.
+
+### The agent credential file
+
+The sandbox and the connection are saved in `~/.config/whk/agent.json` (`$XDG_CONFIG_HOME/whk/agent.json` when set; `~/Library/Application Support/whk/agent.json` on macOS; `%APPDATA%\whk\agent.json` on Windows), or wherever `WHK_AGENT_FILE` points. The [TypeScript](https://webhooks.cc/docs/sdk), [Python](https://webhooks.cc/docs/sdk/python) and [Go](https://webhooks.cc/docs/sdk/go) SDKs and the [`whk` CLI](https://webhooks.cc/docs/cli/commands#sandbox) share it, so a connection made in one works in all of them. It is written atomically with mode `0600`, holds identity assertions and short-lived tokens (never the claim token), and an API key always wins over it. The format is described in [AI agents](https://webhooks.cc/docs/agents#the-agent-credential-file) and specified in [agent-credentials.md](https://github.com/kroqdotdev/webhooks-cc/blob/main/packages/sdk/conformance/agent-credentials.md).
+
 ## Prompts
 
 The server exposes MCP prompts for common workflows:
@@ -231,7 +251,7 @@ Typical agent flows:
 
 ## Programmatic use
 
-The package also exports `createServer()`, `registerTools()`, `registerPrompts()`, and `registerResources()` if you want to embed the server yourself.
+The package also exports `createServer()`, `registerTools()`, `registerSandboxTools()`, `registerPrompts()`, and `registerResources()` if you want to embed the server yourself. `createServer()` without `apiKey` takes `credentialsFile` (a path, or `false` to keep the sandbox and the connection in memory). `registerTools(server, client, { remote: true })` applies the remote server's restrictions; it is also exported from `@webhooks-cc/mcp/tools`.
 
 ```ts
 import { createServer } from "@webhooks-cc/mcp";