/rudder-mcp-setup

name: rudder-mcp-setup
description: Configures Claude Code to connect to RudderStack's MCP server at mcp.rudderstack.com. Use when setting up MCP for rudderstack, connecting claude to rudderstack, or configuring the rudderstack MCP server
allowed-tools: "Bash(rudder-cli workspace info *), Bash(claude mcp add --transport http rudderstack https://mcp.rudderstack.com/mcp), Bash(claude mcp list), Read, Write, Edit"

RudderStack MCP Setup

Configure Claude Code to connect to RudderStack's hosted MCP server at `mcp.rudderstack.com`. Authoritative reference: https://mcp.rudderstack.com/docs.

Choose an auth route

The server accepts two kinds of credentials on two endpoints:

| Route | Endpoint | Credential | Use it for | |-------|----------|------------|------------| | OAuth (default) | `https://mcp.rudderstack.com/mcp` | Browser sign-in, run by the client | People and coding agents in an interactive client | | Access token | `https://mcp.rudderstack.com/bearer-auth-mcp` | `Authorization: Bearer <token>` plus `X-Workspace-ID: <workspace id>` headers | Headless sessions that cannot open a browser, such as CI |

Use OAuth, coding agents included. Use the access-token route only when the session cannot open a browser. The access-token route is in [Access-token route](#access-token-route) below; Steps 1 to 3 cover OAuth.

Setup workflow (OAuth)

1. Add the server ──► claude mcp add --transport http rudderstack https://mcp.rudderstack.com/mcp
2. Sign in (OAuth) ──► /mcp, choose rudderstack, Authenticate, approve in the browser
3. Verify ──► list the sources in one of your workspaces

Step 1: Add the server

Run `claude mcp list` first. If it shows a server at `https://mcp.rudderstack.com/mcp`, under `plugin:rudder-core:rudderstack` (the rudder-core plugin's entry) or any other name, the server is already added. Skip this step and authenticate that entry in Step 2. Adding `rudderstack` as well is redundant. Claude Code hides a plugin's server when a server you added has the same URL, so `/mcp` would then list only `rudderstack`.

Claude Code talks to the server over HTTP and runs the OAuth sign-in itself, so it needs no `npx` or `mcp-remote`:

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

The default scope is this project, for you only. Add `--scope project` to write it to the project's `.mcp.json` for everyone who clones the repository, or `--scope user` for all your projects.

Other clients take the same URL as an HTTP (streamable HTTP) MCP server in their MCP settings. A client without HTTP support can run `npx -y mcp-remote https://mcp.rudderstack.com/mcp` as a stdio command instead.

Step 2: Sign in (OAuth)

Start Claude Code, or restart it if it was running when you added the server. Type `/mcp`, choose `rudderstack` (or the entry Step 1 found), then `Authenticate`. The browser opens:

1. Sign in with your RudderStack account 2. Review and approve the requested access 3. The browser redirects back and Claude Code reports that it is connected

From a terminal, `claude mcp login rudderstack` does the same sign-in before you start Claude Code. For the plugin's entry, run `claude mcp login plugin:rudder-core:rudderstack`. With only that entry, `claude mcp login rudderstack` answers `No MCP server named "rudderstack"`. No long-lived token is stored in the project. The sign-in belongs to you and this client.

Step 3: Verify connection

Test the Connection

Ask Claude to inspect your workspace:

List my RudderStack sources

**If connected:** Claude lists the sources in your workspace.

**If not connected:** Claude reports the MCP server is unavailable — see Troubleshooting below.

What Becomes Available

When connected, your MCP client discovers tools covering five categories (per https://mcp.rudderstack.com/docs):

• **Data sources** — list and inspect configured sources
• **Destinations** — list and inspect destinations and their metrics
• **Transformations** — list, view, create, and test transformations
• **Events** — stream and inspect live events
• **Documentation** — search RudderStack docs from inside Claude

See `/rudder-mcp-workflow` for workflow patterns that combine these.

Access-token route

`https://mcp.rudderstack.com/bearer-auth-mcp` takes a RudderStack access token, the same token rudder-cli reads from `RUDDERSTACK_ACCESS_TOKEN`, so a session that cannot open a browser can still reach the MCP server. The endpoint uses the streamable HTTP transport, so it needs no `mcp-remote` or `npx`.

Two headers are required:

• `Authorization: Bearer <token>`
• `X-Workspace-ID: <workspace id>`. Without it the server answers `400` with `X-Workspace-ID header is required`.

1. Get the workspace ID

rudder-cli workspace info --json

Use the `workspaceID` field. If the command fails, set up the token first with `rudder-cli-setup`. Never ask the user to paste a token into the chat.

2. Add the server to the project

Write `.mcp.json` at the project root:

{
  "mcpServers": {
    "rudderstack": {
      "type": "http",
      "url": "https://mcp.rudderstack.com/bearer-auth-mcp",
      "headers": {
        "Authorization": "Bearer ${RUDDERSTACK_ACCESS_TOKEN}",
        "X-Workspace-ID": "<workspaceID from step 1>"
      }
    }
  }
}

Claude Code expands `${RUDDERSTACK_ACCESS_TOKEN}` from its environment when it connects, so the file holds the variable name and never the token. The workspace ID is an identifier, not a secret.

Or write the same entry with the CLI:

claude mcp add --scope project --transport http rudderstack https://mcp.rudderstack.com/bearer-auth-mcp --header 'Authorization: Bearer ${RUDDERSTACK_ACCESS_TOKEN}' --header "X-Workspace-ID: <workspaceID from step 1>"

Keep the single quotes around the `Authorization` header. With double quotes the shell substitutes the token before `claude` runs, and the token is written into `.mcp.json`.

If `/mcp` also li