Use Drums from Claude Code, Cursor and Codex (MCP)

Drums publishes one MCP server. It exposes the workspace (computers, snapshots, tasks, runs and evaluations, API keys, the audit log) and the desktop itself (GUI actions, screenshots, shell, files, verify, fork, reset) as tools, so an agent in Claude Code, Cursor, Codex or any other MCP client works on Drums desktops the way the SDK does. Every tool call is scoped to the workspace of the API key, is checked against the key's scopes, and is written to the audit log.

Two ways to reach it

Both servers list exactly the same tools with the same schemas and give the same answers; the local one calls the same gateway routes. Authentication is the workspace API key in either case (Authorization: Bearer on the remote endpoint, DRUMS_TOKEN for the local command). There is no OAuth flow: create a key under API keys and put it where the snippet says drums_sk_.... The key is never shown in the console again, so treat the client's configuration file like a secret.

Print the snippet for your client

With the SDK installed and DRUMS_URL exported as in the quickstart, drums mcp --print-config prints the configuration for a client, with your gateway URL filled in and drums_sk_... where the key goes. It never prints a key. The four forms are claude, claude-local, cursor and codex; the sections below show each command and its output as printed by SDK 0.3.0. The console's Connect sheet (MCP tab) shows the same snippets for your workspace.

Claude Code

drums mcp --print-config claude

prints the registration command for the remote endpoint; Claude Code keeps it in its settings:

claude mcp add --transport http drums https://beta.drums.run/gw/mcp --header "Authorization: Bearer drums_sk_..."

Put your key in place of drums_sk_... (or write $DRUMS_TOKEN there and let the shell expand it) and run it. To run the server locally instead:

drums mcp --print-config claude-local

claude mcp add drums -e DRUMS_URL=https://beta.drums.run/gw -e DRUMS_TOKEN=drums_sk_... -- drums mcp

Then ask Claude Code for the tools: list_templates, create_computer and the rest appear under the drums server. The SDK repository also ships a Claude Code plugin (see The Claude Code plugin).

Cursor

drums mcp --print-config cursor

prints the object for ~/.cursor/mcp.json (every project) or .cursor/mcp.json (one project); put your key in place of drums_sk_...:

{
  "mcpServers": {
    "drums": {
      "url": "https://beta.drums.run/gw/mcp",
      "headers": { "Authorization": "Bearer drums_sk_..." }
    }
  }
}

Codex or any stdio client

Codex starts MCP servers as commands, so it uses the local server:

drums mcp --print-config codex

prints the table for ~/.codex/config.toml; put your key in place of drums_sk_...:

[mcp_servers.drums]
command = "drums"
args = ["mcp"]
env = { DRUMS_URL = "https://beta.drums.run/gw", DRUMS_TOKEN = "drums_sk_..." }

drums mcp is the same as python -m drums.mcp. drums mcp --env followed by a computer id binds the desktop tools to that computer, so the agent can leave computer_id out. drums mcp --create makes one computer, binds it and closes it when the server exits (--task loads a task JSON file into it).

What the local server refuses

• A key over plain HTTP. DRUMS_URL must be https://, or http:// to loopback (localhost, 127.0.0.0/8, ::1: a local drumsd). Any other http:// URL makes drums mcp exit 2 before any request, with a one-line message that names the host, never the key. For a trusted network, opt in with drums mcp --allow-insecure-http or DRUMS_ALLOW_INSECURE_HTTP=1.
• A redirect to another origin. The client follows a redirect only to the same scheme, host and port, at most 5 hops; anything else is RedirectRefused, so the key is never re-sent elsewhere.

Tools

Every tool, in the order the servers list them. workspace tools act on the workspace through the gateway; desktop tools act inside one computer and take its computer_id (the id that create_computer and list_computers return). The scope is the API-key scope the call needs; "any key" means any active key of the workspace, with the rules in the tool's description. A destructive tool is refused unless the call passes confirm: true.

Tool results are JSON text, except screenshot, which returns a PNG image. A failed call returns a tool error with a one-line reason (for example refused: pass confirm: true to destroy_computer), never a protocol error, so the agent can read it and recover.

The workflow

1. Create. list_templates (or list_snapshots) and list_tasks, then create_computer with a template and a task_id. Poll get_computer until state is ready and validity is valid; before that the desktop may still be restoring. Keep the computer id.
2. Act. screenshot to see the desktop; gui for pyautogui actions (click, type, hotkeys) with a screenshot after each one; shell, read_file, write_file and list_dir for anything a terminal does better than a mouse; browser_open and browser_tabs for Chrome; office_convert and spreadsheet_read for documents. The desktop user has no root and no internet.
3. Verify. verify scores the desktop with the loaded task's checker and reports whether the episode is still valid (every gate passed). load_task swaps the task on a running computer.
4. Fork or reset. fork makes N children that continue from this exact state (the parent keeps running) to branch at a decision point; reset returns the desktop to the clean template and runs the task's setup again for another attempt. See Checkpoints, snapshots and forks.
5. Results. get_run and get_evaluation for runs submitted with create_run or create_evaluation; read_audit_log for what happened, by whom. destroy_computer with confirm: true when the desktop is no longer needed (ttl_s closes it anyway when it expires).

Safety

• Destructive tools need confirm: true from the caller. destroy_computer, delete_snapshot and revoke_api_key are refused before any network call unless the tool arguments carry confirm: true. Drums never prompts a human itself: the MCP client (Claude Code, Cursor, Codex) owns the user's approval of such a call, and a well-behaved agent tells you before it passes the flag.
• Workspace scoping. A key sees only its own workspace. A computer, snapshot, run or key of another workspace does not exist for it: the tool returns a not-found error, never a hint that the id is real.
• Scopes. Each tool needs the scope in the table; a key without it gets a forbidden error. create_api_key cannot grant more than the calling key has; only an owner or admin key may create or revoke keys; a key cannot revoke itself.
• Audit log. The gateway records every tools/call as mcp.<tool> with actor mcp and origin mcp: tool name, duration, computer id and error code, never the arguments, screenshots or file contents. The underlying actions (computer.create, api_key.revoke, ...) keep their own rows. Filter the Audit log page or read_audit_log by action mcp.
• Rate limits are the gateway's. Each MCP request takes one token from the key's bucket, and failed authentications count per source IP, exactly as for /v1; see Limits.
• Secrets. The server never prints a key. create_api_key returns the new key once, in that reply only; the agent's transcript then holds it, so use it, store it and do not paste it elsewhere.

The Claude Code plugin

The SDK repository is also a Claude Code plugin: .claude-plugin/plugin.json, a .mcp.json that starts drums mcp with DRUMS_URL and DRUMS_TOKEN from your environment, and the drums-workflow skill. The skill teaches the workflow above (templates, create, wait until ready and valid, act with screenshots after GUI actions, verify, fork at decision points, reset for another attempt, destroy with confirm when done, read results) and the rules: never destroy without telling the user, prefer shell and read_file over the GUI for checks, keep computer ids. Install it from the repository the way you install any Claude Code plugin, with the two environment variables set.

Troubleshooting

Every gateway reply carries a request id (X-Request-Id on the remote endpoint); include it when you report a problem.