| 1 | # MCP (External Tool Servers) |
| 2 | |
| 3 | In the terminal, `/mcp` (also `/mcps`) opens **Extensions → MCP**. Enter opens the selected server’s recovery action or read-only details. An empty inventory offers server suggestions; browsing them installs nothing. Explicit subcommands such as `/mcp status`, `/mcp doctor`, `/mcp login`, and `/mcp add` retain their existing behavior. |
| 4 | |
| 5 | |
| 6 | > 阅读简体中文版：[zh_hans/MCP.md](zh_hans/MCP.md) |
| 7 | |
| 8 | codewhale can load additional tools via MCP (Model Context Protocol). MCP servers can be local stdio processes that the TUI starts, or remote URL-based servers that speak Streamable HTTP with legacy SSE fallback. |
| 9 | |
| 10 | Browsing note: |
| 11 | - `Web` is the canonical, deferred built-in browsing tool; it provides |
| 12 | `search`, `fetch`, and `wait` actions when network policy permits. |
| 13 | - `web_search`, `fetch_url`, and `wait_for_dev_server` are hidden replay-only |
| 14 | aliases. New prompts and integrations should use `Web`. |
| 15 | |
| 16 | Server mode note: |
| 17 | - `codewhale serve --mcp` runs the MCP stdio server. |
| 18 | - `codewhale serve --http` runs the runtime HTTP/SSE API (separate mode). |
| 19 | - `codewhale mcp-server` is an equivalent stdio entrypoint on the same |
| 20 | consolidated runtime. |
| 21 | |
| 22 | In 0.10.1, the old child-server aggregation proxy is removed. `mcp-server` |
| 23 | now uses the same native tool server as `serve --mcp`; it does not launch the |
| 24 | legacy `mcp.server_definitions` list. Saved definitions are left intact. Configure |
| 25 | external servers in `mcp.json` for the existing MCP client, or connect to those |
| 26 | servers directly from your external client. Native server write tools remain |
| 27 | withheld unless the operator explicitly permits them in its server configuration. |
| 28 | |
| 29 | ## Setup wizard vs manual MCP setup (#3407) |
| 30 | |
| 31 | The `/setup` hub includes an optional **Tools and MCP** |
| 32 | step. That step is discovery/readiness only: |
| 33 | |
| 34 | | Wizard can do | Still requires manual / explicit action | |
| 35 | | --- | --- | |
| 36 | | Show configured servers as `healthy` / `needs_config` / `off` | Start or connect MCP servers | |
| 37 | | Report config path presence (global + project) | Write or edit `mcp.json` contents | |
| 38 | | Safe static health probe (missing command/url, broken absolute path, missing bearer env) | `codewhale mcp validate`, live connect, OAuth login | |
| 39 | | Point at safe on-ramps (`/mcp`, `codewhale mcp init`, `codewhale doctor`) | Install community skills, trust skills, enable plugins | |
| 40 | | Share Hotbar source counts from the same skill/MCP adapters (#3399) | Bind Hotbar slots (Hotbar step / `H`) | |
| 41 | | Record optional/`needs_action` setup_state without blocking first-run | Anything that spawns processes or installs packages | |
| 42 | |
| 43 | Empty inventory is **not** an error: first-run users see “nothing configured |
| 44 | yet, that’s fine.” Failing or incomplete configured servers surface as |
| 45 | `needs_config` with an actionable hint and never block setup completion. |
| 46 | Enumeration never executes MCP/plugin commands beyond the static probe. |
| 47 | Summaries redact commands, args, env, headers, and tokens. |
| 48 | |
| 49 | `codewhale doctor` reports MCP/skills/tools/plugins health with the same |
| 50 | optional-surface intent (paths, counts, static checks) so wizard and doctor |
| 51 | stay consistent. |
| 52 | |
| 53 | ## Plugin-contributed MCP |
| 54 | |
| 55 | A reviewed local plugin bundle may contribute MCP servers without creating a |
| 56 | second transport or approval system. The servers use the same MCP manager, |
| 57 | tool approval, resource, prompt, timeout, and network-policy paths documented |
| 58 | here, and appear under namespaced `<plugin>-<server>` identities. |
| 59 | |
| 60 | The bundle boundary is intentionally stricter than user-authored `mcp.json`: |
| 61 | unknown fields and ambiguous transports fail closed; stdio environment values |
| 62 | must be exact environment-source references; remote literal headers and |
| 63 | secret-bearing URLs are rejected; declared network hosts must exactly match |
| 64 | the normalized endpoint host set; and redirects remain on the reviewed origin. |
| 65 | Reviewed plugin remotes also bypass ambient HTTP proxy configuration entirely; |
| 66 | proxy credentials and proxy-observed traffic are not part of the v1 review. |
| 67 | The plugin review discloses local host-user authority, structural argv, |
| 68 | environment provenance, endpoint, auth source names, scopes, and tool filters |
| 69 | without reading or printing secret values. |
| 70 | |
| 71 | Trust stages reviewed content but does not enable it. Enablement attaches that |
| 72 | staged snapshot to the current workspace's MCP pool. Disable, revoke, and other |
| 73 | cross-process generation changes remove catalog entries, cancel in-flight |
| 74 | operations, and terminate plugin stdio children. Source or staged-tree drift is |
| 75 | fully revalidated before each dispatch/catalogue boundary and fails the next |
| 76 | boundary closed; v0.9.1 does not continuously hash mutable trees during an |
| 77 | already-running call and therefore does not promise drift-triggered mid-call |
| 78 | cancellation. MCP subscriptions are not exposed through plugin bundles. See |
| 79 | [Plugin bundles](PLUGIN_BUNDLES.md) for the complete lifecycle contract. |
| 80 | |
| 81 | ## Bootstrap MCP Config |
| 82 | |
| 83 | Create a starter MCP config at your resolved MCP path: |
| 84 | |
| 85 | ```bash |
| 86 | codewhale mcp init |
| 87 | ``` |
| 88 | |
| 89 | `codewhale setup --mcp` performs the same MCP bootstrap alongside skills setup. |
| 90 | |
| 91 | Common management commands: |
| 92 | |
| 93 | ```bash |
| 94 | codewhale mcp list |
| 95 | codewhale mcp tools [server] |
| 96 | codewhale mcp add <name> --command "<cmd>" --arg "<arg>" |
| 97 | codewhale mcp add <name> --url "http://localhost:3000/mcp" |
| 98 | codewhale mcp add <name> --url "https://example.com/mcp" --bearer-token-env-var MCP_TOKEN |
| 99 | codewhale mcp login <name> |
| 100 | codewhale mcp logout <name> |
| 101 | codewhale mcp enable <name> |
| 102 | codewhale mcp disable <name> |
| 103 | codewhale mcp remove <name> |
| 104 | codewhale mcp validate |
| 105 | ``` |
| 106 | |
| 107 | `codewhale mcp logout <name>` (and `/mcp logout`) clears locally stored |
| 108 | OAuth credentials only — the provider may keep its standing grant. The next |
| 109 | login forces the consent screen, so the authorized account/workspace can |
| 110 | change; to sever the grant remotely, revoke the app from the provider's |
| 111 | account settings. |
| 112 | |
| 113 | ## In-TUI Manager |
| 114 | |
| 115 | Inside the interactive TUI, `/mcp` opens a compact manager for the resolved |
| 116 | MCP config path. It shows each configured server, whether it is enabled or |
| 117 | disabled, its transport, command or URL, timeout values, connection errors, |
| 118 | and discovered tools/resources/prompts when discovery has been run. |
| 119 | |
| 120 | Supported in-TUI actions: |
| 121 | |
| 122 | ```text |
| 123 | /mcp init |
| 124 | /mcp init --force |
| 125 | /mcp import |
| 126 | /mcp recommendations |
| 127 | /mcp add recommended <id> |
| 128 | /mcp add stdio <name> <command> [args...] |
| 129 | /mcp add http <name> <url> |
| 130 | /mcp login <name> [--scope scope] |
| 131 | /mcp logout <name> |
| 132 | /mcp enable <name> |
| 133 | /mcp disable <name> |
| 134 | /mcp remove <name> |
| 135 | /mcp validate |
| 136 | /mcp reload |
| 137 | ``` |
| 138 | |
| 139 | ### Suggested plugins and companion integrations |
| 140 | |
| 141 | `/mcp recommendations` is Codewhale's native, curated suggestions surface. |
| 142 | The entries are described as product plugins, with their component type and |
| 143 | provenance, but `/mcp add recommended <id>` still writes only the named MCP |
| 144 | server component. Viewing recommendations never fetches, installs, trusts, or |
| 145 | enables anything. Adding one writes configuration; the server is first started |
| 146 | only after an explicit `/mcp restart`. |
| 147 | |
| 148 | The v0.9.10 product suggestions use these reviewed, pinned definitions. The |
| 149 | Plugins view is the product/install surface; MCP, Skills, and sandbox adapters |
| 150 | are transparent component kinds and their own tabs remain operational and |
| 151 | diagnostic surfaces: |
| 152 | |
| 153 | | Plugin | Component | Pinned definition | Provenance and maturity | Installation boundary | |
| 154 | | --- | --- | --- | --- | --- | |
| 155 | | Chrome DevTools | MCP server (stdio) | `npx -y chrome-devtools-mcp@1.7.0` (`npx.cmd` on Windows) | [Official ChromeDevTools project](https://github.com/ChromeDevTools/chrome-devtools-mcp) | npm may download the pinned package when the user restarts MCP. | |
| 156 | | Playwright | MCP server (stdio) | `npx -y @playwright/mcp@0.0.79 --isolated` (`npx.cmd` on Windows) | [Official Microsoft project](https://github.com/microsoft/playwright-mcp) | `--isolated` starts a fresh browser profile; npm may download the pinned package only after an explicit restart. | |
| 157 | | Computer Use | First-party plugin (MCP + skill) | Ships in the binary as the `computer-use` plugin | Codewhale; enable through `/plugin` or the Extensions marketplace | This is the only computer-use integration Codewhale recommends. Third-party desktop-control MCPs are not listed here. | |
| 158 | | Browser Use | Skill plus separately installed Python runtime | Skill/runtime release `0.13.8` | [Official browser-use project](https://github.com/browser-use/browser-use) | Optional companion: not an MCP server. Codewhale does not auto-run the upstream Skill installer or install its browser/runtime dependencies. | |
| 159 | | Anthropic Sandbox Runtime | Sandbox adapter companion | `@anthropic-ai/sandbox-runtime@0.0.73` | [Official anthropic-experimental project](https://github.com/anthropic-experimental/sandbox-runtime); beta | Documentation-only adapter candidate in v0.9.10: not an MCP server and not an active Codewhale plugin adapter. It does not replace Codewhale's sandbox policy. | |
| 160 | |
| 161 | [Container Use](https://github.com/dagger/container-use) remains an additional |
| 162 | experimental suggestion with an MCP server component (`container-use stdio`). |
| 163 | The binary must be installed separately; `/mcp add recommended container-use` |
| 164 | only writes config and Codewhale never downloads it. |
| 165 | |
| 166 | This presentation follows the same useful boundary found in the local |
| 167 | Grokbuild extensions view (one product plugin may expose MCP or Skill |
| 168 | components while component tabs stay inspectable), the Kimi marketplace's |
| 169 | explicit display name/tier/source fields, and the Codex marketplace's explicit |
| 170 | source and install-policy fields. |
| 171 | Codewhale keeps its stricter rule: provenance and foreign policy are display |
| 172 | metadata only, never inherited trust or automatic installation. For full |
| 173 | bundle and marketplace semantics, see [Plugin bundles](PLUGIN_BUNDLES.md). |
| 174 | |
| 175 | `/mcp validate` (alias `/mcp doctor`) reconnects for UI discovery only: it |
| 176 | refreshes the manager snapshot you see in the pager, not the catalog the model |
| 177 | gets. |
| 178 | |
| 179 | `/mcp reload` (aliases `/mcp reconnect`, `/mcp restart`) is the hot-reload path. |
| 180 | It re-reads the MCP config sources and reconnects through the engine-owned pool, |
| 181 | so the rebuilt catalog is the exact one the next model turn uses — no TUI |
| 182 | restart. Config edits made from the TUI are written immediately and the manager |
| 183 | marks the snapshot reload-required until you run it; a failed reload leaves the |
| 184 | previous live pool intact and says so. |
| 185 | |
| 186 | Headless surfaces are the exception: the `ConfigReload` app-server request does |
| 187 | **not** refresh MCP connections, so a headless runtime still needs a restart |
| 188 | after MCP config changes. |
| 189 | |
| 190 | ## Remote network authority |
| 191 | |
| 192 | Direct HTTP/SSE requests to public hostnames validate every DNS answer and pin |
| 193 | connections to a public address. This also applies to configured servers, |
| 194 | redirects, and OAuth HTTP requests. The configured network allow/deny policy |
| 195 | applies to login and token refresh as well as MCP tool requests. |
| 196 | |
| 197 | A configured `localhost` name or private IP literal explicitly permits that |
| 198 | local endpoint. For a private DNS name, opt in on the server configuration: |
| 199 | |
| 200 | ```json |
| 201 | { |
| 202 | "mcpServers": { |
| 203 | "internal": { |
| 204 | "url": "https://mcp.internal.example/mcp", |
| 205 | "allow_private_network": true |
| 206 | } |
| 207 | } |
| 208 | } |
| 209 | ``` |
| 210 | |
| 211 | `allow_private_network` defaults to false. This exception applies only to the |
| 212 | configured origin (scheme, host, and port); it does not authorize a different |
| 213 | redirect or OAuth origin. Servers added by the model during a session cannot |
| 214 | use this exception, even if their configuration contains the flag. |
| 215 | |
| 216 | Operator-configured servers continue to honor `HTTP_PROXY`, `HTTPS_PROXY`, and |
| 217 | `NO_PROXY`. When a proxy is selected for the configured origin, destination DNS |
| 218 | resolution and private-network filtering are delegated to that operator-chosen |
| 219 | proxy; a local DNS pin cannot constrain a proxy's own resolution. A `NO_PROXY` |
| 220 | match uses the direct guarded connection instead. Model-added servers, |
| 221 | reviewed plugin remotes, and secondary redirect/OAuth origins do not inherit |
| 222 | ambient proxy authority. |
| 223 | |
| 224 | ## Remote HTTP Auth |
| 225 | |
| 226 | URL-based MCP servers can use static headers, env-derived headers, bearer-token |
| 227 | env vars, or OAuth. Authorization precedence is conservative: |
| 228 | |
| 229 | 1. `headers` and `env_headers` are applied first. |
| 230 | 2. `bearer_token_env_var` adds `Authorization: Bearer <env value>` when no |
| 231 | Authorization header was already set. |
| 232 | 3. Stored OAuth credentials are used only when no Authorization header exists. |
| 233 | |
| 234 | For bearer-token auth, prefer env-backed config: |
| 235 | |
| 236 | ```json |
| 237 | { |
| 238 | "servers": { |
| 239 | "remote": { |
| 240 | "url": "https://example.com/mcp", |
| 241 | "bearer_token_env_var": "EXAMPLE_MCP_TOKEN" |
| 242 | } |
| 243 | } |
| 244 | } |
| 245 | ``` |
| 246 | |
| 247 | For generic remote MCP OAuth, add the URL server and run login: |
| 248 | |
| 249 | ```bash |
| 250 | codewhale mcp add remote --url "https://example.com/mcp" |
| 251 | codewhale mcp login remote |
| 252 | ``` |
| 253 | |
| 254 | Codewhale discovers the server OAuth metadata, opens the authorization URL in |
| 255 | your browser, listens on a local callback, exchanges the code, and stores the |
| 256 | token response through the Codewhale secrets backend. Stored OAuth tokens are |
| 257 | looked up by server name plus URL and refreshed when possible before requests. |
| 258 | During login, the CLI prints the authorization URL and a waiting status while |
| 259 | the local callback listener is active. If a URL-based server returns 401 or |
| 260 | Unauthorized during connect/discovery, `codewhale mcp connect <name>` reports |
| 261 | that OAuth authentication is required and points to |
| 262 | `codewhale mcp login <name>`. Resource helper listings also surface an |
| 263 | `authentication_required` entry for auth-shaped failures instead of silently |
| 264 | looking empty. |
| 265 | |
| 266 | Optional OAuth fields: |
| 267 | |
| 268 | ```json |
| 269 | { |
| 270 | "servers": { |
| 271 | "remote": { |
| 272 | "url": "https://example.com/mcp", |
| 273 | "scopes": ["tools/read"], |
| 274 | "oauth": { |
| 275 | "client_id": "public-client-id" |
| 276 | }, |
| 277 | "oauth_resource": "https://example.com" |
| 278 | } |
| 279 | } |
| 280 | } |
| 281 | ``` |
| 282 | |
| 283 | User-level config can set callback behavior when the provider requires a fixed |
| 284 | redirect: |
| 285 | |
| 286 | ```toml |
| 287 | mcp_oauth_callback_port = 1455 |
| 288 | mcp_oauth_callback_url = "http://127.0.0.1:1455/callback" |
| 289 | ``` |
| 290 | |
| 291 | These callback fields are ignored from project-scope config overlays. |
| 292 | |
| 293 | ## Hugging Face MCP |
| 294 | |
| 295 | Hugging Face provides a hosted MCP server for Hub resources, documentation, |
| 296 | datasets, Spaces, and community tools. Codewhale does not call Hugging Face's |
| 297 | Hub HTTP APIs from `/hf`; it only helps you inspect and set up the MCP config |
| 298 | that the regular MCP manager will load. |
| 299 | |
| 300 | The recommended setup path is Hugging Face's settings-generated configuration: |
| 301 | |
| 302 | 1. Visit <https://huggingface.co/settings/mcp> while signed in. |
| 303 | 2. Choose the MCP client closest to your Codewhale config shape and copy the |
| 304 | generated server snippet. |
| 305 | 3. Paste the Hugging Face server entry into your resolved MCP config file. |
| 306 | 4. Run `/mcp reload` to rebuild the live model-visible tool pool. |
| 307 | |
| 308 | Codewhale reads both `servers` and `mcpServers`, so settings-generated snippets |
| 309 | can be adapted without changing the rest of the MCP file. A placeholder-only |
| 310 | shape looks like this: |
| 311 | |
| 312 | ```json |
| 313 | { |
| 314 | "servers": { |
| 315 | "huggingface": { |
| 316 | "url": "https://huggingface.co/mcp", |
| 317 | "headers": { |
| 318 | "Authorization": "Bearer ${HF_TOKEN}" |
| 319 | } |
| 320 | } |
| 321 | } |
| 322 | } |
| 323 | ``` |
| 324 | |
| 325 | The placeholder above is not a runnable secret. Use the settings-generated |
| 326 | value in your private MCP config and never commit real Hugging Face tokens. |
| 327 | |
| 328 | Interactive helpers: |
| 329 | |
| 330 | ```text |
| 331 | /hf mcp status |
| 332 | /hf mcp setup |
| 333 | /hf concepts |
| 334 | ``` |
| 335 | |
| 336 | `/hf mcp status` checks the configured MCP file for common Hugging Face server |
| 337 | names or Hugging Face MCP URLs. `/hf concepts` explains the difference between |
| 338 | the Hugging Face provider route, Hugging Face MCP, and explicit Hub workflows. |
| 339 | |
| 340 | Official docs: <https://huggingface.co/docs/hub/hf-mcp-server> |
| 341 | |
| 342 | ## Config File Location |
| 343 | |
| 344 | Default path: |
| 345 | |
| 346 | - `~/.codewhale/mcp.json` (`~/.deepseek/mcp.json` is still read when the Codewhale file is absent) |
| 347 | |
| 348 | Overrides: |
| 349 | |
| 350 | - Config: `mcp_config_path = "/path/to/mcp.json"` |
| 351 | - Env: `DEEPSEEK_MCP_CONFIG=/path/to/mcp.json` |
| 352 | |
| 353 | `codewhale mcp init` (and `codewhale setup --mcp`) writes to this resolved path. |
| 354 | |
| 355 | The interactive `/config` editor also exposes `mcp_config_path`. Changing it in |
| 356 | the TUI updates the path used by `/mcp` and marks the pool reload-required; |
| 357 | `/mcp reload` then switches the live pool to the new config source. |
| 358 | |
| 359 | After editing the MCP file or changing `mcp_config_path`, run `/mcp reload`. No |
| 360 | TUI restart is needed. |
| 361 | |
| 362 | ## Tool Naming |
| 363 | |
| 364 | Discovered MCP tools are exposed to the model as: |
| 365 | |
| 366 | - `mcp_<server>_<tool>` |
| 367 | |
| 368 | Example: a server named `git` with a tool named `status` becomes `mcp_git_status`. |
| 369 | |
| 370 | The command palette includes MCP entries grouped by server. It shows disabled |
| 371 | and failed servers instead of hiding them, and uses the same runtime tool names |
| 372 | shown to the model. |
| 373 | |
| 374 | ## Resource and Prompt Helpers |
| 375 | |
| 376 | The CLI also exposes helper tools when MCP is enabled: |
| 377 | |
| 378 | - `list_mcp_resources` (optional `server` filter) |
| 379 | - `list_mcp_resource_templates` (optional `server` filter) |
| 380 | - `mcp_read_resource` / `read_mcp_resource` (aliases) |
| 381 | - `mcp_get_prompt` |
| 382 | |
| 383 | ## Minimal Example |
| 384 | |
| 385 | ```json |
| 386 | { |
| 387 | "timeouts": { |
| 388 | "connect_timeout": 30, |
| 389 | "execute_timeout": 1800, |
| 390 | "read_timeout": 120 |
| 391 | }, |
| 392 | "servers": { |
| 393 | "example": { |
| 394 | "command": "node", |
| 395 | "args": ["./path/to/your-mcp-server.js"], |
| 396 | "env": {}, |
| 397 | "disabled": false |
| 398 | } |
| 399 | } |
| 400 | } |
| 401 | ``` |
| 402 | |
| 403 | You can also use `mcpServers` instead of `servers` for compatibility with other clients. |
| 404 | |
| 405 | ## Running Codewhale as an MCP Server |
| 406 | |
| 407 | You can register your local Codewhale binary as an MCP server so other Codewhale sessions (or any MCP client) can call its tools. |
| 408 | |
| 409 | ### Quick Setup |
| 410 | |
| 411 | ```bash |
| 412 | codewhale mcp add-self |
| 413 | ``` |
| 414 | |
| 415 | This resolves the current binary path, generates a config entry that runs |
| 416 | `codewhale serve --mcp`, and writes it to your MCP config file. The default |
| 417 | server name is `codewhale`. |
| 418 | |
| 419 | Options: |
| 420 | |
| 421 | - `--name <NAME>` — custom server name (default: `codewhale`) |
| 422 | - `--workspace <PATH>` — workspace directory for the server |
| 423 | |
| 424 | ### Manual Config |
| 425 | |
| 426 | Equivalent manual entry in `~/.codewhale/mcp.json`: |
| 427 | |
| 428 | ```json |
| 429 | { |
| 430 | "servers": { |
| 431 | "codewhale": { |
| 432 | "command": "/path/to/codewhale", |
| 433 | "args": ["serve", "--mcp"], |
| 434 | "env": {} |
| 435 | } |
| 436 | } |
| 437 | } |
| 438 | ``` |
| 439 | |
| 440 | The consolidated `codewhale` runtime supports `serve --mcp` directly and also |
| 441 | offers the equivalent `codewhale mcp-server` stdio entrypoint. Release |
| 442 | installers expose the same runtime as `codew`; `mcp add-self` automatically |
| 443 | resolves the command that invoked it. |
| 444 | |
| 445 | ### Prerequisites |
| 446 | |
| 447 | - The binary referenced in `command` must exist and be executable. |
| 448 | - The MCP server runs as a child process via stdio — no network ports required. |
| 449 | - Each MCP client session spawns its own server process. |
| 450 | |
| 451 | ### Tool Naming |
| 452 | |
| 453 | Tools from an MCP server follow the standard naming convention: |
| 454 | |
| 455 | - `mcp_<server>_<tool>` |
| 456 | |
| 457 | For example, the `shell` tool from the default server (named `codewhale`) |
| 458 | becomes `mcp_codewhale_shell`. |
| 459 | |
| 460 | ### MCP Server vs HTTP/SSE API vs ACP |
| 461 | |
| 462 | | | `codewhale serve --mcp` | `codewhale serve --http` | `codewhale serve --acp` | |
| 463 | |---|---|---|---| |
| 464 | | **Protocol** | MCP stdio | HTTP/SSE JSON-RPC | ACP stdio | |
| 465 | | **Use case** | Tool server for MCP clients | Runtime API for apps | Editor agent for Zed/custom ACP clients | |
| 466 | | **Config** | `~/.codewhale/mcp.json` entry | Direct URL connection | Editor `agent_servers` custom command | |
| 467 | | **Lifecycle** | Spawned per client session | Long-running daemon | Spawned per editor agent session | |
| 468 | |
| 469 | Use `mcp add-self` when you want Codewhale tools available to other MCP clients. |
| 470 | Use `serve --http` when building applications that consume the API directly. |
| 471 | Use `serve --acp` when an editor wants to talk to Codewhale as an ACP agent. |
| 472 | |
| 473 | ### Verification |
| 474 | |
| 475 | After adding, test the connection: |
| 476 | |
| 477 | ```bash |
| 478 | codewhale mcp validate |
| 479 | codewhale mcp tools codewhale |
| 480 | ``` |
| 481 | |
| 482 | ## Connection Lifecycle |
| 483 | |
| 484 | Session boot is lazy (#6033): a configured server is not spawned until |
| 485 | something asks for it — a turn whose `allowed_tools`/`tools.always_load` |
| 486 | selection covers its `mcp_<server>_*` names, a model call that resolves to |
| 487 | one of its tools, or an explicit `/mcp retry <name>`. Servers marked |
| 488 | `required` still connect eagerly at boot so their failure surfaces before the |
| 489 | first turn. A configured-but-unstarted server shows as `configured`, never |
| 490 | `connecting`; the connecting label only describes handshakes actually in |
| 491 | flight. |
| 492 | |
| 493 | An MCP-focused `tool_search` is also explicit discovery intent: search a |
| 494 | configured server name (for example `engram`), an exact `mcp_<server>_...` |
| 495 | name, or use `{"query":"mcp_.*","match":"regex"}`. The current turn's |
| 496 | allow/deny ceiling filters the configured servers before a batch of at most |
| 497 | eight connects; the existing five-second wait and cancellation remain in |
| 498 | force. General searches do not boot all optional servers. Only actual |
| 499 | `tools/list` schemas enter the deferred catalogue; failed, disabled, or |
| 500 | revoked servers do not acquire fabricated tools. Narrow a broad search by |
| 501 | server name when more than eight configured servers match. |
| 502 | |
| 503 | `codewhale mcp connect`, `validate`, and `tools` inspect their own process's |
| 504 | pool. They do not attach transports to a running TUI or exec session. Use |
| 505 | in-session discovery or explicit tool selection. In the TUI, |
| 506 | `/mcp retry <name>` connects through the current session's pool; |
| 507 | `/mcp reload` re-reads its MCP configuration. |
| 508 | |
| 509 | ## Server Fields |
| 510 | |
| 511 | Per-server settings: |
| 512 | |
| 513 | - `command` (string, required) |
| 514 | - `args` (array of strings, optional) |
| 515 | - `env` (object, optional) |
| 516 | - `connect_timeout`, `execute_timeout`, `read_timeout` (seconds, optional). A per-server value overrides the global `timeouts` block, and each budget is independent of the others: |
| 517 | - `connect_timeout` (default 30) covers spawn, `initialize` and the first `tools/list`, so a cold `uvx`/`npx` package download counts against it. |
| 518 | - `execute_timeout` (default 1800) is the budget for each `tools/call` and `prompts/get`. An explicit shorter value is respected, and `read_timeout` never cuts a running tool short. |
| 519 | - `read_timeout` (default 120) bounds each reply wait during the handshake and tool discovery, and is the budget for `resources/read`. |
| 520 | - A request that runs out of budget fails with a timeout. The connection is kept, and a reply that arrives later is discarded instead of being handed to another call. Interrupting the turn stops the wait at once, but Codewhale does not send `notifications/cancelled` yet, so a server that handles one request at a time finishes the abandoned call before it answers the next one. |
| 521 | - Streamable HTTP servers return the reply inside the POST itself; the request's own budget bounds that POST too. A request that expires while still sending closes the connection, which is rebuilt before the next call. |
| 522 | - `disabled` (bool, optional) |
| 523 | - `enabled` (bool, optional, default `true`) |
| 524 | - `required` (bool, optional): startup/connect validation fails if this server cannot initialize. |
| 525 | - `enabled_tools` (array, optional): allowlist of tool names for this server. |
| 526 | - `disabled_tools` (array, optional): denylist applied after `enabled_tools`. |
| 527 | - `url` (string, optional): Streamable HTTP endpoint for a remote MCP server. |
| 528 | - `allow_private_network` (boolean, default false): operator opt-in for private DNS addresses on this configured origin; ignored for model-added servers. |
| 529 | - `transport` (string, optional): set to `"sse"` for legacy SSE endpoints. |
| 530 | - `headers` (object, optional): literal HTTP headers for URL-based servers. |
| 531 | - `env_headers` or `env_http_headers` (object, optional): header names mapped to environment variable names. |
| 532 | - `bearer_token_env_var` (string, optional): environment variable containing a bearer token. |
| 533 | - `scopes` (array, optional): default OAuth scopes for `mcp login`. |
| 534 | - `oauth.client_id` (string, optional): pre-registered OAuth client ID. |
| 535 | - `oauth_resource` (string, optional): resource parameter appended to the authorization URL. |
| 536 | |
| 537 | ## Safety Notes |
| 538 | |
| 539 | MCP tools flow through the same approval framework as built-in tools. Read-only |
| 540 | MCP helpers (resource/prompt listing and reads) can run without prompts in Ask |
| 541 | and Auto-Review when policy permits, while side-effectful MCP tools require |
| 542 | approval. Full Access does not bypass hard policy holds. |
| 543 | |
| 544 | You should still only configure MCP servers you trust, and treat MCP server configuration as equivalent to running code on your machine. |
| 545 | Avoid committing literal `Authorization` headers. Prefer `env_headers`, |
| 546 | `bearer_token_env_var`, or OAuth login so secrets stay outside the MCP file. |
| 547 | |
| 548 | ## Troubleshooting |
| 549 | |
| 550 | - Run `codewhale doctor` to confirm the MCP config path it resolved and whether it exists. |
| 551 | - In the TUI, run `/mcp validate` to refresh the visible server/tool snapshot. |
| 552 | - If tools are missing from the model's catalog after a config or credential |
| 553 | change, run `/mcp reload` — `/mcp validate` only refreshes the UI snapshot. |
| 554 | - If the MCP config is missing, run `codewhale mcp init --force` to regenerate it. |
| 555 | - If tools don’t appear, verify the server command works from your shell and that the server supports MCP `tools/list`. |
| 556 |