Ogma MCP 服务器设置

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

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

完整资源和工具列表请参阅MCP 资源和工具。

快速入门：桌面应用

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

此方式无需单独构建二进制文件。页面导航、表单、登录流程及故障排查请参阅使用 MCP 自动化浏览器。

连接地址

接口	默认地址	用途
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 传输规范。

何时使用 MCP

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

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

如果希望使用 Ogma 内嵌的助手窗口，请使用工作区 AI。

独立运行要求

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

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

构建

bash

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

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

运行

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-profile、--mcp-tool-profile 和 OGMA_MCP_TOOL_PROFILE 值仍可接受以保持兼容，但不会隐藏工具或授予权限。

对于较大的目录，请先使用 ogma_explain_capabilities 和 ogma_find_tools，不要猜测输入。搜索任务关键词以筛选工具，然后查询确切工具名称以查看其契约。浏览器和搜索分派器提供便捷入口；专用工具仍可直接使用。参阅工具发现与分派。

应用内 MCP 设置

打包后的 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

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

bash

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

如果 Ogma 显示的端点不同，请使用该端点。配置作用域和 stdio 选项请参阅 Claude Code 的 MCP 配置。可用以下问题验证：“Ogma 中有哪些项目？”

Cursor

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

json

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

在 Cursor 的 MCP 设置中启用连接。参阅 Cursor MCP 文档。

Stdio 客户端配置

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

json

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

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

权限

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

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

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

只读模式

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

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

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

安全发现写入工具

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

bash

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

或设置环境变量：

bash

OGMA_MCP_ALLOW_WRITE_FINDINGS=true ./ogma-mcp

可用的写入工具

工具	说明
`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 报告

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

示例：AI 辅助创建安全发现

启用 --allow-write-findings 后：

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

仅有安全发现写入权限时仍不可用的操作

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

导出工具

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

bash

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

或设置环境变量：

bash

OGMA_MCP_ALLOW_EXPORT_DATA=true ./ogma-mcp

可用的导出工具

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

支持的导出类型和格式

类型	说明	格式
`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 类型。

安全警告

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

仅有导出权限时仍不可用的操作

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

重放请求发送

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

启用方法：

bash

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

或通过环境变量启用：

bash

OGMA_MCP_ALLOW_SEND_REQUESTS=true ./ogma-mcp

前提条件

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

发送工具

工具	权限	说明
`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	使用字典值替换占位符
`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`	无	列出重放会话

两步工作流

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

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

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

会话示例

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 --

仅有请求发送权限时仍不可用的操作

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

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

拦截控制

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

启用方法：

bash

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

或通过环境变量启用：

bash

OGMA_MCP_ALLOW_INTERCEPT_CONTROL=true ./ogma-mcp

拦截工具

工具	权限	说明
`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	等待匹配的条目，修改后转发

工作流执行

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

启用方法：

bash

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

工作流执行工具

工具	权限	说明
`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 读取生成的运行记录。

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

跨权限要求

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

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

安全分类提示说明

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

仅有工作流权限时仍不可用的操作

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

提示词示例

连接后：

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

故障排查

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

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

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

浏览器不可用或操作失败： 保持桌面应用运行。检查 ogma_browser_health、对话框和浏览器恢复。仅有无头后端不提供桌面浏览器桥接。

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

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

Ogma MCP 服务器设置 ​

快速入门：桌面应用 ​

连接地址 ​

何时使用 MCP ​

独立运行要求 ​

构建 ​

运行 ​

工具发现 ​

应用内 MCP 设置 ​

Claude Code ​

Cursor ​

Stdio 客户端配置 ​

权限 ​

只读模式 ​

安全发现写入工具 ​

可用的写入工具 ​

示例：AI 辅助创建安全发现 ​

仅有安全发现写入权限时仍不可用的操作 ​

导出工具 ​

可用的导出工具 ​

支持的导出类型和格式 ​

安全警告 ​

仅有导出权限时仍不可用的操作 ​

重放请求发送 ​

前提条件 ​

发送工具 ​

两步工作流 ​

会话示例 ​

仅有请求发送权限时仍不可用的操作 ​

拦截控制 ​

拦截工具 ​

工作流执行 ​

工作流执行工具 ​

跨权限要求 ​

安全分类提示说明 ​

仅有工作流权限时仍不可用的操作 ​

提示词示例 ​

故障排查 ​

Ogma MCP 服务器设置

快速入门：桌面应用

连接地址

何时使用 MCP

独立运行要求

构建

运行

工具发现

应用内 MCP 设置

Claude Code

Cursor

Stdio 客户端配置

权限

只读模式

安全发现写入工具

可用的写入工具

示例：AI 辅助创建安全发现

仅有安全发现写入权限时仍不可用的操作

导出工具

可用的导出工具

支持的导出类型和格式

安全警告

仅有导出权限时仍不可用的操作

重放请求发送

前提条件

发送工具

两步工作流

会话示例

仅有请求发送权限时仍不可用的操作

拦截控制

拦截工具

工作流执行

工作流执行工具

跨权限要求

安全分类提示说明

仅有工作流权限时仍不可用的操作

提示词示例

故障排查