Find the guidance you need.

MCP

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. A successfully connected server registers its tools into the model catalog; a failed or disabled server is never presented as an available tool.

The config file defaults to ~/.codewhale/mcp.json (the legacy ~/.deepseek/mcp.json is still read when the Codewhale file is absent), overridable with mcp_config_path or DEEPSEEK_MCP_CONFIG. The mcpServers key used by other clients is accepted too.

Setup and management

Bootstrap a starter config with codewhale-tui mcp init; inside the TUI, /mcp opens a compact manager showing each server's enabled state, transport, command or URL, timeouts, and connection errors. Common commands:

codewhale-tui mcp add <name> --command "<cmd>" --arg "<arg>"
codewhale-tui mcp add <name> --url "https://example.com/mcp" --bearer-token-env-var MCP_TOKEN
codewhale-tui mcp login <name>      # OAuth for remote servers
codewhale-tui mcp list
codewhale-tui mcp validate

Config edits made from the TUI are written immediately, but the model-visible MCP tool pool is not hot-reloaded — the manager marks it restart-required. /mcp validate and /mcp reload reconnect to refresh the on-screen snapshot.

Remote authentication

URL-based servers can use static headers, env-derived env_headers, bearer_token_env_var, or OAuth. Precedence is conservative: headers and env_headers apply first; bearer_token_env_var adds an Authorization header only when one is not already set; OAuth login tokens likewise never override an explicit header. Avoid committing literal Authorization headers — prefer env_headers, bearer_token_env_var, or OAuth login so secrets stay outside the MCP file.

Tool naming and safety

Discovered MCP tools are exposed to the model as mcp_<server>_<tool> — a server named git with a status tool becomes mcp_git_status. MCP tools flow through the same approval framework as built-in tools: read-only MCP helpers can run without prompts when policy permits, side-effectful MCP tools require approval, and Full Access does not bypass hard policy holds.

Only configure MCP servers you trust, and treat MCP server configuration as equivalent to running code on your machine. Reviewed local plugin bundles can also contribute MCP servers: they reuse the same MCP manager, approval, and network-policy paths, appear under namespaced <plugin>-<server> identities, and are held to a stricter boundary than hand-written mcp.json.

Codewhale as an MCP server

codewhale-tui serve --mcp runs Codewhale as an stdio MCP server so other sessions (or any MCP client) can call its tools; codewhale mcp-server is the equivalent dispatcher entrypoint. codewhale-tui mcp add-self resolves the current binary path and writes the server into your MCP config. Keep the modes distinct: serve --http is the runtime HTTP/SSE API, a separate surface.