> ## Documentation Index
> Fetch the complete documentation index at: https://docs.whim.run/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Tools

> The 24 MCP tools available to agents inside containers and external clients via the Whim MCP server.

Whim exposes a [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that provides workspace awareness and task management. This server is available in two ways:

* **Inside task containers** — automatically injected via stdio transport. Every agent has access to these tools out of the box.
* **External clients** — connect over HTTP using a bearer token. Use from Claude Desktop, Codex CLI, or any MCP-compatible client.

Both paths expose the same 24 tools with the same capabilities.

## How agents use these tools

The built-in MCP server gives agents workspace context they wouldn't otherwise have. An agent working on a task can:

* **Check what else is happening** — list tasks to avoid duplicating work or to understand the broader project state
* **Spawn subtasks** — create child tasks to parallelize work (the foundation of [orchestrator mode](/whim-agent/orchestrator-mode))
* **Coordinate with other agents** — send prompts to running tasks and receive reports back
* **Search for context** — find past decisions, implementations, or debugging context across workspace conversations and task summaries
* **Plan future work** — create todos in the backlog for follow-up items

The agent doesn't need to be in orchestrator mode to use these tools. Any task can list, search, or create work — orchestrator mode simply optimizes the agent's behavior for delegation rather than direct implementation.

## External client setup

To connect an external MCP client to your workspace:

<Steps>
  <Step title="Open Settings">
    In Whim, go to **Settings** > **Configuration** > **Whim MCP**.
  </Step>

  <Step title="Copy the workspace MCP URL">
    ```
    https://api.whim.run/api/mcp/<team-slug>/<workspace-slug>
    ```
  </Step>

  <Step title="Create a token">
    Click **Create Token**, copy it immediately, and store it securely. Whim only shows the full token once.
  </Step>

  <Step title="Configure your client">
    Use one of the examples below.
  </Step>
</Steps>

### Client configuration examples

<AccordionGroup>
  <Accordion title="Claude Desktop / Claude Code (JSON)">
    ```json theme={null}
    {
      "mcpServers": {
        "whim": {
          "type": "http",
          "url": "https://api.whim.run/api/mcp/<team-slug>/<workspace-slug>",
          "headers": {
            "Authorization": "Bearer ${WHIM_MCP_TOKEN}"
          }
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="Codex CLI (~/.codex/config.toml)">
    ```toml theme={null}
    [mcp_servers.whim]
    url = "https://api.whim.run/api/mcp/<team-slug>/<workspace-slug>"
    bearer_token_env_var = "WHIM_MCP_TOKEN"
    ```

    Or add via CLI:

    ```bash theme={null}
    export WHIM_MCP_TOKEN="whim_mcp_<lookup>_<secret>"
    codex mcp add whim \
      --url "https://api.whim.run/api/mcp/<team-slug>/<workspace-slug>" \
      --bearer-token-env-var WHIM_MCP_TOKEN
    ```
  </Accordion>

  <Accordion title="Generic HTTP client">
    ```http theme={null}
    GET https://api.whim.run/api/mcp/<team-slug>/<workspace-slug>
    Authorization: Bearer whim_mcp_<lookup>_<secret>
    Accept: text/event-stream

    POST https://api.whim.run/api/mcp/<team-slug>/<workspace-slug>
    Authorization: Bearer whim_mcp_<lookup>_<secret>
    Content-Type: application/json
    Accept: application/json, text/event-stream
    ```

    Streamable HTTP MCP is content-negotiated. Whim returns `406 Not Acceptable` when `Accept` headers are missing or incompatible.
  </Accordion>
</AccordionGroup>

## Tool reference

### Task discovery

| Tool                        | Description                                                                                                               |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `list_tasks`                | List tasks in the workspace. Filter by status (`active`, `completed`, `archived`, `todo`, `all`), parent task, and limit. |
| `get_task`                  | Get detailed task information including optional conversation history (`first`, `last`, or `full`).                       |
| `get_task_comments`         | Retrieve comments and threaded replies on a task or todo.                                                                 |
| `get_task_attachments`      | Get attachment metadata and preview URLs for a task.                                                                      |
| `search`                    | Search workspace conversations and task summaries. Supports keyword, semantic, and hybrid search modes.                   |
| `list_workspace_users`      | List workspace members with their user IDs, roles, and usernames.                                                         |
| `get_ai_capabilities`       | Discover available AI providers, model IDs, and reasoning effort options.                                                 |
| `whim_get_workspace_config` | Get the resolved workspace configuration including skills, env vars, MCP servers, plugins, and instructions.              |

### Task creation

| Tool           | Description                                                                                                                   |
| -------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `create_task`  | Create and immediately start a running task in its own container. Specify title, prompt, model, remote base branch, and more. |
| `create_todo`  | Create a backlog todo without running it. Supports body, assignee, priority, effort, tags, and remote base branch settings.   |
| `create_batch` | Create multiple tasks or todos in a single call with a shared relationship decision.                                          |
| `launch_todo`  | Launch a backlog todo, optionally with a startup prompt override.                                                             |

### Task lifecycle

| Tool             | Description                                                                                             |
| ---------------- | ------------------------------------------------------------------------------------------------------- |
| `pause_task`     | Pause a running task (transitions to sleeping).                                                         |
| `resume_task`    | Resume a paused task and restore terminal sessions.                                                     |
| `complete_tasks` | Mark one or more tasks as completed and suspend their containers.                                       |
| `archive_tasks`  | Archive one or more tasks and suspend their containers.                                                 |
| `send_prompt`    | Send a follow-up prompt to another running task's agent terminal. Can copy attachments onto the target. |

### Task organization

| Tool                  | Description                                                                                    |
| --------------------- | ---------------------------------------------------------------------------------------------- |
| `edit_task`           | Update task metadata: title, assignee, priority, effort, tags.                                 |
| `edit_todo`           | Update todo-specific fields: body, model, remote base branch, and more.                        |
| `nest_task`           | Nest, unnest, or reorder child tasks under a top-level parent (one level of nesting only).     |
| `fork_task`           | Create a new task from an existing task using `session` (full context copy) or `summary` mode. |
| `create_task_comment` | Add comments to tasks or todos, with optional threading via `parentId`.                        |

### Configuration

| Tool       | Description                                                           |
| ---------- | --------------------------------------------------------------------- |
| `settings` | Inspect or apply workspace settings snapshots.                        |
| `images`   | List, build, activate, delete, or inspect workspace container images. |

## Token management

<CardGroup cols={2}>
  <Card title="Scope" icon="lock">
    Tokens are scoped to the workspace where they were created. Use a different
    workspace's URL and token to access another workspace.
  </Card>

  <Card title="Revocation" icon="ban">
    Revoke tokens from the **Whim MCP** settings page. Revoked tokens stop
    working immediately.
  </Card>

  <Card title="Last-used tracking" icon="clock">
    Whim tracks when each token was last used, visible in the token management
    UI.
  </Card>

  <Card title="Compatibility" icon="puzzle-piece">
    Requires clients that can send a custom `Authorization` header. Clients that
    only support OAuth-based MCP auth will need a different connection path.
  </Card>
</CardGroup>