Connect tools with MCP

Add a server

codewhale mcp add git --command "uvx" --arg "mcp-server-git"
codewhale mcp add docs --url "https://example.com/mcp"
codewhale mcp list
codewhale mcp validate

--command starts a local server over stdio; repeat --arg for each argument. --url connects to a remote server over Streamable HTTP, with legacy SSE as a fallback. mcp validate checks the config and the servers you require.

Inside a session, /mcp opens the MCP manager: each server's state, transport, timeouts, errors, and discovered tools. The same actions are available there, for example /mcp add stdio <name> <command> and /mcp add http <name> <url>.

Note: An MCP server runs with your permissions. Add only servers you trust, as you would any program you install.

Sign in to a remote server

For a server that uses OAuth, add it by URL and log in. For a bearer token, keep the token in an environment variable instead of the config file:

codewhale mcp login docs
codewhale mcp add tracker --url "https://example.com/mcp" --bearer-token-env-var TRACKER_TOKEN

An explicit Authorization header always wins: headers from config apply first, then the bearer-token variable, then a stored OAuth login. codewhale mcp logout <name> removes the stored login on this machine; the provider may keep its own grant until you revoke it there.

Edit the config file

Servers live in ~/.codewhale/mcp.json. codewhale mcp init writes a starter file. The mcpServers key used by other clients works too, so you can paste an existing entry.

{
  "servers": {
    "example": {
      "command": "node",
      "args": ["./path/to/your-mcp-server.js"],
      "env": {},
      "disabled": false
    }
  }
}

After editing the file, run /mcp reload in the session; no restart is needed. A server starts only when a turn needs one of its tools, unless you mark it "required": true to connect at startup.

Find the tools

Each tool appears to the model as mcp_<server>_<tool>: a server named git with a status tool becomes mcp_git_status. codewhale mcp tools <server> lists what a server offers. A server that fails to connect or is disabled never shows up as an available tool.

MCP tools follow your approval setting: listing and reading a server's resources and prompts can run without a prompt when policy allows, and tools with side effects ask first. Full Access does not override repository rules or managed policy.

Run Codewhale as an MCP server

Other MCP clients — including another Codewhale session — can use Codewhale's tools. Register it once:

codewhale mcp add-self
codewhale mcp tools codewhale

add-self writes an entry that runs codewhale serve --mcp over stdio. Each client starts its own process; no network port is opened. codewhale serve --http is a different thing — the Runtime API for apps.

Compose tool calls with code mode (experimental)

Code mode lets the model write one short JavaScript program that calls several tools, loops, and filters results, instead of making each call as a separate step. Only the program's final value goes back to the model, which keeps long lookups compact. It is off by default. Try it for one session, or turn it on in config:

codewhale --enable code_mode

# ~/.codewhale/config.toml
[features]
code_mode = true

• Only read-only tools that need no approval can run inside a program. Anything that writes, runs a shell command, or would ask you stops the program and reports which call it refused.
• MCP tools cannot be called from a program yet. Use them as ordinary tool calls.
• Limits per program: 50 tool calls, 4 at a time, 30 seconds, and 16 KiB returned.
• Code mode is not available in Plan mode.

Next