配置 MCP 访问

WingGate 可以通过 MCP（Model Context Protocol）向 AI Agent 暴露受限的文件、命令和浏览器能力。访问绑定在项目上：凭据只能使用项目与资产 MCP 配置启用的工具组。

前置条件

一个已授予资产的项目（见快速开始）。
支持连接远程 MCP 服务器的外部 MCP 客户端。
创建 MCP 凭据需要组织的 Owner 或 Admin 角色。

创建 MCP 凭据

在 Web 控制台打开项目的 MCP 区域并创建凭据。
立即复制凭据。 secret 值只在创建时展示一次；之后列表和详情响应绝不返回它，也不会出现在日志和审计条目中。
将它存入 MCP 客户端的凭据存储。

项目 MCP 页面

配置 MCP 客户端

在客户端中添加 WingGate 作为 MCP 服务器，提供端点与凭据。客户端必须在每次请求中携带凭据；缺失或错误的凭据会作为认证失败被拒绝。具体工具面由端点在会话建立时宣告；工具组与能力边界见本站 API 与协议参考。

所有客户端使用同一组连接信息：

端点 URL——在 Web 控制台打开项目的 MCP 区域，复制展示的端点 URL。
访问令牌——创建 MCP 凭据时展示的一次性 secret，作为 Authorization: Bearer <token> 请求头发送。

Claude Code

claude mcp add --transport http winggate <ENDPOINT> \
  --header "Authorization: Bearer <TOKEN>"

默认写入当前项目的 local 配置；--scope user 让所有项目可用，--scope project 写入 .mcp.json 与团队共享。用 claude mcp list 检查连接状态。

Codex CLI

export WINGGATE_MCP_TOKEN=<TOKEN>
codex mcp add winggate --url <ENDPOINT> --bearer-token-env-var WINGGATE_MCP_TOKEN

Codex 只保存环境变量名，token 值不落盘。等价的手写配置（~/.codex/config.toml）：

[mcp_servers.winggate]
url = "<ENDPOINT>"
bearer_token_env_var = "WINGGATE_MCP_TOKEN"

Cursor

在项目根目录创建 .cursor/mcp.json（或 ~/.cursor/mcp.json 全局生效）：

{
  "mcpServers": {
    "winggate": {
      "url": "<ENDPOINT>",
      "headers": { "Authorization": "Bearer <TOKEN>" }
    }
  }
}

保存后在 Cursor 设置 → MCP 中确认连接状态。

pi

pi 不内置 MCP，先安装社区扩展：

pi install npm:pi-mcp-adapter

然后在 ~/.pi/agent/mcp.json（全局）或 .pi/mcp.json（项目）添加服务器：

{
  "mcpServers": {
    "winggate": {
      "url": "<ENDPOINT>",
      "description": "Remote assets of your project: list them with asset.list, then read/write/search files and run commands through this server rather than a local ssh/scp or your own Playwright browser.",
      "headers": { "Authorization": "Bearer <TOKEN>" }
    }
  }
}

重启 pi 后可用 /mcp 检查连接。

DeepSeek Harness

在 harness 的 cordis.yml 中挂载内置 MCP 客户端插件：

- id: mcp-client
  config:
    transport: streamable-http
    serverName: winggate
    url: <ENDPOINT>
    headers:
      Authorization: Bearer <TOKEN>

工具以 mcp__winggate__* 命名注册。也可以安装 dsh-mcp-manager 插件，在 Settings → MCP 页面图形化添加。

能力边界

MCP 能力是项目内资产上的受限文件、命令与浏览器操作。
asset.list 与 SSH 入口只发布已加入项目的资产：从项目资产页创建会自动加入该项目，在组织资产页创建则需到项目页的「项目资产」用「添加资产」加入，否则不会出现在这些入口，按 id 直接调用也会被拒绝。
浏览器能力只作用于本人拥有的浏览器资产；点击/填写等敏感写操作与页面 WebMCP 调用还需在扩展端本地确认。
MCP 能覆盖的操作，工具描述与握手说明会引导 Agent 经本服务器作用于列出的资产，而不是本地 ssh/scp/shell 或自建的 Playwright/CDP 浏览器：只有这条通道携带资产授权、审计与凭据（浏览器资产另带本地用户的登录会话）。
MCP 入口的权限集是固定的；任何凭据或客户端都无法放大它。
每次 MCP 操作都记录在组织审计中，Agent 活动与人工会话一样可追溯。

预期结果

客户端列出 WingGate 的工具，MCP 配置允许的调用成功，并出现在审计视图中。

排障

认证失败——核对凭据值，以及客户端是否每次请求都携带。secret 只展示一次；如果丢失，创建新凭据并吊销旧的。
权限不足——成员没有 active grant，或项目、资产 MCP 配置不允许该工具。请 Owner 或 Admin 检查授权和 MCP 配置。
资产不可达——确认服务该资产的连接器在线；MCP 操作与终端会话走同一条数据面。