/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`. See `rudder-mcp-setup` for the Claude Code walkthrough; the official docs cover Claude Desktop, Cursor, VS Code, Windsurf, and the claude.ai web UI.
• [ ] OAuth flow completed (browser sign-in to your RudderStack account on first tool use).
• [ ] `mcp.rudderstack.com` is reachable on port 443 from your network.

Client configuration

Claude Code `mcpServers` block (HTTP transport via `mcp-remote`):

{
  "mcpServers": {
    "rudderstack": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.rudderstack.com/mcp"]
    }
  }
}

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

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 transformations, draft a new one, run it against captured payloads, then save.
• **"Live-debug this connection."** — inspect live events for the source and correlate with recent destination errors.

Instrumentation Verification Workflow

After instrumenting events (via CLI, Terraform, or code), verify they reach destinations:

1. APPLY TRACKING PLAN
   └── e.g. rudder-cli apply -l ./

2. TRIGGER EVENTS
   └── Run your app, trigger the instrumented events

3. VERIFY LIVE EVENTS
   └── Ask Claude: "show recent live events from source <id>"
   └── Confirm event name, properties, context match the tracking plan

4. VERIFY DESTINATION
   └── For warehouse destinations: query the warehouse
       (Snowflake, BigQuery, Redshift, etc.) for the event
   └── For SaaS destinations: check the destination UI

5. CHECK FOR VIOLATIONS
   └── Ask Claude: "any tracking-plan violations on source <id>?"
   └── Review violations to identify schema mismatches

Example: Verifying an "Audience Created" event

1. Apply tracking plan with "Audience Created" event
2. Create an audience in the web app
3. Ask Claude: "any Audience Created events on source <id> in the last hour?"
4. Verify properties: audience_id, audience_name, condition_count
5. Confirm the event landed in your warehouse destination

Dev vs Prod Workspace Pattern

Recommended for safe iteration:

| Workspace | Purpose | Governance | |-----------|---------|------------| | Dev | Testing, iteration | `unplannedEvents: log` | | Prod | Production traffic | `unplannedEvents: block` |

Workflow:

1. Point your MCP client at the Dev workspace
   (your MCP client surfaces a workspace-switch tool if your account
    has access to multiple workspaces)

2. Apply changes to Dev
   └── e.g. rudder-cli apply -l ./

3. Verify events end-to-end in Dev
   └── Live events + warehouse check via MCP

4. Switch to the Prod workspace and apply

**Why two workspaces:**

• **Safe iteration** — test tracking-plan changes without affecting production
• **End-to-end validation** — trigger events in Dev, verify in Dev's warehouse
• **Early violation detection** — schema mismatches surface in Dev before prod

Don't do this

• Don't run mutating tools (transformation upserts, destination connection changes, workspace switches) without confirming the target workspace and resource with the user — these affect shared workspace state.
• Don't assume a specific tool name; the server evolves and your client's discovered tool list is the source of truth.
• Don't rely on the MCP to discover workspace **account IDs**. The MCP only surfa