---
url: https://docs.ogmabox.com/zh/mcp-setup.md
description: 通过 Streamable HTTP 或 stdio 将 AI 智能体连接到 Ogma，配置权限并使用本地 MCP 管理端点。
---

# Ogma MCP 服务器设置 {#ogma-mcp-server-setup}

Ogma MCP 服务器（`ogma-mcp`）让兼容的 AI 助手查看项目上下文，并在启用相应功能后控制嵌入式浏览器、发送请求、运行工作流和收集证据。其笔记/待办工具是内存中的 MCP 会话临时记事区，与应用中持久保存的笔记页面相互独立。

MCP 面向 Codex、Claude Code、Cursor 及其他模型上下文协议客户端等外部工具。它与应用内的工作区 AI 助手并非同一功能。

完整资源和工具列表请参阅[MCP 资源和工具](./reference/mcp-tools.md)。

## 快速入门：桌面应用 {#quick-start-desktop-app}

1. 启动 Ogma，打开需要智能体检查的项目。
2. 打开**设置 > MCP**，选择所需权限并保存。浏览器交互需要**发送重放请求**权限。
3. 点击**启动**并复制显示的端点，通常为 `http://127.0.0.1:3000/mcp`。
4. 将其作为 **Streamable HTTP** 服务器添加到 MCP 客户端。
5. 让智能体调用 `ogma_explain_capabilities` 并读取 `ogma://project/current`，检查连接和当前项目。

此方式无需单独构建二进制文件。页面导航、表单、登录流程及故障排查请参阅[使用 MCP 自动化浏览器](./guide/mcp-browser.md)。

### 连接地址 {#connection-addresses}

| 接口 | 默认地址 | 用途 |
| --- | --- | --- |
| MCP 传输 | `http://127.0.0.1:3000/mcp` | 原生 MCP 客户端连接到此地址。 |
| 后端 REST API | `http://127.0.0.1:8181` | 独立 MCP 的 `--api-url` 以及下文的管理/桥接路由。 |
| 代理监听器 | `127.0.0.1:8080` | 捕获浏览器流量；这不是 MCP 端点。 |

桌面实例可能动态分配后端 API 端口。stdio/REST 集成应使用实际运行实例的地址，原生 MCP 应使用设置中显示的端点。如果没有本地客户端/连接器，云端聊天服务无法访问你的回环地址。

HTTP 端点有状态：让客户端处理初始化和会话头部。不存在单独的旧版 `/sse` 端点。自定义客户端应遵循 MCP [传输规范](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports)。

## 何时使用 MCP {#when-to-use-mcp}

当需要外部助手协助完成以下工作时，使用 MCP：

* 汇总已捕获的流量。
* 对安全发现进行分类和优先级评估。
* 起草基于证据的报告内容。
* 审查工作流和重放会话。
* 准备范围受限且经你明确批准的操作。

如果希望使用 Ogma 内嵌的助手窗口，请使用[工作区 AI](./guide/workspace-ai.md)。

## 独立运行要求 {#standalone-requirements}

当客户端需要启动本地可执行文件，而非连接到嵌入式 HTTP 端点时，使用 stdio。

* Ogma 后端运行在其实际 API 地址上（CLI 默认地址：`http://127.0.0.1:8181`）
* `ogma-mcp` 二进制文件（从源码构建）

## 构建 {#build}

```bash
cargo build --locked --bin ogma-mcp --release
```

除非自定义了 Cargo 目标目录，否则默认输出为 `target/release/ogma-mcp`（Windows 上为 `ogma-mcp.exe`）。

## 运行 {#run}

```bash
# Connect to Ogma running on the default port
./ogma-mcp

# Connect to a custom address
./ogma-mcp --api-url http://127.0.0.1:9090

# Use a larger body preview
./ogma-mcp --body-preview-bytes 2048
```

服务器无法访问 Ogma API 时会退出。配置 MCP 客户端启动此命令；stdout 传输 MCP 消息，stderr 输出诊断信息。stdio 权限由其自身的标志决定，而非嵌入式 MCP 设置。

