Skip to main content

​
Overview

Whim exposes a Model Context Protocol (MCP) server that lets external AI agents and tools interact with your workspace programmatically. You can list, search, and manage tasks; create new work; control task lifecycle; and search across conversations and shell history — all from any MCP-compatible client. Whim MCP uses static bearer tokens for authentication. You create a token in your workspace settings, configure your MCP client to send it on every request, and you’re connected. Tokens are workspace-scoped, and Whim verifies live workspace membership on every request.

​
Setup

1

Open Settings

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

Copy the workspace MCP URL

The URL determines which workspace your MCP client will operate on. The format is:
https://api.whim.run/api/mcp/<team-slug>/<workspace-slug>
3

Create a Whim MCP token

Click Create Token, copy it immediately, and store it securely. Whim only shows the full token once — you cannot retrieve it later.
4

Configure your client

Use the configuration format your client expects. See the examples below.

​
Client Configuration Examples

Codex uses TOML configuration with an [mcp_servers.<name>] table. Set a bearer_token_env_var that points to the environment variable holding your token.TOML config file:
[mcp_servers.whim]
url = "https://api.whim.run/api/mcp/<team-slug>/<workspace-slug>"
bearer_token_env_var = "WHIM_MCP_TOKEN"
Or add via the 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
Use the HTTP transport object with the Whim bearer token in headers.Authorization.
{
  "mcpServers": {
    "whim": {
      "type": "http",
      "url": "https://api.whim.run/api/mcp/<team-slug>/<workspace-slug>",
      "headers": {
        "Authorization": "Bearer ${WHIM_MCP_TOKEN}"
      }
    }
  }
}
If you are wiring up a custom client or transport, send the bearer token plus the correct streamable HTTP Accept headers.
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

​
Required HTTP Headers

Streamable HTTP MCP is content-negotiated. Most MCP clients set the Accept header automatically, but custom integrations need to be explicit.
MethodRequired Accept Header
GETtext/event-stream
POSTapplication/json, text/event-stream
Whim returns 406 Not Acceptable when these headers are missing or incompatible.

​
Available Capabilities

Once connected, your MCP client has access to 24 tools organized into the following categories:

​
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, environment variables, 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 content, 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 state).
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.

​
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.

​
Operational Notes

Token scope

Tokens are scoped to the workspace where they were created. Use a different workspace’s URL and token to access a different 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

This flow requires clients that can send a custom Authorization header to a remote MCP endpoint. Clients that only support OAuth-based remote MCP auth will need a different connection path.