Skip to main content
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 all workspace conversations and shell history
  • 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:
1

Open Settings

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

Copy the workspace MCP URL

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

Create a token

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

Configure your client

Use one of the examples below.

​
Client configuration examples

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

[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

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

ToolDescription
list_tasksList tasks in the workspace. Filter by status (active, completed, archived, todo, all), parent task, and limit.
get_taskGet detailed task information including optional conversation history (first, last, or full).
get_task_commentsRetrieve comments and threaded replies on a task or todo.
get_task_attachmentsGet attachment metadata and preview URLs for a task.
searchFull-text search across workspace conversations and shell history. Supports keyword, semantic, and hybrid search modes.
list_workspace_usersList workspace members with their user IDs, roles, and usernames.
get_ai_capabilitiesDiscover available AI providers, model IDs, and reasoning effort options.
whim_get_workspace_configGet the resolved workspace configuration including skills, env vars, MCP servers, plugins, and instructions.

​
Task creation

ToolDescription
create_taskCreate and immediately start a running task in its own container. Specify title, prompt, model, source branch, and more.
create_todoCreate a backlog todo without running it. Supports body, assignee, priority, effort, and tags.
create_batchCreate multiple tasks or todos in a single call with a shared relationship decision.
launch_todoLaunch a backlog todo, optionally with a startup prompt override.

​
Task lifecycle

ToolDescription
pause_taskPause a running task (transitions to sleeping).
resume_taskResume a paused task and restore terminal sessions.
complete_tasksMark one or more tasks as completed and suspend their containers.
archive_tasksArchive one or more tasks and suspend their containers.
send_promptSend a follow-up prompt to another running task’s agent terminal. Can copy attachments onto the target.

​
Task organization

ToolDescription
edit_taskUpdate task metadata: title, assignee, priority, effort, tags.
edit_todoUpdate todo-specific fields: body, model, source branch, and more.
nest_taskNest, unnest, or reorder child tasks under a top-level parent (one level of nesting only).
fork_taskCreate a new task from an existing task using session (full context copy) or summary mode.
create_task_commentAdd comments to tasks or todos, with optional threading via parentId.

​
Configuration

ToolDescription
settingsInspect or apply workspace settings snapshots.
imagesList, 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.