# MCP Server 接入

> 来源：https://help.gravity-engine.com/docs/server-integration/mcp
> 说明如何把引力引擎 MCP Server 接入 Codex、Claude Code、Cursor 等支持 MCP 的 AI 客户端，涵盖 OAuth 自动授权、APIKey 固定授权、可用工具与常见问题。
> 文档修改日期：2026-10-29




## 1 什么是引力引擎 MCP [#1-什么是引力引擎-mcp]

引力引擎 MCP 是一个由引力引擎托管的远程 MCP 服务。接入后，你可以直接在 Codex、Claude Code、Cursor 等支持 MCP 的 AI Agent 中，用自然语言查询或操作本人有权访问的引力引擎数据。

引力引擎 MCP 支持两种授权方式：

* **自动授权（OAuth）**：适用于支持 MCP OAuth 的客户端。在浏览器中登录引力引擎账号并完成授权后，即可使用已授权的工具，无需手工管理 Token。
* **固定授权（APIKey）**：适用于不支持 MCP OAuth、但支持自定义 HTTP 请求头的客户端或自建 Agent。你可以在引力引擎中创建 APIKey、选择需要的查询工具，再把 APIKey 配置到客户端。

引力引擎 MCP 具有以下特点：

* **使用本人身份访问**：Agent 使用授权用户的身份调用引力引擎。
* **沿用现有业务权限**：最终能访问哪些应用和数据，仍由引力引擎按你的原有权限和数据范围判断。
* **按需授权**：自动授权可选择读取、写入和高风险权限；固定授权仅支持查询工具，并可为不同使用场景分别选择工具。
* **统一服务地址**：两种授权方式均使用同一个 MCP 服务地址。
* **服务持续更新**：自动授权下，新工具可随服务更新出现在对应授权范围内；固定授权下，需要编辑授权并勾选新增工具。

## 2 开始前准备 [#2-开始前准备]

接入前请确认：

1. 你已有可正常登录的**引力引擎账号**。
2. 使用支持 **Remote MCP 和 Streamable HTTP** 的客户端。
3. 根据客户端能力选择授权方式：
   * **自动授权**：客户端需要支持 MCP OAuth 浏览器授权。
   * **固定授权**：客户端需要支持自定义 HTTP 请求头，可以发送 `Authorization: Bearer <APIKey>`。

## 3 三步完成接入 [#3-三步完成接入]

两种授权方式使用相同的服务地址：`https://mcp.gravity-engine.com/user/mcp`。

### 3.1 自动授权 [#31-自动授权]

1. 在 MCP 客户端中添加服务地址。
2. 点击连接或认证，在浏览器中登录引力引擎，并确认客户端名称和授权范围。
3. 回到客户端，确认引力引擎 MCP 已连接，然后用自然语言发起一次查询。

> **注意**
> 授权页会展示当前 MCP 客户端和申请的权限。请确认客户端来自可信来源，并只授予完成任务所需的权限。

### 3.2 固定授权 [#32-固定授权]

1. 在引力引擎**用户中心 → MCP授权管理 → 固定授权**中新增授权，选择查询工具并生成 APIKey。
2. 在 MCP 客户端中添加服务地址，并配置携带 APIKey 的请求头。
3. 保存并连接，确认工具列表中出现已选择的查询工具，然后发起一次查询。

> **注意**
> 固定授权连接时不会打开浏览器授权页。请妥善保管 APIKey，避免向他人泄露。

## 4 客户端配置 [#4-客户端配置]

> **注意**
> 4.1～4.7 介绍自动授权的配置方式；使用固定授权时，请参考 4.8。

### 4.1 快速开始 [#41-快速开始]

将以下内容发送给 Agent 客户端，按 Agent 提示操作即可完成配置：

```text
帮我配置好引力引擎 MCP，并发起授权验证，以下是引力引擎官方提供的 MCP JSON：
{
  "mcpServers": {
    "gravity-mcp": {
      "type": "streamable-http",
      "url": "https://mcp.gravity-engine.com/user/mcp"
    }
  }
}
```

