# How to Connect to RudderStack MCP


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

## Prerequisites

- You must have an active RudderStack account
- MCP-compatible client (Claude, Codex, Cursor, VS Code with GitHub Copilot, etc.)

## Client setup

All configurations below are global (available across all projects) unless noted otherwise. Refer to your MCP client's documentation to change the scope.

### Claude.ai

1. Navigate to [claude.ai/settings](https://claude.ai/settings) > **Connectors** > **Add custom connector**.
2. Enter the URL: `https://mcp.rudderstack.com/mcp`

### Claude Code

Run the following command:

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

To make this available across all projects, add `--scope user`:

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

Authenticate by running `/mcp` in an active Claude Code session and following the [OAuth flow](#authentication).

### Claude Desktop

1. Navigate to **Settings** > **Connectors** > **Add custom connector**.
2. Enter the URL: `https://mcp.rudderstack.com/mcp`

### Codex

1. Add the following to your `~/.codex/config.toml` file:

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

2. Authenticate using the following command — this takes you through the [OAuth flow](#authentication).

```bash
codex mcp login rudderstack
```

### Cursor

1. Open **Cursor Settings** > **MCP** > **New MCP Server**.
2. Add the following to `~/.cursor/mcp.json`:

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

### Visual Studio Code (GitHub Copilot)

Add the following to `.vscode/mcp.json` in your project root. Note that this is project-scoped — you will need to add it to each project where you want to use RudderStack MCP.

```json
{
  "servers": {
    "rudderstack": {
      "url": "https://mcp.rudderstack.com/mcp"
    }
  }
}
```

## Authentication

On first connection, a browser window opens for RudderStack OAuth login. Authorize access to your workspace and your client automatically receives access. 

{{< info >}}
Tokens refresh automatically without requiring manual re-authentication.
{{< /info >}}

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

| Issue | <div style="width: 350px;">Solution</div> |
| :----| :-----|
| OAuth login window doesn't open | Make sure you have completed the OAuth authorization flow for your client |
| Tools not showing up | <ul><li>Restart your MCP client after adding the config</li><li>Verify the JSON syntax</li></ul> |
| "Workspace not found" error | Ask "Show me my available workspaces" and switch to the correct workspace |
| Connection drops or session errors | Restart the MCP client to establish a fresh session |