# EchoScan MCP Server

EchoScan 的正式远程 MCP Server 地址为 `https://api.echoscan.org/mcp`。它使用 Streamable HTTP 与 OAuth 2.1 Authorization Code + PKCE S256。Secret API Key 不会被当作 OAuth Bearer Token 使用。

## 在 Codex 中连接

1. 打开 Codex 设置，进入 **MCP servers**，添加 `https://api.echoscan.org/mcp`。
2. 选择 OAuth 鉴权。
3. 登录 EchoScan，选择一个 Workspace，检查所请求的能力并授权客户端。
4. 返回 Codex。EchoScan 会在每次调用时重新检查成员身份、套餐权益、速率限制和月度额度。

命令行配置：

```bash
codex mcp add echoscan --url https://api.echoscan.org/mcp
```

## 从 Claude Code 连接

```bash
claude mcp add --transport http echoscan https://api.echoscan.org/mcp
```

## 从 VS Code 连接

```json
{
  "servers": {
    "echoscan": {
      "type": "http",
      "url": "https://api.echoscan.org/mcp"
    }
  }
}
```

## 从其他 MCP Client 连接

选择 Streamable HTTP，地址填写 `https://api.echoscan.org/mcp`，鉴权方式选择 OAuth 2.1。客户端会根据公开 OAuth Metadata 打开浏览器授权。

## Tools

- `echoscan_get_report`：按 Imprint 读取现有 Lite 或 Pro Report 合同；参数为 `depth: lite | pro`。
- `echoscan_get_history`：读取现有 History 合同；需要 Pro 权益。
- `echoscan_get_usage`：读取当前 Workspace 的套餐、权益摘要、请求用量、共享额度与 RPS 限制。
- `echoscan_integration_plan`：返回不含敏感信息的 Agent Installer 计划与本地 CLI 命令。
- `echoscan_installation_status`：读取持久化 Installation 状态，不返回凭证。
- `echoscan_installation_verify`：根据真实连接证据验证 Browser Environment 与 Server Credential。

## OAuth scopes

- `echoscan.report.lite`
- `echoscan.report.pro`
- `echoscan.history.read`
- `echoscan.usage.read`
- `echoscan.integration.read`
- `echoscan.integration.write`

只有当前 Workspace 具备对应权益时，授权页才会提供 Pro Report 与 History scope。Token 与用户、Workspace、客户端、资源及已授予 scope 绑定。Access Token 为短期令牌；Refresh Token 每次使用都会轮换，旧令牌复用会撤销整段授权关系。

## Browser Verifier 与用量边界

Browser Verifier 仍然必须运行在真实 Browser Origin 中并生成 Imprint。MCP 不生成或模拟浏览器指纹；AI 或服务端只有在取得该 Imprint 后，才使用 `echoscan_get_report` 查询报告。MCP 调用与已鉴权 HTTP API 调用消费同一个 Workspace 月度额度和速率策略。

MCP 只是新增的访问界面，不替代由 OpenAPI 描述的 HTTP API。

## 发现与撤销

OAuth Protected Resource Metadata 位于 `https://api.echoscan.org/.well-known/oauth-protected-resource/mcp`；Authorization Server Metadata 位于 `https://api.echoscan.org/.well-known/oauth-authorization-server`。Client ID Metadata Documents（CIMD）是标准接入路径：HTTPS `client_id` 就是元数据文档地址。对于尚未支持 CIMD 的客户端（包括当前版本的 Codex），EchoScan 还在 `https://api.echoscan.org/oauth/register` 提供受控的 Dynamic Client Registration（DCR）兼容入口。DCR 返回的身份是临时的；只有用户在授权页明确允许访问后，系统才会创建持久 OAuth 客户端。

授权前，Consent 页面会显示客户端自报名称、CIMD 身份 URL/主机名或 DCR 兼容身份，以及准确的回调目标。Loopback 回调会明确标为“本机应用回调”，让用户知道授权结果将返回当前设备上的应用。EchoScan 的长期 QA CIMD 文档为 `https://echoscan.org/.well-known/oauth-client/mcp-qa.json`，仅用于受控的 MCP Inspector 上线验收。

可以从客户端撤销 EchoScan MCP 授权。Workspace 成员身份或权益被移除后，后续调用也会立即受限。

现有 REST API、Agent Trial 与 x402-compatible 购买流程仍是互相独立的合同。