### 4.2 Codex [#42-codex]

1. 打开 **设置 → 插件 → MCP**。
2. 选择 **添加 → 添加 MCP 服务器**。
3. 名称填写 `gravity-mcp`，传输方式选择 **流式 HTTP**。
4. URL 填写 `https://mcp.gravity-engine.com/user/mcp`。
5. 保存配置，然后在服务器列表中选择 **进行身份验证**。
6. 在浏览器中完成引力引擎登录授权，再回到 Codex 确认连接成功。

### 4.3 Claude Code [#43-claude-code]

建议使用用户级配置，使引力引擎 MCP 在所有项目中可用：

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

然后：

1. 启动 Claude Code。
2. 输入 `/mcp`。
3. 选择 `gravity-mcp` 并完成浏览器登录授权。
4. 返回 Claude Code，确认服务器状态为已连接。

也可以运行 `claude mcp list` 查看连接状态。

### 4.4 Cursor [#44-cursor]

1. 打开 Cursor Customize 中的 MCPs 配置页面，添加一个 New MCP Server。
2. 将下方配置复制添加至 Cursor `~/.cursor/mcp.json` 文件：

```json
{
  "mcpServers": {
    "gravity-mcp": {
      "type": "streamable-http",
      "url": "https://mcp.gravity-engine.com/user/mcp"
    }
  }
}
```

3. 保存后，在 MCP 工具列表中点击 **Authenticate** 或登录按钮。
4. 在浏览器中完成引力引擎登录授权，再回到 Cursor 确认连接成功。

### 4.5 WorkBuddy [#45-workbuddy]

1. 打开 **专家·技能·连接器 → 连接器 → 自定义连接器**。
2. 选择 **配置 MCP**。
3. 将下方配置复制添加至 WorkBuddy `~/.workbuddy/mcp.json` 文件并保存：

```json
{
  "mcpServers": {
    "gravity-mcp": {
      "type": "streamable-http",
      "url": "https://mcp.gravity-engine.com/user/mcp"
    }
  }
}
```

4. 保存配置，然后在服务器列表中选择 **信任 → 连接**。
5. 在浏览器中完成引力引擎登录授权，再回到 WorkBuddy 确认连接成功。

### 4.6 TRAE [#46-trae]

1. 打开 **设置 → MCP**。
2. 选择 **添加 → 手动配置**。
3. 将下方配置复制添加至弹窗中并点击确认：

```json
{
  "mcpServers": {
    "gravity-mcp": {
      "type": "streamable-http",
      "url": "https://mcp.gravity-engine.com/user/mcp"
    }
  }
}
```

4. 开启 `gravity-mcp`，点击 **前往验证**。
5. 在浏览器中完成引力引擎登录授权，再回到 TRAE 确认连接成功。

### 4.7 其他 MCP 客户端 [#47-其他-mcp-客户端]

对于支持 Remote MCP 和 OAuth 的客户端，通常只需添加以下配置：

```json
{
  "mcpServers": {
    "gravity-mcp": {
      "type": "streamable-http",
      "url": "https://mcp.gravity-engine.com/user/mcp"
    }
  }
}
```

如果客户端要求选择传输方式，请选择 **Streamable HTTP** 或 **HTTP**。

客户端还必须能够完成 OAuth 浏览器授权。如果客户端不支持 MCP OAuth，但支持远程 MCP 和自定义 HTTP 请求头，可以使用固定授权，配置方式见 4.8。仅支持本地 `stdio` 的客户端不能直接连接此远程 MCP 服务。

### 4.8 固定授权配置 [#48-固定授权配置]

对于不支持 MCP OAuth、但支持自定义 HTTP 请求头的客户端，可以使用固定授权。

先在引力引擎中创建固定授权（见 5.2），再在客户端中填写：

> **注意**
> `Bearer` 与 APIKey 之间保留一个空格。请使用页面复制的完整 APIKey，不要使用列表中隐藏部分字符后的显示内容。

