Title: MCP 接入
Locale: zh
URL: https://sensorswave.com/docs/ai/mcp/
Description: 在 Cursor、VS Code、Claude、Codex 中接入 Wave MCP，并把 AI Agent 连到项目级能力。
Wave MCP 是 AI Agent 接入 Sensors Wave 的标准入口。完成接入后，AI Agent 可以在您授权的项目范围内读取元数据、创建埋点计划、查询分析结果，并配合 Wave Skills 执行更完整的工作流。

如果您希望把埋点设计和数据分析工作流一起交给 AI Agent，请继续阅读 [Wave Skills](wave-skills.mdx)。

## 前提条件

在连接 AI Agent 之前，请先确认：

- 您可以登录 Wave 控制台，并且拥有组织与项目的访问权限。
- 所使用的 AI Agent 工具支持 MCP，并能完成 OAuth 登录流程。
- 当前网络可以正常访问 Wave 控制台和 `https://app.sensorswave.com/api/mcp`。
- 如果您仅使用 Codex CLI，需要先在 `~/.codex/config.toml` 中开启 `experimental_use_rmcp_client = true`，再执行 `codex mcp login`。

连接后可使用的能力会受到当前账号权限控制。

## 接入地址

以下示例统一使用：

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

首次连接时在 AI Agent 所在工具内完成 **使用 Wave 账号登录（OAuth）**，并选择要让 AI Agent 操作的业务组织与项目。

## 接入配置

### Cursor

1. 打开 **Settings → Tools & MCP → New MCP Server**（或编辑 `~/.cursor/mcp.json`）。
2. 写入：

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

3. 保存后按提示完成 Wave 登录。

### Visual Studio Code

1. 命令面板执行 **MCP: Open User Configuration**（说明见 [在 VS Code 中管理 MCP](https://code.visualstudio.com/docs/copilot/customization/mcp-servers)）。
2. 添加：

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

3. 保存后在 Copilot 或 MCP 面板中触发连接并完成 OAuth。

### Claude Code（终端 CLI）

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

需要继续授权或查看状态时，在 Claude Code 中使用 `/mcp`。

### Claude 桌面版（Claude Desktop）

1. **Claude → Settings → Developer → Edit Config**，编辑 `claude_desktop_config.json`。
2. 增加：

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

3. 重启应用并在提示时完成登录。

### Codex（桌面应用或 VS Code 扩展）

1. **Settings → MCP Servers** → 添加服务器。
2. 类型选 **Streamable HTTP**，URL 填 `https://app.sensorswave.com/api/mcp`。
3. 执行 **`codex mcp login sensorswave`** 或使用应用内的授权流程完成一次登录。

### 仅使用 Codex CLI 时

在 `~/.codex/config.toml` 中写入：

```toml
experimental_use_rmcp_client = true

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

然后执行：

```bash
codex mcp login sensorswave
```

更多选项见 [Codex MCP 文档](https://developers.openai.com/codex/mcp)。

## 接入后能做什么

完成 MCP 接入后，AI Agent 通常可以在您当前项目里执行以下工作：

- 读取项目、事件、属性、指标、分群等元数据
- 查询事件分析、漏斗分析、留存分析、用户列表和 SQL 分析结果
- 创建 Pipeline、Tracking Plan、Dashboard 等项目资产
- 获取 SDK 初始化信息，生成埋点或分析相关代码片段

如果您还安装了 [Wave Skills](wave-skills.mdx)，AI Agent 会进一步把这些工具能力组织成可复用的工作流。

## 常见问题

- **结果不对或为空**：回忆连接时选择的项目；若当前 AI Agent 工具支持切换数据范围，请在设置中改选项目。
- **无法连接**：检查网络或 VPN，以及示例中的主机名是否与你在浏览器中打开 Wave 时一致。
- **Codex CLI 无法完成登录**：确认 `~/.codex/config.toml` 中已添加 `experimental_use_rmcp_client = true`，然后重新执行 `codex mcp login sensorswave`。
- **AI Agent 已连接但不会做事**：MCP 只提供工具接入；如果您希望 AI Agent 自动按埋点设计或数据分析流程工作，请继续配置 [Wave Skills](wave-skills.mdx)。

连接完成后，您可以直接在 AI Agent 所在工具中发起提问，并根据当前项目权限查看可用能力。