# 连接 AI 代理 {/* #connect-an-ai-agent */}

Reconstruct 通过 MCP 服务器公开采集的界面数据。请选择代理以查看设置说明：

- [Codex](/docs/zh/agents/codex)
- [Claude](/docs/zh/agents/claude)
- [Cursor](/docs/zh/agents/cursor)
- [Cline](/docs/zh/agents/cline)
- [VS Code 中的 GitHub Copilot](/docs/zh/agents/vscode-copilot)
- [Gemini CLI](/docs/zh/agents/gemini-cli)
- [MiMo](/docs/zh/agents/mimo)
- [Muse Code](/docs/zh/agents/muse-code)
- [Grok Build](/docs/zh/agents/grok-build)
- [Hermes Agent](/docs/zh/agents/hermes)
- [OpenClaw](/docs/zh/agents/openclaw)
- [OpenMausBot](/docs/zh/agents/openmausbot)
- [其他 MCP 客户端](/docs/zh/agents/other-mcp-clients)

## 开始之前 {/* #before-you-start */}

Reconstruct MCP 端点为 **`https://reconstruct.dev/mcp`**，使用 **Streamable HTTP**。可通过 OAuth 浏览器登录或个人访问令牌连接。

| 方式 | 工作原理 | 适用场景 |
|---|---|---|
| **OAuth 浏览器登录** | MCP 客户端在浏览器中打开 Reconstruct 登录页面。登录并批准访问后返回客户端。无需在平台创建或复制令牌。 | 支持 OAuth 的交互式代理和编辑器。 |
| **个人访问令牌** | 在平台设置中创建 MCP 令牌，并添加至客户端凭据。 | 不支持 OAuth 的客户端，或没有浏览器登录的自动化环境。 |

两种方式均连接至同一 MCP 服务器，使用 Reconstruct 账户的订阅和用量额度。

## OAuth 浏览器登录 {/* #oauth-browser-sign-in */}

通过 OAuth 连接前，无需在平台签发个人令牌。

1. 在客户端中将 `https://reconstruct.dev/mcp` 添加为远程 HTTP MCP 服务器。
2. 选择 OAuth 或浏览器登录。如果客户端要求连接设置，请使用以下值。
3. 启动 **Sign in**（登录）、**Connect**（连接）或客户端的 MCP 登录命令。具体操作取决于客户端。
4. 在浏览器中登录 Reconstruct 账户并批准请求的访问。如果未开放注册，请联系支持获取账户访问权限。
5. 返回客户端并刷新工具。请它调用 `list_products` 确认连接。

| 设置 | 值 |
|---|---|
| 服务器 URL | `https://reconstruct.dev/mcp` |
| 传输 | Streamable HTTP |
| OAuth 客户端 ID | 预配置客户端使用 `reconstruct-mcp`；Claude Desktop 自动注册 |
| 作用域 | `openid aud-mcp` |
| 客户端密钥 | 留空 |
| OAuth 签发者 | `https://reconstruct.dev/sso/realms/reconstruct` |
| 授权端点 | `https://reconstruct.dev/sso/realms/reconstruct/protocol/openid-connect/auth` |
| 令牌端点 | `https://reconstruct.dev/sso/realms/reconstruct/protocol/openid-connect/token` |

客户端在登录后获取并保存 OAuth 凭据，并用于 MCP 调用。此方式无需复制令牌或设置 `CR_RECONSTRUCT_MCP_TOKEN`。将现有连接切换至 OAuth 时，移除所有手动配置的 `Authorization` 请求头或 bearer 令牌设置。