如果客户端支持以下 JSON 格式，可以参考：

```json
{
  "mcpServers": {
    "gravity-mcp": {
      "type": "streamable-http",
      "url": "https://mcp.gravity-engine.com/user/mcp",
      "headers": {
        "Authorization": "Bearer <你的 APIKey>"
      }
    }
  }
}
```

将 `<你的 APIKey>` 替换为实际值，不保留尖括号。不同客户端的配置字段可能有所不同，请以客户端支持的格式为准。

保存配置后直接连接，无需再次发起 OAuth 登录。如果仍出现浏览器授权，请检查请求头是否配置正确，以及客户端是否仍在使用原有 OAuth 配置。

对于自建 Agent，请确保发送到该 MCP 地址的每次 HTTP 请求都携带上述请求头。

> **注意**
> 请将 APIKey 填写在客户端的凭据配置中，不要发送到 Agent 对话、放入服务地址或工具参数，也不要提交到共享代码仓库。

## 5 登录、授权与授权管理 [#5-登录授权与授权管理]

### 5.1 自动授权管理 [#51-自动授权管理]

首次连接时，客户端会自动打开引力引擎授权页面：

1. 使用你的引力引擎账号登录。
2. 核对授权页面展示的授权申请客户端信息。
3. 选择需要的权限范围。
4. 确认授权，并等待页面跳转回客户端。

当前权限分为三类：

| 权限    | 适用场景               | 使用建议           |
| ----- | ------------------ | -------------- |
| 读取    | 查询应用、报表、事件和配置      | 日常分析优先只授予读取权限  |
| 写入    | 创建应用以及后续开放的配置变更    | 确实需要修改业务数据时再授予 |
| 高风险操作 | 未来开放的删除、批量变更等高影响操作 | 仅在明确理解影响时授予    |

授权范围决定客户端能够发现哪些工具，但不代替引力引擎的业务权限校验。即使客户端展示了某个工具，如果你的账号没有对应功能或数据权限，实际调用仍会被拒绝。

> **注意**
> 自动授权目前不支持直接修改已有授权的范围。如需增减权限，请在**用户中心 → MCP授权管理 → 自动授权**中撤销授权，再从客户端重新发起认证。

### 5.2 固定授权管理 [#52-固定授权管理]

你可以在**用户中心 → MCP授权管理 → 固定授权**中创建和管理自己的 APIKey。

**新增授权**

1. 点击 **新增授权**。
2. 填写 **Key名称**，建议使用便于识别用途的名称，例如「日报查询」。
3. 在 **绑定工具** 中勾选需要的查询工具。
4. 点击 **生成授权**，页面返回授权列表。
5. 点击 API Key 旁的复制图标，将完整 APIKey 配置到客户端。

同一用户可以创建多份固定授权，为不同客户端或使用场景分别选择工具。

**查看与编辑**

在授权列表中可以再次复制 APIKey，也可以点击 **编辑** 查看完整 APIKey、修改 Key名称和绑定工具。

编辑名称或工具范围不会改变 APIKey，无需重新填写客户端凭据。保存后，后续请求会按新的工具范围校验；如果客户端仍显示旧工具列表，请刷新工具列表或重新连接。

新发布的工具不会自动加入已有固定授权，需要编辑授权后手工勾选。

**删除授权**

不再使用某份固定授权时，可以在列表中点击 **删除**。

删除后，该 APIKey 无法再通过新的请求鉴权；已经开始执行的请求可能继续完成。删除操作不可恢复，如需再次使用，请新增授权并更新客户端中的 APIKey。

**权限说明**

固定授权仅支持绑定的查询工具，不支持写入或高风险操作。实际能访问的应用和数据仍受本人业务权限限制。

APIKey 当前不设自动到期时间，但授权被删除、账号失效或业务权限变化，都可能影响后续调用。请仅向可信客户端配置 APIKey；如发生泄露，请删除对应授权并重新创建。

