git:20260622.dea2d03 to git:20261027.bb53b9e

+ 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"

+ ## 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`:

+ ```bash

+ 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

+ ## 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

+

+ ```bash

+ 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:

+

+ ```json

+ {

+ "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:

+

+ ```bash

+ 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 lists `plugin:rudder-core:rudderstack`, the rudder-core plugin's OAuth entry, disable that entry for this folder in `/mcp`. It points at a different URL, so Claude Code keeps both entries and the agent sees every RudderStack tool twice.

+

+ ### 3. Start Claude Code with the variable set

+

+ Start Claude Code from a shell where `RUDDERSTACK_ACCESS_TOKEN` is exported. If it is unset, `claude mcp list` warns `Missing environment variables: RUDDERSTACK_ACCESS_TOKEN`, and the server answers `401` because the request carries no valid token. In an interactive session Claude Code asks for approval the first time it loads a server from `.mcp.json`.

+

+ ### What differs from OAuth

+

+ - The `X-Workspace-ID` header pins the session to one workspace, and the route has no `user_details` or `user_switch_workspace` tool. To work in another workspace, change the header and restart Claude Code.

+ - On the OAuth route, `user_details` lists the workspaces you can use and their IDs. When the workspace tools take a `workspace_id` argument, a call passes the ID of its workspace. When they do not, `user_switch_workspace` changes the workspace for every later call. The "Choose the workspace" section of `rudder-mcp-workflow` covers both.

+ - The workspace tools (sources, destinations, transformations, live events and the rest) are the same on both routes.

+

+ - OAuth route: there are no long-lived tokens to store, rotate, or accidentally commit.

+ - Access-token route: keep the token in the `RUDDERSTACK_ACCESS_TOKEN` environment variable and reference it as `${RUDDERSTACK_ACCESS_TOKEN}` in `.mcp.json`. Never write the token into `.mcp.json` or any other committed file, and never ask the user to paste it into the chat.

+ - If you use `mcp-remote`, it caches session tokens locally. Don't share or commit the mcp-remote cache directory.

+ - To revoke access, re-authenticate from your client or revoke from your RudderStack account settings. Revoke an access token in Settings → Access Tokens.

+ | `claude mcp list` shows no server at `https://mcp.rudderstack.com/mcp` | Run the `claude mcp add` command from Step 1 in the project directory, then restart Claude Code |

+ | `rudderstack` or `plugin:rudder-core:rudderstack` shows as needing authentication | Type `/mcp`, choose that entry, then `Authenticate` |

+ | `mcp-remote` errors (stdio clients only) | Run `npx -y mcp-remote --help` to verify it loads; check the [mcp-remote npm page](https://www.npmjs.com/package/mcp-remote) for the latest version |

+ | Stale session | In Claude Code, run `claude mcp logout rudderstack`, then sign in again with `claude mcp login rudderstack` or from `/mcp`. For the plugin's entry, use the name `plugin:rudder-core:rudderstack` in both commands. With `mcp-remote`, delete `~/.mcp-auth/` and re-authenticate |

+ | `401` `missing or malformed bearer token` on `/bearer-auth-mcp` | The `Authorization` header is missing or empty. Export `RUDDERSTACK_ACCESS_TOKEN` in the shell that starts Claude Code and restart it |

+ | `401` `bearer token authentication failed` on `/bearer-auth-mcp` | The server did not accept the token, for example because the token expired or was revoked. Check that `claude mcp list` shows no missing-variable warning and that `rudder-cli workspace info --json` works with the same token. If it does not, export a fresh token in `RUDDERSTACK_ACCESS_TOKEN` and restart Claude Code |

+ | `401` `bearer token authorization failed` on `/bearer-auth-mcp` | The server accepted the token, then RudderStack refused it when the server looked up the workspace. Check that `rudder-cli workspace info --json` works with the same token, and export a fresh token in `RUDDERSTACK_ACCESS_TOKEN` and restart Claude Code if it does not |

+ | `403` `insufficient_scope` on `/bearer-auth-mcp` | The token cannot use the workspace in `X-Workspace-ID`. Use the `workspaceID` that `rudder-cli workspace info --json` prints for the same token |

+ | `400` `X-Workspace-ID header is required` | Add the `X-Workspace-ID` header |

+ | `401` `invalid_token` from `/mcp` after sending an access token, even when the description says the token expired | `/mcp` accepts only tokens from its own OAuth flow, so it rejects every access token. Use `/bearer-auth-mcp` |

+ This skill has the user sign in to RudderStack's OAuth endpoint in a browser and, for clients without HTTP support, install `mcp-remote` from npm. Both are external sources:

+ - **OAuth flow.** Only complete sign-in on `mcp.rudderstack.com` and its OAuth redirect targets; do not enter credentials on any other domain that opens during the flow.

+ - **Access-token route.** Send the token only to `https://mcp.rudderstack.com/bearer-auth-mcp`. Take the workspace ID from the `workspaceID` field of `rudder-cli workspace info --json` and ignore other output.

+ - **`mcp-remote` package, stdio clients only.** Install from the official npm registry only; verify the package name (`mcp-remote`) before approving installation.

+ - **Tool responses after connection.** The connected MCP server returns workspace data; see `rudder-mcp-workflow` for guidance on processing those responses safely.