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 can use Codewhale as a tool server. By default, it exposes only read-only file_read and search tools.

codewhale mcp add-self
codewhale mcp tools codewhale

add-self registers codewhale serve --mcp over stdio; codewhale mcp-server is the equivalent entry point. Write tools stay withheld unless the operator explicitly permits them in server configuration. Runtime API HTTP is a separate transport.

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 on by default — execute_tools is advertised from the first request — and MCP and plugin tools compose inside a program the same way built-in ones do. Turning it off does not remove code mode: execute_tools goes back to being deferred, and the model can still find it through tool_search. To turn it off for one session, or in config:

codewhale --disable code_mode

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

• Nested native, MCP and plugin calls pass the same gate as a direct call: allow/deny lists, ask-rules, and review still apply. A call that needs approval raises the normal approval card and pauses the program; allow resumes it, deny fails only that call. Approving the program itself grants nothing.
• MCP calls run through the session's MCP pool, and plugin tools are callable inside a program just like built-in ones.
• Limits per program: 50 nested calls, 4 at a time, and 16 KiB returned. There is no fixed 30-second cap: a program runs on the turn's remaining wall clock, unbounded unless [tui].turn_wall_clock_secs is set.
• Code mode is not available in Plan mode.

Next