## 6 支持的能力 [#6-支持的能力]

> **注意**
> 固定授权只会返回当前 APIKey 已绑定且可用的查询工具，不包含创建应用等写入工具。

实际可用工具以客户端连接后返回的工具列表为准。

### 6.1 应用管理 [#61-应用管理]

* `gravity_app_list`：查询有权限访问的应用。
* `gravity_app_create`：创建应用，属于写入操作，执行前 Agent 应再次确认关键参数。

### 6.2 广告、素材与经营报表 [#62-广告素材与经营报表]

* `gravity_metric_ad_search`、`gravity_metric_creative_search`：查找报表可用指标。
* `gravity_report_ad_query`：查询广告报表。
* `gravity_report_creative_query`：查询素材报表。
* `gravity_report_user_fields_search`：查找用户报表可用字段。
* `gravity_report_user_list`、`gravity_report_order_list`：查询用户或订单明细。
* `gravity_report_event_list`：查询事件分析报表。
* `gravity_report_monetization_detail`：查询变现明细报表。

用户和订单明细属于敏感业务数据，可能只向指定客户或账号开放，并始终受本人数据范围限制。

### 6.3 事件与埋点排查 [#63-事件与埋点排查]

* `gravity_event_metadata_list`：查询事件定义。
* `gravity_event_property_list`：查询事件属性。
* `gravity_event_user_property_list`：查询用户属性。
* `gravity_event_realtime_list`：查询最近的实时事件明细。

### 6.4 应用与归因配置 [#64-应用与归因配置]

* `gravity_config_app_detail`：查询应用详情。
* `gravity_config_attribution_backtrack`：查询媒体归因回溯窗口。
* `gravity_config_attribution_click_interval`：查询跨媒体点击间隔配置。
* `gravity_config_reattribution`：查询应用再归因配置。
* `gravity_config_postback_window`：查询媒体数据回传窗口。
* `gravity_config_postback_mode`：查询媒体数据回传模型。

## 7 快速验证与示例 [#7-快速验证与示例]

完成接入后，可以先发送：

```text
请使用 Gravity MCP 列出我有权限访问的应用，只返回应用名称和 app_id。
```

使用固定授权时，请先绑定 `gravity_app_list`，再验证应用列表。尝试其他示例时，也需要绑定对应查询工具；涉及先查找指标、再查询报表的任务，需要同时绑定相关工具。

如果能够返回应用列表，说明连接、授权和基础查询已经生效。

还可以尝试以下问题：

### 7.1 广告报表分析 [#71-广告报表分析]

```text
查询应用 12345 在 2026-08-01 到 2026-08-07 的广告消耗、展示、点击和激活，按天汇总，并计算每天的点击率和激活成本。
```

### 7.2 素材效果分析 [#72-素材效果分析]

```text
查询应用 12345 最近 7 天的素材报表，按素材汇总消耗、点击和激活，找出消耗最高但激活成本偏高的 10 个素材。
```

### 7.3 事件排查 [#73-事件排查]

```text
先查找应用 12345 中与“支付”相关的事件英文名，再查询最近 30 分钟该事件的实时上报记录，按 SDK 版本汇总异常情况。
```

### 7.4 归因配置检查 [#74-归因配置检查]

```text
查询应用 12345 的媒体归因回溯窗口、再归因规则、回传窗口和回传模型，并用业务语言解释这些配置会怎样影响归因与回传。
```

### 7.5 创建应用 [#75-创建应用]

```text
帮我创建一个 Android 应用。在真正创建前，先向我确认应用名称、包名、行业类型以及其他必填信息。
```

写入或高风险操作会改变业务数据。请在 Agent 展示最终参数和影响后再确认执行。

本示例仅适用于已授予写入权限的自动授权，固定授权不支持创建应用。

## 8 常见问题 [#8-常见问题]

### 8.1 添加后没有自动打开浏览器 [#81-添加后没有自动打开浏览器]

> **注意**
> 以下排查适用于自动授权。固定授权无需打开浏览器，配置正确后可直接连接。

