/rudder-mcp-workflow

name: rudder-mcp-workflow
description: Connects AI agents to RudderStack via MCP tool calls for catalog, sources, destinations, transformations, and live events. Use when connecting an AI agent to RudderStack's MCP server, driving RudderStack via MCP, or mentions of mcp.rudderstack.com.
allowed-tools: "Read, Write, Edit"

RudderStack MCP Workflow

RudderStack's hosted MCP server at `mcp.rudderstack.com` exposes a RudderStack workspace as an MCP endpoint so AI agents (Claude Code, Claude Desktop, Cursor, VS Code, Windsurf, or any MCP client) can inspect and drive workspace resources via tool calls. Authoritative docs: https://mcp.rudderstack.com/docs.

When to use

The user wants an AI agent to drive RudderStack, mentions RudderStack + MCP, asks about `mcp.rudderstack.com`, or wants to configure MCP tool access for a RudderStack workspace.

Preflight

Before running any workflow, verify:

• [ ] Your MCP client is configured to connect to `https://mcp.rudderstack.com/mcp` (OAuth, the default) or `https://mcp.rudderstack.com/bearer-auth-mcp` (access token). See `rudder-mcp-setup` for the Claude Code walkthrough of both; the official docs cover Claude Desktop, Cursor, VS Code, Windsurf, and the claude.ai web UI.
• [ ] OAuth route: browser sign-in to your RudderStack account completed on first tool use. Access-token route: `RUDDERSTACK_ACCESS_TOKEN` was exported in the shell that started the client, and the `X-Workspace-ID` header holds the workspace ID.
• [ ] `mcp.rudderstack.com` is reachable on port 443 from your network.

Client configuration

If `claude mcp list` already shows a server at `https://mcp.rudderstack.com/mcp` or `https://mcp.rudderstack.com/bearer-auth-mcp`, under `plugin:rudder-core:rudderstack` (the rudder-core plugin's entry) or any other name, use it and add nothing. For an `/mcp` entry, choose it in `/mcp` and `Authenticate`. A `/bearer-auth-mcp` entry has no sign-in, so check that `RUDDERSTACK_ACCESS_TOKEN` is exported in the shell that started the client, as the access-token route in `rudder-mcp-setup` says. Adding a server under a name that the project's `.mcp.json` already uses writes a local entry that hides the project's one.

Otherwise, Claude Code connects over HTTP and runs the OAuth sign-in itself, with no `npx` or `mcp-remote`:

claude mcp add --transport http rudderstack https://mcp.rudderstack.com/mcp

That command writes this `mcpServers` entry, to your Claude Code config by default or to the project's `.mcp.json` with `--scope project`:

{
  "mcpServers": {
    "rudderstack": {
      "type": "http",
      "url": "https://mcp.rudderstack.com/mcp"
    }
  }
}

Then type `/mcp`, choose `rudderstack` and `Authenticate`, or run `claude mcp login rudderstack` from a terminal. For the plugin's entry, the name in `/mcp` and in `claude mcp login` is `plugin:rudder-core:rudderstack`. `rudder-mcp-setup` has the full walkthrough. A client without HTTP support runs `npx -y mcp-remote https://mcp.rudderstack.com/mcp` as a stdio command instead.

For headless sessions that cannot open a browser, `rudder-mcp-setup` shows the access-token route: `https://mcp.rudderstack.com/bearer-auth-mcp` with `Authorization: Bearer ${RUDDERSTACK_ACCESS_TOKEN}` and `X-Workspace-ID` headers in `.mcp.json`. That route pins one workspace and has no `user_details` or `user_switch_workspace` tools.

For other clients (Claude Desktop, Cursor, VS Code, Windsurf, claude.ai connectors), use the snippets at https://mcp.rudderstack.com/docs.

Choose the workspace

On the OAuth route, call `user_details` first. It lists the workspaces your account can use and their IDs. How a call picks its workspace depends on the server version, so check the tool list:

• When the workspace tools take a `workspace_id` argument, pass the ID of the target workspace on every call. A call without it fails with `workspace_id is required`.
• When they do not, the tool list has `user_switch_workspace`. Call it with the target workspace's ID before the other calls. It changes the workspace for every later call in the session, so confirm the target with the user first.

On the access-token route, the `X-Workspace-ID` header picks the workspace for every call. To work in another workspace, change the header and restart the client.

Tool catalog

The server exposes tools across five categories. Exact names are discovered dynamically by your MCP client — inspect your client's tools panel (or ask Claude "what RudderStack tools do you have?") for the authoritative list. The names below are representative.

Data sources

List sources and fetch a specific source's details, definitions, event schemas, event metrics, and the tracking plan(s) bound to it. Useful for: "what's broken in source X?", "what events does source X emit?".

Destinations

List destinations and fetch a specific destination's details, definitions, event metrics, latency metrics, and recent errors. Useful for: "why is destination X dropping events?", "compare event volume across destinations".

Transformations

List transformations and libraries, fetch a specific transformation, create or update transformations, and test them against captured payloads. Useful for: "draft a transformation for use case X", "test this transformation against last week's events".

Events

Stream and inspect live events flowing through your workspace. Useful for: "show me the last 10 events from source X", "did the 'Order Completed' event land with the right properties?".

Documentation

Search RudderStack documentation from inside your client. Useful for: "how does RETL handle late-arriving rows?", "what destination types support transformations?".

Common workflows

Patterns to ask Claude — phrased as a user would say them:

• **"What's broken in my sources?"** — list sources, then for each one check event metrics and tracking-plan violations.
• **"Draft a transformation and test it."** — find similar existing trans