## 工具发现 {#tool-discovery}

当前服务器始终公开完整的工具目录。设置中没有工具配置方案选择器。旧版 `--tool-profile`、`--mcp-tool-profile` 和 `OGMA_MCP_TOOL_PROFILE` 值仍可接受以保持兼容，但不会隐藏工具或授予权限。

对于较大的目录，请先使用 `ogma_explain_capabilities` 和 `ogma_find_tools`，不要猜测输入。搜索任务关键词以筛选工具，然后查询确切工具名称以查看其契约。浏览器和搜索分派器提供便捷入口；专用工具仍可直接使用。参阅[工具发现与分派](./reference/mcp-tools.md#tool-discovery-and-dispatch)。

## 应用内 MCP 设置 {#in-app-mcp-settings}

打包后的 Ogma 版本可通过**设置 > MCP** 管理 MCP。当希望 Ogma 为当前实例启动或停止嵌入式 MCP 进程时，使用设置页面。

当 AI 客户端需要直接启动 MCP 服务器时，使用独立的 `ogma-mcp` 二进制文件。

保存设置会自动重启正在运行的嵌入式 MCP 进程。之后请重新连接客户端；旧会话 ID 和确认令牌不能重复使用。**运行时诊断**显示最近的进程输出。

Ogma 还通过本地 REST API 提供 MCP 管理功能。这些路由位于**后端 API 端口**，而非专用 MCP 端口，供设置页面和应用内 AI 桥接使用：

| 端点 | 用途 |
| --- | --- |
| `GET /mcp/status` | 返回 `{ running, pid, endpoint, config, diagnostics }`。停止时 `endpoint` 为 null；诊断信息包含最近的 `{ stream, message }` 记录。 |
| `POST /mcp/start` | 使用持久保存的设置启动嵌入式 MCP 并返回状态。无消息体。如果已在运行，则返回冲突。 |
| `POST /mcp/stop` | 停止嵌入式 MCP 子进程。 |
| `GET /settings/mcp` | 返回持久保存的 MCP 配置。 |
| `PUT /settings/mcp` | 接收完整配置对象并保存，如果 MCP 正在运行则重启。返回已接受的配置或错误。仅允许绑定到回环主机。 |
| `GET /mcp/tools` | 返回 `{ tools, config }`，包括每个工具的 `inputSchema`。此 REST 目录不分页。 |
| `POST /mcp/tools/call` | 使用 `{ "name": "ogma_explain_capabilities", "arguments": {} }` 调用一个工具。返回 `{ "result": "..." }`；将该文本解析为工具的 JSON 封装。这不是包含图像块的原生 MCP 结果。 |

REST 桥接使用持久保存的权限，但无需启动独立的 HTTP MCP 子进程。它为后端/配置共享一个桥接会话。需要隔离的客户端会话和图像输出时，优先使用原生 MCP。

桥接失败时，解析 `result` 会得到包含序列化错误封装的 `{ "error": "..." }`。应检查该值，不要将 HTTP 成功状态视为工具成功。

默认的持久保存 MCP 配置：

```json
{
  "bind_host": "127.0.0.1",
  "port": 3000,
  "allow_write_findings": false,
  "allow_export_data": false,
  "allow_read_secrets": false,
  "allow_send_requests": false,
  "allow_run_workflows": false,
  "allow_intercept_control": false,
  "tool_profile": "full"
}
```

允许的绑定主机为 `127.0.0.1`、`localhost` 和 `::1`；端口必须在 `1024` 到 `65535` 之间。此版本没有为暴露到网络的 MCP 配置身份验证，因此会拒绝公共绑定地址。旧版 `allow_public_bind` 和 `acknowledge_write_tool_risk` 字段不会覆盖此限制。

## Claude Code {#claude-code}

对于正在运行的桌面端点：

```bash
claude mcp add --transport http ogma http://127.0.0.1:3000/mcp
```

如果 Ogma 显示的端点不同，请使用该端点。配置作用域和 stdio 选项请参阅 [Claude Code 的 MCP 配置](https://code.claude.com/docs/en/mcp)。可用以下问题验证：“Ogma 中有哪些项目？”

## Cursor {#cursor}

将以下条目合并到项目的 `.cursor/mcp.json` 或用户级 `~/.cursor/mcp.json` 中：

```json
{
  "mcpServers": {
    "ogma": {
      "url": "http://127.0.0.1:3000/mcp"
    }
  }
}
```

在 Cursor 的 MCP 设置中启用连接。参阅 [Cursor MCP 文档](https://cursor.com/docs/mcp)。

### Stdio 客户端配置 {#stdio-client-configuration}

启动可执行文件的客户端可使用以下服务器条目，并按需调整配置文件位置：

```json
{
  "mcpServers": {
    "ogma": {
      "command": "/absolute/path/to/ogma-mcp",
      "args": ["--api-url", "http://127.0.0.1:8181"]
    }
  }
}
```

在 Windows 上，使用可执行文件的完整路径，并在 JSON 中转义反斜杠。部分客户端还要求 `"type": "stdio"`。按需向 `args` 添加权限标志。

## 权限 {#permissions}

全部六项特权能力默认禁用。从 `ogma://mcp/permissions` 读取其当前值。即使工具已列出，在对应能力启用前仍可能拒绝执行。完整的标志/环境变量表请参阅 [CLI 参考](./reference/cli.md#standalone-ogma-mcp-flags)。

浏览器交互、浏览器上下文管理、项目切换及所有身份验证流程调用均需要 `--allow-send-requests`。浏览器观察可检查已运行的浏览器，无需启用其控制工具。`--allow-read-secrets`（或 `OGMA_MCP_ALLOW_READ_SECRETS=true`）单独允许读取未掩码的环境变量值。

服务器**没有每分钟或每会话的活动配额**。各工具仍会执行输入大小、批量大小、范围检查和超时限制。旧版发送/工作流配额标志已不再支持。

## 只读模式 {#read-only-mode}

默认情况下，MCP 服务器为只读模式。除非明确启用，否则以下操作不可用：

* 发送请求（重放）
* 控制嵌入式浏览器、爬虫、身份验证捕获和主动探测辅助工具
* 运行工作流
* 创建或修改安全发现
* 修改范围或匹配与替换规则
* 修改或转发被拦截的流量
* 删除数据
* 访问秘密环境变量值
* 导出数据

消息体预览默认为 512 字节。`--body-preview-bytes` 可调整预览，且必须至少为 1；它不限制所有工具的输出。使用 `ogma_get_http_entry_body` 获取完整 HTTP 消息体或执行定向消息体搜索，使用 `ogma_get_ws_message` 获取完整 WebSocket 消息。

## 安全发现写入工具 {#finding-write-tools}

如需启用 AI 辅助创建安全发现，请使用写入权限重启 ogma-mcp：

```bash
./ogma-mcp --allow-write-findings
```

或设置环境变量：

```bash
OGMA_MCP_ALLOW_WRITE_FINDINGS=true ./ogma-mcp
```

### 可用的写入工具 {#write-tools-available}

| 工具 | 说明 |
|------|-------------|
| `ogma_preview_finding_from_evidence` | 根据 HTTP 条目预览安全发现草稿（只读，始终可用） |
| `ogma_create_finding` | 创建带有严重性、状态、标签和证据链接的安全发现 |
| `ogma_update_finding` | 更新现有安全发现 |
| `ogma_add_finding_tag` | 向安全发现添加标签，不替换现有标签 |
| `ogma_link_finding_evidence` | 将 HTTP 条目、重放尝试、自动化结果或 WS 消息关联到安全发现 |
| `ogma_delete_finding` | 删除一个安全发现 |
| `ogma_export_findings_report` | 生成 HTML、Markdown 或 PDF 报告 |

当前实现还对环境变量更新、历史注释、范围选择及匹配与替换修改等共享写入工具使用安全发现写入权限。这些操作请参阅[工具目录](./reference/mcp-tools.md)。

### 示例：AI 辅助创建安全发现 {#example-ai-assisted-finding-creation}

启用 `--allow-write-findings` 后：

1. “分析 HTTP 条目 {id} 中的安全问题。如果发现真实问题，使用 ogma\_create\_finding 记录它。”
2. AI 会调用 `ogma_get_http_entry` 检查请求
3. 如果证据支持某个安全发现，AI 会调用 `ogma_create_finding`，并关联证据

### 仅有安全发现写入权限时仍不可用的操作 {#still-not-available-with-finding-writes-only}

* 重放发送
* 工作流执行
* 创建导出
* 拦截队列控制
* 项目切换

## 导出工具 {#export-tools}

如需启用 AI 辅助创建导出任务，请使用导出权限重启 ogma-mcp：

```bash
./ogma-mcp --allow-export-data
```

或设置环境变量：

```bash
OGMA_MCP_ALLOW_EXPORT_DATA=true ./ogma-mcp
```

### 可用的导出工具 {#export-tools-available}

| 工具 | 所需权限 | 说明 |
|------|--------------------|-------------|
| `ogma_preview_export_plan` | 无（只读） | 预览导出将包含的内容 |
| `ogma_list_export_jobs` | 无（只读） | 列出最近的导出任务 |
| `ogma_get_export_job` | 无（只读） | 检查导出任务状态 |
| `ogma_get_export_download_info` | 无（只读） | 获取已完成导出的下载 URL |
| `ogma_create_export_job` | export\_data | 创建导出任务 |

### 支持的导出类型和格式 {#supported-export-kinds-and-formats}

| 类型 | 说明 | 格式 |
|------|-------------|---------|
| `http_history` | 所有经代理的 HTTP 请求 | json, csv, raw\_http |
| `search` | 过滤后的 HTTP 请求 | json, csv, raw\_http |
| `findings` | 安全发现 | json, csv |
| `automate_results` | 自动化会话结果 | json, csv |

注意：`raw_http` 格式仅适用于 `http_history` 和 `search` 类型。

### 安全警告 {#security-warning}

导出文件可能包含完整的 HTTP 请求和响应消息体，其中可能有密码、令牌和个人数据。请妥善处理导出文件。

### 仅有导出权限时仍不可用的操作 {#still-not-available-with-export-permissions-only}

* 删除导出文件
* 重命名导出文件
* 通过 MCP 流式传输导出内容
* 重放发送
* 工作流执行

## 重放请求发送 {#replay-request-sending}

警告：此功能允许通过 Ogma 重放发送真实的出站 HTTP 流量。

启用方法：

```bash
./ogma-mcp --allow-send-requests
```

或通过环境变量启用：

```bash
OGMA_MCP_ALLOW_SEND_REQUESTS=true ./ogma-mcp
```

### 前提条件 {#prerequisites}

1. Ogma 代理必须正在运行
2. 必须在**测试范围**中配置当前测试范围，用于受保护的重放发送
3. 目标主机必须位于当前测试范围内

### 发送工具 {#send-tools}

| 工具 | 权限 | 说明 |
|------|-----------|-------------|
| `ogma_preview_replay_send` | send\_requests | 准备发送，获取确认令牌 |
| `ogma_send_replay_request` | send\_requests | 使用确认令牌执行发送 |
| `ogma_create_replay_session_from_history` | send\_requests | 创建重放会话 |
| `ogma_create_replay_session_raw` | send\_requests | 根据原始请求定义创建重放会话 |
| `ogma_browser_form_to_replay` | send\_requests | 根据当前页面的表单创建重放会话 |
| `ogma_create_scope_preset` | send\_requests | 保存测试范围预设；使用 `ogma_set_active_scope` 单独激活 |
| `ogma_repeat_request` | send\_requests | 重复已捕获的请求，可选修改 |
| `ogma_replay_with_modifications` | send\_requests | 使用字段级覆盖重放已捕获的请求 |
| `ogma_http_request` | send\_requests | 直接发送 HTTP 请求 |
| `ogma_fetch_url` | send\_requests | 获取 URL 并返回状态、头部和预览 |
| `ogma_follow_redirect` | send\_requests | 跟随重定向链并报告每一跳 |
| `ogma_bulk_send_requests` | send\_requests | 发送数量受限的一批请求 |
| `ogma_fuzz_parameter` | send\_requests | 使用字典值替换 `{{FUZZ}}` 占位符 |
| `ogma_multipart_upload` | send\_requests | 发送 multipart form-data 请求以测试上传 |
| `ogma_websocket_connect` | send\_requests | 连接 WebSocket URL 并交换消息 |
| `ogma_login_replay_auto` | send\_requests | 提交浏览器登录表单并捕获身份验证配置 |
| `ogma_auth_capture_profile` | send\_requests | 捕获浏览器 Cookie、存储、身份验证令牌和 CSRF 候选项 |
| `ogma_auth_apply_profile` | send\_requests | 将捕获的身份验证配置应用到浏览器 |
| `ogma_auth_refresh_csrf` | send\_requests | 从浏览器状态刷新 CSRF 候选项 |
| `ogma_authz_matrix_test` | send\_requests | 使用多个身份验证配置重放同一请求 |
| `ogma_run_active_probe_workflow` | send\_requests | 运行数量受限、针对特定漏洞的主动探测 |
| `ogma_test_race` | send\_requests | 并发发送同一请求，并报告状态码不同于最常见状态码的响应 |
| `ogma_test_smuggling` | send\_requests | 通过原始 TCP 发送 CL.TE 和 TE.CL 请求失同步探测 |
| `ogma_test_hpp` | send\_requests | 发送 HTTP 参数污染变体 |
| `ogma_run_nuclei` | send\_requests | 使用一个内置或提供的模板扫描器模板扫描目标 URL |
| `ogma_browser_navigate` 及浏览器交互工具 | send\_requests | 控制嵌入式浏览器并捕获产生的流量 |
| `ogma_crawl_site` | send\_requests | 通过嵌入式浏览器爬取范围内的目标 |
| `ogma_get_replay_session` | 无 | 查看重放会话元数据 |
| `ogma_get_replay_attempt` | 无 | 查看重放尝试元数据 |
| `ogma_list_replay_sessions` | 无 | 列出重放会话 |

### 两步工作流 {#two-step-workflow}

基于确认的重放工具对需要两次调用：

1. `ogma_preview_replay_send`：审查请求，获取确认令牌
2. `ogma_send_replay_request`：使用令牌确认并发送

确认令牌在 5 分钟后过期，仅可使用一次，并属于创建它的 MCP 会话。修改请求或重启 MCP 后，请重新预览。此两步规则并不适用于所有发送工具：直接 HTTP 工具、重复请求辅助工具和浏览器操作在启用后可立即发送。

### 会话示例 {#example-session}

```
User: Resend HTTP entry abc123 and check the response
AI: (calls ogma_preview_replay_send with http_entry_id="abc123")
    - shows request preview, confirmation token, scope status --
AI: (calls ogma_send_replay_request with confirmation_token and request_hash)
    - shows response status, timing, response preview --
```

### 仅有请求发送权限时仍不可用的操作 {#still-not-available-with-request-sending-permissions-only}

* 工作流执行
* 创建或更新安全发现
* 删除

启用这些工具前，请保持当前测试范围尽量狭窄。范围检查仅适用于受保护的发送路径；不要将范围视为针对任意浏览器 JavaScript 或所有直接获取辅助工具的通用防火墙。

## 拦截控制 {#intercept-control}

警告：拦截控制允许 MCP 客户端转发、丢弃或修改当前保留在 Ogma 拦截队列中的实时流量。

启用方法：

```bash
./ogma-mcp --allow-intercept-control
```

或通过环境变量启用：

```bash
OGMA_MCP_ALLOW_INTERCEPT_CONTROL=true ./ogma-mcp
```

### 拦截工具 {#intercept-tools}

| 工具 | 权限 | 说明 |
|------|-----------|-------------|
| `ogma_get_intercept_status` | intercept\_control | 读取请求、响应和 WebSocket 拦截状态 |
| `ogma_set_intercept_enabled` | intercept\_control | 启用或禁用拦截模式 |
| `ogma_list_intercept_queue` | intercept\_control | 列出当前保留的条目 |
| `ogma_get_intercept_item` | intercept\_control | 检查一个队列条目 |
| `ogma_forward_intercept_item` | intercept\_control | 转发队列条目，可选修改 |
| `ogma_drop_intercept_item` | intercept\_control | 丢弃队列条目 |
| `ogma_intercept_and_modify` | intercept\_control | 等待匹配的条目，修改后转发 |

## 工作流执行 {#workflow-execution}

警告：工作流执行会运行工作流逻辑。部分工作流会发送 HTTP 流量或创建安全发现。

启用方法：

```bash
./ogma-mcp --allow-run-workflows
```

### 工作流执行工具 {#workflow-execution-tools}

| 工具 | 权限 | 说明 |
|------|-----------|-------------|
| `ogma_get_workflow_safety` | 无（只读） | 对工作流副作用进行分类 |
| `ogma_preview_workflow_run` | run\_workflows | 预览并获取确认令牌 |
| `ogma_run_workflow` | run\_workflows | 使用确认令牌执行 |
| `ogma_cancel_workflow_run` | run\_workflows | 取消正在运行的主动工作流 |

使用 `workflow_id` 预览；转换工作流还需提供 `input`，使用已捕获条目作为主动工作流输入时需提供 `trigger_entry_id`。运行时使用返回的 `confirmation_token` 和 `definition_hash`；转换工作流还需要 `input_hash` 和相同的 `input`。令牌在五分钟后过期，且仅可使用一次。使用 `ogma_get_workflow_run` 读取生成的运行记录。

自动化执行通过其会话/运行工具提供，需要**请求发送权限**，而非工作流运行权限。列出和检查现有运行记录无需发送权限。

### 跨权限要求 {#cross-permission-requirements}

使用 `sdk.requests.send` 的工作流还需要 `--allow-send-requests`。
使用 `sdk.findings.create` 的工作流还需要 `--allow-write-findings`。

检测基于静态文本分析；参阅下方提示说明。

### 安全分类提示说明 {#safety-classification-advisory-note}

工作流安全分类检查 JavaScript 源码文本中的 `sdk.requests.send` 等模式。这种检测并不全面：混淆或动态构造的 SDK 方法调用可能无法被检测到。运行不可信工作流前，务必审查工作流 JavaScript 源码。

### 仅有工作流权限时仍不可用的操作 {#still-not-available-with-workflow-permissions-only}

* 手动触发被动工作流
* 删除
* 修改环境变量

## 提示词示例 {#example-prompts}

连接后：

* “显示最近 20 个发往 example.com 的 HTTP 请求”
* “此项目是否有高危或严重的安全发现？”
* “当前启用了哪些工作流？”
* “检查 HTTPQL 查询 `req.method.eq:\"POST\"` 是否有效”
* “总结当前项目的安全状况”
* “分析 HTTP 条目 {id} 中的安全问题”

## 故障排查 {#troubleshooting}

**连接被拒绝：** 先启动 Ogma（`ogma --data-dir ./ogma-data`）。

**MCP 客户端未显示工具：** 检查传输 URL 或可执行文件路径。客户端必须跟随所有 `tools/list` 游标；每页最多包含 40 个工具。检查客户端过滤设置，以及已安装版本是否包含缺失的工具。

**会话或确认令牌无效：** 重启后重新连接，并生成新的预览令牌。

**浏览器不可用或操作失败：** 保持桌面应用运行。检查 `ogma_browser_health`、对话框和[浏览器恢复](./guide/mcp-browser.md#recover-from-errors)。仅有无头后端不提供桌面浏览器桥接。

**截图没有可读文本：** 使用支持原生 MCP 图像内容的客户端，或检查语义快照。

**结果为空：** Ogma 需要先捕获流量。配置浏览器代理，使流量通过 Ogma 转发后再浏览。