Terminal
Terminal/Skill
Connects Claude Code to RudderStack's hosted MCP server through an OAuth sign-in, by editing the config or running a command.
By RudderStack
Works with
npx skills add rudderlabs/rudder-agent-skills --skill rudder-mcp-setupConfigure Claude Code to connect to RudderStack's hosted MCP server at mcp.rudderstack.com. Authoritative reference: https://mcp.rudderstack.com/docs.
1. Check Prerequisites ──► which npx
│
├── Found ──► Configure Claude Code
│
└── Not Found ──► Install Node.js first
2. Configure Claude Code
│
├── Option A: /mcp command (recommended)
│
└── Option B: Edit settings.json directly
3. Authenticate (OAuth) ──► Browser opens, sign in to RudderStack
4. Verify Connection ──► Restart Claude, list workspace resources
which npx
If found: Continue to Step 2.
If not found: Install Node.js first from https://nodejs.org/ (includes npx).
/mcp add rudderstack
Follow the prompts:
rudderstackhttp (via mcp-remote)https://mcp.rudderstack.com/mcpEdit your Claude Code settings file.
| Platform | Path |
|---|---|
| macOS / Linux | ~/.claude/settings.json |
| Windows | %APPDATA%\claude\settings.json |
Add under mcpServers:
{
"mcpServers": {
"rudderstack": {
"command": "npx",
"args": ["-y", "mcp-remote", "https://mcp.rudderstack.com/mcp"]
}
}
}
The first time you invoke an MCP tool, mcp-remote opens your browser:
No long-lived tokens to manage — OAuth handles the handshake per session.
After configuration, restart Claude Code:
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.
When connected, your MCP client discovers tools covering five categories (per https://mcp.rudderstack.com/docs):
See /rudder-mcp-workflow for workflow patterns that combine these.
The same hosted server works with Claude Desktop, Cursor, VS Code, Windsurf, and the claude.ai web UI (Team / Enterprise / Individual Paid plans get a one-click connector under claude.ai/settings/connectors). For per-client config snippets, see https://mcp.rudderstack.com/docs.
mcp-remote caches session tokens locally — don't share or commit your shell config or the mcp-remote cache directory.| Issue | Solution |
|---|---|
npx: command not found | Install Node.js from https://nodejs.org/ |
| MCP server not responding | Verify https://mcp.rudderstack.com is reachable; check network/proxy |
| Authentication failed | Clear browser cookies for the RudderStack domain and retry; verify your account is active |
| Tools not appearing | Restart Claude Code; check settings.json syntax with python3 -m json.tool ~/.claude/settings.json |
mcp-remote errors | Run npx -y mcp-remote --help to verify it loads; check the mcp-remote npm page for the latest version |
| Stale session | Delete the mcp-remote cache (~/.mcp-auth/) and re-authenticate |
If the connection remains broken after these steps, contact your RudderStack administrator.
Outbound HTTPS access to mcp.rudderstack.com (port 443). If behind a corporate proxy, ensure this domain is allowed.
This skill instructs the agent to open a browser to RudderStack's OAuth endpoint and to install mcp-remote from npm — both are external sources:
mcp.rudderstack.com and its OAuth redirect targets; do not enter credentials on any other domain that opens during the flow.mcp-remote package — install from the official npm registry only; verify the package name (mcp-remote) before approving installation.rudder-mcp-workflow for guidance on processing those responses safely./rudder-environment-check to verify your full environment/rudder-mcp-workflow for MCP-based workflow patterns