参阅 [Codex](/docs/zh/agents/codex#oauth-browser-sign-in)、[Claude Code](/docs/zh/agents/claude-code#oauth-browser-sign-in)、[Cursor](/docs/zh/agents/cursor#oauth-browser-sign-in)、[Cline](/docs/zh/agents/cline#oauth-browser-sign-in)、[OpenMausBot](/docs/zh/agents/openmausbot#oauth-browser-sign-in)或[其他 MCP 客户端](/docs/zh/agents/other-mcp-clients#oauth-browser-sign-in)的 OAuth 设置示例。使用对应客户端文档中的回调设置。如果客户端要求重新登录，请再次执行其 MCP 登录流程。

### 客户端兼容性 {/* #client-compatibility */}

浏览器登录示例涵盖 Claude、Cursor、Claude Code、Codex、Grok Build 和 Muse Code，使用其已注册回调地址。Gemini CLI、VS Code、MiMo Code、MiMo Desktop、Hermes Agent 和 OpenClaw 指南使用个人访问令牌；VS Code 指南还提供通过自动客户端注册的一键安装。Claude Desktop 和网页连接器支持使用已批准的确切 HTTPS 回调进行自动客户端注册。其他支持 OAuth 发现和动态客户端注册的客户端也可仅凭服务器 URL 连接；它们会注册并处理自己的确切 HTTPS 或环回回调。不支持 DCR 的客户端仍可使用预配置公共客户端设置。

OAuth 端点来自发现元数据，位于 SSO realm 下，而非网站根目录的 `/authorize` 或 `/token`。客户端若打开根端点，请重新加载服务器配置并再次登录，以刷新缓存的发现信息。

Claude 云连接器请按 [Claude Desktop 指南](/docs/zh/agents/claude-desktop)操作。连接其他云集成前，请向支持团队提供确切的回调 URI。`reconstruct-mcp` 不应填写客户端密钥。

## 代理发现和设备登录 {/* #agent-discovery-and-device-sign-in */}

公开发现从 `https://reconstruct.dev/mcp/server-card` 开始。根目录 `/.well-known/api-catalog` 列出公共 API 文档，`/.well-known/agent-skills/index.json` 列出 Reconstruct 工作流程及其可安装归档。九种工作流程、无需单独安装的 MCP 资源访问、网站或 GitHub CLI 安装、手动下载和客户端专用插件包，请参阅 [Reconstruct 技能](/docs/zh/skills)。连接远程 MCP 服务器不需要在用户计算机上安装 .NET SDK。

已发布的网站页面和文档接受 `Accept: text/markdown`。工作区页面仍要求账户访问权限。

实现 OAuth 设备授权的客户端可读取 `https://reconstruct.dev/auth.md`，并向 `https://reconstruct.dev/agent/register` POST `{"type":"anonymous"}`。响应包含待完成的设备授权、用户验证 URL 和代码、有效期、轮询间隔，以及私密的 PKCE `code_verifier`。向用户展示验证说明。用户必须登录并批准访问。代理随后使用设备代码授权和返回的 `code_verifier` 轮询签发者的令牌端点。遵守轮询间隔和 `slow_down` 响应。注册本身不会签发访问令牌或创建账户。现有角色、订阅限制和同意要求仍然适用。

将设备代码、代码验证器和令牌保密。切勿代替用户批准访问。此流程适用于实现该功能的客户端；不能替代编辑器现有的授权码 + PKCE 设置。

## 个人访问令牌 {/* #personal-access-token */}

1. 登录 [Reconstruct 平台](https://reconstruct.dev/platform/)，打开 **Settings → API tokens**（设置 → API 令牌）。
2. 创建具有 **MCP** 作用域（`mcp`）的令牌，并在显示密钥时复制。
3. 配置客户端发送 `Authorization: Bearer <token>`。如果从环境变量读取令牌，请使用 `CR_RECONSTRUCT_MCP_TOKEN`。
4. 连接并请客户端调用 `list_products`。

将令牌保存在本地密钥或客户端凭据存储中。令牌过期或被撤销时，在平台设置中创建替代令牌，并更新客户端凭据。

## 选择采集数据 {/* #select-captured-data */}

首先调用 `list_products`、`list_platforms` 和 `list_versions`。从 `list_platforms.options.platforms[]` 中选择平台类型和环境，使用返回的 ID。`list_platforms.platforms[]` 包含实际有采集数据的组合。页面工具应使用 `list_pages.views[]` 中确切的已保存 `view` 键。版本包含多个环境时，明确传入 `environment`。上下文工具需要有可用的订阅用量，每次调用获接受时消耗一次上下文读取，包括缓存结果。已接受的调用即使后来失败仍计入用量。发现、图像工具和资源下载不消耗上下文读取。参阅[用量限制](/docs/zh/mcp-tools#usage-limits)。

## 故障排查 {/* #troubleshooting */}

| 现象 | 检查项 |
|---|---|
| `401 Unauthorized` | 完成 OAuth 登录，或检查个人令牌；令牌过期或被撤销时请替换。 |
| `/authorize` 返回 404 | 刷新连接元数据并重新登录；授权端点位于 `https://reconstruct.dev/sso/realms/reconstruct` 下。 |
| `invalid_scope` | 请求 `openid aud-mcp`；Grok Build 也可能请求可选的 `offline_access` 作用域。 |
| 登录后仍要求身份验证 | 刷新服务器并重新执行 OAuth 登录。移除有冲突的手动 bearer 凭据。 |
| OAuth 重定向不匹配 | 使用客户端文档中规定的回调端口。如果仍有错误，请向支持团队提供客户端显示的回调 URI。 |
| 动态客户端注册被拒绝 | 选择自动 OAuth 注册，一分钟后重试。客户端必须提供确切的 HTTPS 或环回回调，并支持 PKCE S256。若不能自行注册，请使用其指南中的预配置 OAuth 设置。 |
| 服务器无法连接 | 确认代理所在计算机能够访问 `https://reconstruct.dev/mcp`。 |
| 工具返回拒绝访问 | 使用 Reconstruct 账户登录并检查订阅。仍无法访问时请联系支持。 |
| 配额或用量不可用 | 检查账户设置中的用量和状态页面。访问可用后重试。 |
| 采集了多个环境 | 从 `list_versions` 获取并提供 `environment`。 |
| 请求的平台或视图不可用 | 使用已采集的平台/环境组合和确切的 `list_pages.views[]` 键；支持的选项不保证已有存储数据。 |
| 未显示工具 | 重启代理或刷新其 MCP 工具列表，然后检查服务器状态。 |

连接后，试试[提示词示例](/docs/zh/prompt-examples)，或浏览 [MCP 工具目录](/docs/zh/mcp-tools)。

### 请求新采集或更新 {/* #request-a-new-capture-or-update */}

MCP 服务器包含 `get_request_options`、`create_product_request`、`get_product_request`、`list_product_requests` 和 `wait_product_request`。通过 OAuth 登录或使用 MCP 访问令牌。订阅必须支持请求，并且只能查看本账户提交的请求。请代理提交新的产品 URL，或更新已知的已发布产品键；随后保留 `requestId`，并等待审核状态变化。请求获批不表示采集已经就绪。参数请参阅[请求工具](/docs/zh/mcp-tools#product-requests)。