MCP Connection Guide

Note

MCP v2 ships workflow-led tools. The previous job-shaped tools were removed. If your agent or client referenced them, see the v2 migration guide.

The rotor.sh MCP server exposes 12 tools that let AI agents trigger workflows, inspect runs, manage queues, and approve pending operations. Workflows are first-class. Runs are how you observe them.

Prerequisites

A rotor.sh account — sign up free
An API key — generate one at rotor.sh/dashboard/api-keys

Your key looks like rt_ws_<workspaceId>_<secret>.

Claude Code (recommended)

Claude Code supports MCP servers natively via the claude mcp add command.

claude mcp add rotor https://rotor.sh/mcp \
  --header "Authorization: Bearer $ROTOR_API_KEY"

Replace $ROTOR_API_KEY with your actual key, or set the environment variable first:

export ROTOR_API_KEY=rt_ws_your_key_here
claude mcp add rotor https://rotor.sh/mcp \
  --header "Authorization: Bearer $ROTOR_API_KEY"

Verify the connection:

claude mcp list
# Output should include:
# rotor: https://rotor.sh/mcp (12 tools)

Available tools

Tool	Description
`list_workflows`	List the workspace's registered workflow functions
`trigger_workflow`	Fire-and-forget trigger of a workflow. Returns `run_id`.
`invoke_workflow`	Synchronous wait. Polls until the run completes or times out.
`get_run`	Get full run detail including step graph
`list_runs`	List runs with filters by workflow, status, and time
`cancel_run`	Cancel a running workflow. Idempotent on terminal runs.
`upsert_queue`	Create or update a BullMQ-backed queue
`set_queue_state`	Pause, resume, or drain a queue
`drain_queue`	Destructively drain a queue (requires `confirm: true`)
`queue_stats`	Get job counts and throughput for a queue
`upsert_schedule`	Create or update a cron schedule
`approve_run`	Approve or reject a pending workflow approval

Claude Desktop

Claude Desktop reads MCP server configuration from a JSON file.

•
Open your Claude Desktop config
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json
- Linux: ~/.config/Claude/claude_desktop_config.json

•

Add the rotor MCP server

Paste the following into mcpServers (create the key if the file does not have it):

{
  "mcpServers": {
    "rotor": {
      "url": "https://rotor.sh/mcp",
      "headers": {
        "Authorization": "Bearer rt_ws_your_key_here"
      }
    }
  }
}

Replace rt_ws_your_key_here with your actual API key.

•
Restart Claude Desktop
Fully quit and reopen Claude Desktop. You should see the rotor tools available in the tools panel.

Cursor

Cursor supports MCP via its settings panel or a config file.

Via Cursor Settings UI

Open Cursor Settings (Cmd/Ctrl + ,)
Navigate to Features → Model Context Protocol
Click Add MCP Server
Enter:
- Name: rotor
- URL: https://rotor.sh/mcp
- Auth Header: Authorization: Bearer rt_ws_your_key_here

Via Config File

Add to your Cursor MCP config (usually ~/.cursor/mcp.json):

{
  "servers": {
    "rotor": {
      "url": "https://rotor.sh/mcp",
      "headers": {
        "Authorization": "Bearer rt_ws_your_key_here"
      }
    }
  }
}

Restart Cursor after saving.

Verify the connection

Regardless of which client you use, verify the MCP server is responding by asking the AI assistant:

"List my rotor workflows"

"Trigger the lead-enrichment workflow with email [email protected]"

"What was the result of run abc-123?"

The assistant should call the appropriate tool and return data from your workspace.

Troubleshooting

Tools not appearing after connecting:

Ensure your API key starts with rt_ws_ (workspace-scoped key required)
Check the key is not expired — generate a fresh one from dashboard/api-keys
Restart the AI client after changing the config

401 Unauthorized errors:

Verify the Authorization: Bearer ... header is correctly formatted
Ensure no extra whitespace around the key value

Connection timeout:

The MCP endpoint is https://rotor.sh/mcp (not the API base URL https://api.rotor.sh)
Check your network is not blocking SSE connections (some corporate proxies do)

What changed in v2

The MCP surface was redesigned to put workflows at the center. If you used the previous job-shaped tools, the v2 migration guide maps every removed tool to its replacement.

Need help? Open an issue on GitHub or reach out in the Anthropic Discord #rotor channel.