How to Set Up RudderStack MCP

This guide covers the steps to connect your AI assistant to RudderStack MCP for pipeline debugging and management.

Client setup overview

RudderStack MCP is a hosted remote server that uses Streamable HTTP at https://mcp.rudderstack.com/mcp. The server uses OAuth 2.0 with PKCE and dynamic client registration, so don’t add a RudderStack access token, client secret, or other static credential to your MCP client configuration.

Each section below notes whether the configuration is global (available across all your projects) or project-scoped. Refer to your MCP client’s documentation to change the scope.

Prerequisites

• Sign up for an active RudderStack account.
• Install an MCP-compatible client, such as Claude, Codex, Cursor, or VS Code with GitHub Copilot.

Claude.ai

1. Navigate to claude.ai/settings > Connectors > Add custom connector.
2. Enter RudderStack as the connector name and https://mcp.rudderstack.com/mcp as the remote MCP server URL.
3. Select Add and complete RudderStack authorization when prompted.

Claude Code

Add RudderStack MCP to the current project:

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

To make the server available to you across all projects, use user scope:

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

In an active Claude Code session, run /mcp, select rudderstack, and choose Authenticate if prompted. Then, complete the OAuth flow in your browser.

Claude Desktop

1. Navigate to Settings > Connectors > Add custom connector.
2. Enter RudderStack as the connector name and https://mcp.rudderstack.com/mcp as the remote MCP server URL.
3. Select Add and complete RudderStack authorization when prompted.

Codex

Add RudderStack MCP as a global Streamable HTTP server:

codex mcp add rudderstack --url https://mcp.rudderstack.com/mcp

If Codex doesn’t start the OAuth flow automatically, run:

codex mcp login rudderstack

Then, complete the OAuth flow in your browser.

Alternatively, add the following configuration to ~/.codex/config.toml before running the login command:

[mcp_servers.rudderstack]
url = "https://mcp.rudderstack.com/mcp"

Cursor

Add the following configuration to your global ~/.cursor/mcp.json file:

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

Open Cursor Settings > Tools & Integrations > MCP Tools, enable rudderstack, and select Connect or Login if prompted. Then, complete the OAuth flow in your browser.

To share the configuration with a project instead, add the same configuration to .cursor/mcp.json in the project root.

Visual Studio Code (GitHub Copilot)

Add the following configuration to .vscode/mcp.json in your project root:

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

This is the VS Code-specific format. VS Code now prefers the portable .mcp.json format at your workspace root, which uses a top-level mcpServers object instead.

Save the file and select Start in the CodeLens above the server. If Auth appears, select it and complete the OAuth flow in your browser.

This configuration is project-scoped. For a personal configuration available across projects:

1. Run MCP: Add Server.
2. Select HTTP (HTTP or Server-Sent Events).
3. Enter https://mcp.rudderstack.com/mcp.
4. Enter rudderstack as the server ID.
5. Select Copilot Global to make the server available across all your projects.

Other MCP clients

For any client that supports remote MCP servers:

1. Add a remote server named rudderstack.
2. Select Streamable HTTP as the transport, if the client asks for one.
3. Enter https://mcp.rudderstack.com/mcp as the server URL.
4. Connect to the server and complete the OAuth flow in your browser.

Configuration field names vary by client. You only need the hosted server URL. Don’t configure a local command or static credentials.

Authentication

Your client starts the OAuth flow on the first connection, or when you select its authentication action. Complete authorization in the browser window that opens, or open the authorization URL the client shows. The server accesses only the workspaces and resources available to your RudderStack user.

Compatible clients store and refresh OAuth credentials automatically. You may need to authenticate again if authorization is revoked or the refresh token expires.

Verify your connection

Ask your AI assistant:

“Give me an overview of my RudderStack workspace.”

You should see your sources, destinations, and connections listed.

Troubleshooting

See more

• RudderStack MCP Tool Reference: Lists every hosted tool, its access class, and the permissions it requires.
• RudderStack MCP: Covers capabilities, example prompts, and security considerations.