# 将 Cursor 连接到 MCP 网关

Cursor 可以作为远程 Streamable HTTP 客户端连接到 AISIX MCP 端点。它发送 AISIX 调用方 API Key，仅发现该密钥有权使用的工具，并通过网关调用这些工具，无需获取上游服务器凭证。

Cursor 继续负责选择模型、决定何时请求工具、获取所需批准和展示结果。此连接将 MCP 工具流量发送到 AISIX，不会将 Cursor 的模型请求路由到网关。要单独路由受支持的 Ask 模式模型请求，请参阅 [Cursor 模型集成](https://docs.apiseven.com/ai-gateway/integrations/coding-agents/cursor.md)。

本指南将 Cursor 连接到聚合的 `/mcp` 端点。你可以接着[设置 MCP 网关](https://docs.apiseven.com/ai-gateway/mcp-gateway/setup.md)继续操作，该指南仅向调用方授予 `everything__echo` 权限；也可以使用现有 AISIX 环境，以及调用方有权访问且可安全调用的工具。

[]()

## 前置条件[​](#prerequisites "前置条件的直接链接")

开始之前，请准备以下内容：

* 完成[设置 MCP 网关](https://docs.apiseven.com/ai-gateway/mcp-gateway/setup.md)并保留 `AISIX_PROXY` 和 `AISIX_MCP_KEY`，或向网关运维团队获取 AISIX 代理源地址和调用方 API Key。对于现有环境，请使用这两个变量名导出相应值，并选择一个已获许可且可安全调用的工具进行验证。
* 安装 [Cursor](https://www.cursor.com/)，并配置支持 Agent 的模型。
* 确保 Cursor 可访问 AISIX 代理 URL。运行在网关宿主机上的 Cursor 可以使用快速入门中的地址；远程开发环境则需要使用其可访问的地址。

本示例使用工作区配置，以便随项目审查连接设置。不要提交调用方 API Key，Cursor 会从环境中读取它。

[]()

## 配置连接[​](#configure-the-connection "配置连接的直接链接")

从已导出 `AISIX_MCP_KEY` 的 Shell 启动 Cursor。如果 Cursor 已在运行但未继承该变量，请先关闭它，再从该环境重新启动，然后测试连接。

在工作区中创建 `.cursor/mcp.json`，将示例 URL 替换为 `$AISIX_PROXY/mcp`：

.cursor/mcp.json

```
{

  "mcpServers": {

    "aisix": {

      "url": "https://gateway.example.com/mcp",

      "headers": {

        "Authorization": "Bearer ${env:AISIX_MCP_KEY}"

      }

    }

  }

}
```

如果需要在所有工作区中使用该连接，请将同一个对象添加到 `~/.cursor/mcp.json`。确保使用此配置的每个 Cursor 进程均可读取该环境变量。

打开 **Customize → MCPs**，选择 `aisix`；如果工作区来源已禁用，请将其启用。确认本地环境已连接，并显示所选的已授权工具。对于 Everything 测试服务，应仅显示 `everything__echo`。

[]()

## 验证工具调用[​](#verify-a-tool-call "验证工具调用的直接链接")

以下提示词使用设置指南中的 Everything 测试服务。对于现有 MCP 服务器，请替换为已授权的工具名称、有效参数和预期结果。在 Cursor Agent 聊天中明确要求使用指定工具，不要依赖自动工具选择：

```
使用 MCP 工具 everything__echo，消息为 "hello through AISIX"。原样返回工具结果。
```

如果 Cursor 请求确认，请审查并批准此次调用。使用 Everything 测试服务时，结果应为：

```
Echo: hello through AISIX
```

确认完整路径：

* Cursor 显示已授权工具，不显示调用方有效授权范围之外的工具。对于此测试服务，应仅显示 `everything__echo`。
* [AISIX MCP 可观测性](https://docs.apiseven.com/ai-gateway/mcp-gateway/observability.md)记录预期调用方 API Key 和服务器的一次成功 `tools/call`。
* Cursor 显示经由 AISIX 返回的工具结果。

工具发现成功说明连接和调用方授权正常，但不能证明模型会选择工具，也不能证明 Cursor 的批准策略允许执行。因此，仍需保留显式工具调用测试。

[]()

## Cursor 故障排查[​](#troubleshoot-cursor "Cursor 故障排查的直接链接")

| 现象                          | 检查项                                                                                                                                                              |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Cursor 未连接                 | 确认 URL 以 `/mcp` 结尾、Cursor 可访问网关，且启动 Cursor 的环境中包含 `AISIX_MCP_KEY`。                                                                            |
| 工作区来源已禁用              | 打开 **Customize → MCPs**，选择 `aisix`，并启用工作区来源。                                                                                                         |
| Cursor 返回 `401`             | 确认 `AISIX_MCP_KEY` 包含 AISIX 调用方 API Key，而非上游 MCP 凭证。                                                                                                 |
| 连接成功但未显示工具          | 按照[工具访问故障排查](https://docs.apiseven.com/ai-gateway/mcp-gateway/overview.md#troubleshoot-tool-access)检查服务器和有效授权，然后在 Cursor 中重新加载服务器。 |
| 工具已显示，但 Agent 未调用它 | 明确指定所选工具的名称，在 MCP 工具列表中启用它，并检查 Cursor 的工具批准策略。对于测试服务，请选择 `everything__echo`。                                            |

[]()

## 下一步[​](#next-steps "下一步的直接链接")

* [客户端身份认证](https://docs.apiseven.com/ai-gateway/mcp-gateway/client-authentication.md)：使用网关 API Key、OAuth 登录，或在适合的可信网络中使用匿名访问。
* [控制工具访问](https://docs.apiseven.com/ai-gateway/mcp-gateway/tool-access-control.md)：授权具体工具、符合服务器名称模式的工具，或所有已注册工具。
* [可观测性](https://docs.apiseven.com/ai-gateway/mcp-gateway/observability.md)：按调用方、服务器、工具和结果检查 MCP 调用。