在客户端的 MCP 管理页面选择 `gravity-mcp` 并点击 **Authenticate**、**Connect** 或登录按钮。

Codex 可以运行：

```bash
codex mcp login gravity-mcp
```

Claude Code 可以在会话中输入 `/mcp` 后选择 `gravity-mcp`。如果客户端给出授权链接但没有自动打开，请复制到本机浏览器完成登录。

### 8.2 一直显示未认证、401 或登录已过期 [#82-一直显示未认证401-或登录已过期]

**自动授权：**

1. 确认配置的是完整地址 `https://mcp.gravity-engine.com/user/mcp`。
2. 在客户端中清除 `gravity-mcp` 的认证信息。
3. 重新连接并完成浏览器授权。
4. 仍失败时，记录客户端名称、版本、发生时间和错误信息后联系支持人员；请勿发送 Token 或完整授权链接。

**固定授权：**

检查完整地址、`Authorization` 请求头、`Bearer` 后的空格、完整 APIKey，以及对应授权是否已删除。联系支持时不要发送完整 APIKey、Token 或授权链接。

### 8.3 Agent 看不到某个工具 [#83-agent-看不到某个工具]

可能原因包括：

* 本次 OAuth 授权未包含该工具所需的读取、写入或高风险权限；
* 工具仍处于灰度、白名单或暂停开放状态；
* 客户端缓存了旧工具列表，尚未完成刷新；
* 该能力尚未在当前环境发布；
* 固定授权未绑定该工具，或该工具不属于查询工具。

> **注意**
> 可以先刷新或重新连接 MCP。需要调整授权范围时，自动授权请按 5.1 撤销原授权并重新认证；固定授权请按 5.2 编辑绑定工具，保存后刷新客户端工具列表。

### 8.4 能看到工具，但调用提示无权限 [#84-能看到工具但调用提示无权限]

MCP 工具是否可见和业务数据是否可访问是两层判断。调用时，引力引擎仍会校验当前账号的公司、菜单、功能和数据范围权限。

请先确认自己能否在引力引擎页面中访问同一应用和功能；如果页面中也没有权限，请联系所在公司的管理员。

### 8.5 查询结果为空 [#85-查询结果为空]

依次检查：

1. 应用 ID 是否正确，并且当前用户有权访问该应用；
2. 时间范围和筛选条件是否过窄；
3. 对应报表、事件或配置在该时间段内是否确有数据；
4. 是否把事件中文名误当成事件英文标识使用。

可以要求 Agent 先查询应用、指标或事件元数据，再执行正式查询，避免猜测字段名。

### 8.6 客户端是否会保存我的引力引擎密码 [#86-客户端是否会保存我的引力引擎密码]

不会。登录发生在引力引擎的网页中，MCP 客户端接收并保存的是授权结果，不应获得你的引力引擎密码。具体授权凭据的本地保存方式由客户端决定，请使用可信、及时更新的客户端。

使用固定授权时，客户端使用的是你配置的 APIKey，无需填写引力引擎密码。

### 8.7 能否用于无人值守脚本或共享账号 [#87-能否用于无人值守脚本或共享账号]

支持远程 MCP 和自定义 HTTP 请求头的自建 Agent 或自动化任务，可以使用固定授权调用已绑定的查询工具。固定授权仍归属于创建它的个人账号，访问范围受该账号当前权限限制。建议按用途分别创建授权，不要多人共享同一账号或 APIKey；写入和高风险操作不支持固定授权。

### 8.8 固定授权的 APIKey 丢失或泄露怎么办 [#88-固定授权的-apikey-丢失或泄露怎么办]

如果只是没有保存 APIKey，可以回到**用户中心 → MCP授权管理 → 固定授权**，在列表中再次复制，或进入编辑页面查看。

如果怀疑 APIKey 已经泄露，请删除对应授权，重新创建一份固定授权，并更新使用它的客户端配置。修改 Key名称或绑定工具不会更换 APIKey。