Title: MCP Setup
Locale: en
URL: https://sensorswave.com/en/docs/ai/mcp/
Description: Connect Wave MCP from Cursor, VS Code, Claude, and Codex, and expose project-scoped Wave capabilities to your AI Agent.
Wave MCP is the standard way to connect AI Agents to Sensors Wave. After setup, the AI Agent can work inside your authorized project scope to read metadata, create tracking assets, query analysis results, and collaborate with Wave Skills on higher-level workflows.

If you want AI Agents to handle tracking design and analytics workflows more systematically, continue with [Wave Skills](wave-skills.mdx).

## Prerequisites

Before you connect an AI Agent to Wave, make sure that:

- You can sign in to the Wave console and have access to the target organization and project.
- Your AI Agent tool supports MCP and can complete an OAuth sign-in flow.
- Your network can reach the Wave console and `https://app.sensorswave.com/api/mcp`.
- If you use Codex CLI only, you enable `experimental_use_rmcp_client = true` in `~/.codex/config.toml` before running `codex mcp login`.

The capabilities available after sign-in are determined by your current account permissions.

## Endpoint

All examples below use:

```text
https://app.sensorswave.com/api/mcp
```

First connection: complete **Sign in with Wave** (OAuth) in the AI Agent tool, then choose the organization and project you want the AI Agent to use.

## Setup

### Cursor

1. Open **Settings → Tools & MCP → New MCP Server** (or edit `~/.cursor/mcp.json`).
2. Add:

```json
{
  "mcpServers": {
    "sensorswave": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://app.sensorswave.com/api/mcp"]
    }
  }
}
```

3. Save and finish the Wave login prompt when the tools connect.

### Visual Studio Code

1. Run **MCP: Open User Configuration** (see [MCP servers in VS Code](https://code.visualstudio.com/docs/copilot/customization/mcp-servers)).
2. Add:

```json
{
  "servers": {
    "sensorswave": {
      "type": "http",
      "url": "https://app.sensorswave.com/api/mcp"
    }
  }
}
```

3. Save, trigger a connection from Copilot or the MCP panel, and complete OAuth.

### Claude Code (CLI)

```bash
claude mcp add --transport http sensorswave https://app.sensorswave.com/api/mcp
```

Use `/mcp` in Claude Code if you need to finish authorization or check status.

### Claude Desktop

1. **Claude → Settings → Developer → Edit Config** (`claude_desktop_config.json`).
2. Add:

```json
{
  "mcpServers": {
    "sensorswave": {
      "type": "http",
      "url": "https://app.sensorswave.com/api/mcp"
    }
  }
}
```

3. Restart Claude Desktop and sign in when prompted.

### Codex (app or VS Code extension)

1. **Settings → MCP Servers** → add a server.
2. Type **Streamable HTTP**, URL `https://app.sensorswave.com/api/mcp`.
3. Run **`codex mcp login sensorswave`** or use the in-app OAuth flow once.

### Codex CLI

In `~/.codex/config.toml`:

```toml
experimental_use_rmcp_client = true

[mcp_servers.sensorswave]
url = "https://app.sensorswave.com/api/mcp"
```

Then:

```bash
codex mcp login sensorswave
```

More detail: [Codex MCP](https://developers.openai.com/codex/mcp).

## What you can do after setup

After MCP is connected, the AI Agent can typically:

- Read projects, events, properties, metrics, cohorts, and other project metadata
- Run event analysis, funnel analysis, retention analysis, user list queries, and SQL analysis
- Create Pipelines, Tracking Plans, Dashboards, and related project assets
- Retrieve SDK initialization info and generate tracking or analysis code snippets

If you also install [Wave Skills](wave-skills.mdx), the AI Agent can turn those tools into reusable task flows.

## Troubleshooting

- **Wrong or empty results**: Re-check which project you selected when authorizing; switch scope in the AI Agent tool if it allows.
- **Cannot connect**: Verify network or VPN access and that the host matches the URL you use to open Wave in the browser.
- **Codex CLI cannot complete login**: Confirm `experimental_use_rmcp_client = true` is present in `~/.codex/config.toml`, then run `codex mcp login sensorswave` again.
- **AI Agent is connected but still does not follow a workflow**: MCP only exposes tools. If you want the AI Agent to follow structured tracking or analytics workflows, set up [Wave Skills](wave-skills.mdx).

After MCP is connected, you can start asking questions in the AI Agent tool and inspect which capabilities are available in the current project scope.