MCP Server 接入

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 开始前准备

接入前请确认：

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

3 三步完成接入

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

3.1 自动授权

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

3.2 固定授权

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

4 客户端配置

4.1 快速开始

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

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

4.2 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

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

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

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

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

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

4.5 WorkBuddy

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

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

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

4.6 TRAE

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

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

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

4.7 其他 MCP 客户端

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

{
  "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 固定授权配置

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

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

如果客户端支持以下 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 请求都携带上述请求头。

5 登录、授权与授权管理

5.1 自动授权管理

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

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

当前权限分为三类：

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

5.2 固定授权管理

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

新增授权

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

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

查看与编辑

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

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

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

删除授权

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

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

权限说明

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

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

6 支持的能力

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

6.1 应用管理

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

6.2 广告、素材与经营报表

• 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 事件与埋点排查

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

6.4 应用与归因配置

• 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 快速验证与示例

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

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

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

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

还可以尝试以下问题：

7.1 广告报表分析

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

7.2 素材效果分析

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

7.3 事件排查

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

7.4 归因配置检查

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

7.5 创建应用

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

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

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

8 常见问题

8.1 添加后没有自动打开浏览器

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

Codex 可以运行：

codex mcp login gravity-mcp

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

8.2 一直显示未认证、401 或登录已过期

自动授权：

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

固定授权：

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

8.3 Agent 看不到某个工具

可能原因包括：

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

8.4 能看到工具，但调用提示无权限

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

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

8.5 查询结果为空

依次检查：

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

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

8.6 客户端是否会保存我的引力引擎密码

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

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

8.7 能否用于无人值守脚本或共享账号

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

8.8 固定授权的 APIKey 丢失或泄露怎么办

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

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