MCP Tools

Whim exposes a Model Context Protocol (MCP) 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)
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:

Open Settings

In Whim, go to Settings > Configuration > Whim MCP.

Copy the workspace MCP URL

https://api.whim.run/api/mcp/<team-slug>/<workspace-slug>

Create a token

Click Create Token, copy it immediately, and store it securely. Whim only shows the full token once.

Configure your client

Use one of the examples below.

Client configuration examples

Claude Desktop / Claude Code (JSON)

{
  "mcpServers": {
    "whim": {
      "type": "http",
      "url": "https://api.whim.run/api/mcp/<team-slug>/<workspace-slug>",
      "headers": {
        "Authorization": "Bearer ${WHIM_MCP_TOKEN}"
      }
    }
  }
}

Codex CLI (~/.codex/config.toml)

[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:

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

Generic HTTP client

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.

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

Scope

Tokens are scoped to the workspace where they were created. Use a different workspace’s URL and token to access another workspace.

Revocation

Revoke tokens from the Whim MCP settings page. Revoked tokens stop working immediately.

Last-used tracking

Whim tracks when each token was last used, visible in the token management UI.

Compatibility

Requires clients that can send a custom Authorization header. Clients that only support OAuth-based MCP auth will need a different connection path.

Getting Started

Whim Agent

Tasks

AI Providers & Models

Workspaces

Git & Version Control

Terminal

Collaboration

Integrations

Configuration

Billing & Plans

Support

How agents use these tools

External client setup

Client configuration examples

Tool reference

Task discovery

Task creation

Task lifecycle

Task organization

Configuration

Token management

Scope

Revocation

Last-used tracking

Compatibility

​How agents use these tools

​External client setup

​Client configuration examples

​Tool reference

​Task discovery

​Task creation

​Task lifecycle

​Task organization

​Configuration

​Token management

Scope

Revocation

Last-used tracking

Compatibility

How agents use these tools

External client setup

Client configuration examples

Tool reference

Task discovery

Task creation

Task lifecycle

Task organization

Configuration

Token management