CyberStrikeAI MCP 联邦完全指南内置 MCP、独立 HTTP 服务与外部工具联邦的接入、加固与排障【免费下载链接】CyberStrikeAIThe system of action for AI-native cybersecurity—where intent becomes governed execution, evidence becomes operational memory, and every operation improves the next.项目地址: https://gitcode.com/GitHub_Trending/cy/CyberStrikeAIMCPModel Context Protocol是 CyberStrikeAI 中 Agent 调用工具的主要协议层。本篇指南以docs/zh-CN/mcp-federation.md为骨架结合仓库源码深入讲解 CyberStrikeAI 的三层 MCP 体系——内置 MCP Server、独立 HTTP MCP 服务与外部 MCP 联邦从 YAML 配置、Web 管理 API、stdio/HTTP/SSE 三种传输模式到连接恢复、熔断限流、工具暴露策略与安全审查清单读完你便能独立完成外部 MCP 的接入、调试与生产加固。MCP 联邦架构总览CyberStrikeAI 的 MCP 能力分三层分别对应不同的部署与集成场景内置 MCPWeb 服务进程内部创建的 MCP Server随服务自动注册并暴露给前端和 Agent通常无需额外配置独立 HTTP MCP 服务以mcp:配置段开启的独立监听端点供外部程序通过 MCP 协议直接调用平台能力外部 MCP 联邦通过external_mcp:配置段或 Web 管理页面接入的第三方 MCP 服务stdio / SSE / HTTP其工具经过拉取、命名隔离、授权与监控后进入 Agent 的工具池。从源码结构看这三层分别由 internal/mcp/server.go内置 Server、internal/mcp/external_manager.go外部 MCP 管理器与 internal/einomcp/mcp_tools.goEino 工具桥接支撑前端与 Agent 统一通过应用内部调用无需感知底层传输差异。内置 MCP零配置的工具注册Web 服务内部会创建 MCP Server 并注册以下工具类别YAML 命令工具加载自tools/目录下的工具定义如 tools/nmap.yaml、tools/sqlmap.yaml内置安全执行工具execute/exec等命令执行类知识库工具检索knowledge_base/语料项目事实工具项目黑板的读写与查询C2 工具WebShell 工具批量任务工具视觉分析工具analyze_image需 config.example.yaml 中vision.enabled: true且配置 VL 模型才注册。在 internal/mcp/server.go 中RegisterTool(tool Tool, handler ToolHandler)是工具注册的统一入口RegisterPrompt、RegisterResource则用于注册 MCP 协议层面的提示词与资源。前端和 Agent 通常通过应用内部调用这些工具不需要额外配置只有在需要把平台能力暴露给外部程序时才需要启用下一节的独立 HTTP MCP 服务。独立 HTTP MCP 服务把平台能力开放给外部程序如果希望外部程序如 Claude Desktop、Cursor、其他 Agent 框架通过 MCP 协议直接调用 CyberStrikeAI 的能力可启用独立 HTTP MCP 服务配置如下摘自 config.example.yaml 并补齐注释mcp: enabled: false # 是否启用 MCP 服务器http 模式 host: 127.0.0.1 # MCP 服务器监听地址需要远程访问时再显式修改并配置网络层访问控制 port: 8081 # MCP 服务器端口 auth_header: X-MCP-Token # 可选的全局服务凭证 Header普通调用请使用用户 Authorization: Bearer Token auth_header_value: # 全局服务凭证值仅 allow_global_accesstrue 时生效 allow_global_access: false # 高风险兼容模式静态密钥映射为全局服务身份默认请使用用户 Bearer Token原文档给出的示例将host: 0.0.0.0与auth_header_value: random-secret组合使用适合明确需要对外暴露的场景而示例配置默认保持enabled: false、host: 127.0.0.1与allow_global_access: false即默认只允许本机、且不开启静态密钥的全局访问模式。生产环境必须设置auth_header_value并限制网络访问防火墙、安全组层面仅放行可信 IP。这一点与配置注释的语义一致allow_global_access属于“高风险兼容模式”它把静态密钥映射为全局服务身份常规推荐做法是使用用户级Authorization: Bearer Token配合平台的 RBACdocs/zh-CN/rbac.md做身份与权限控制而不是用一把全局密钥。Web 内 MCP 端点复用登录态的内部集成除了独立监听端口Web 服务还提供登录后可访问的 MCP 端点POST /api/mcp该端点复用 Web 认证用户会话适合内部页面或受控集成调用无需单独发放 MCP Token。其路由定义可以在 internal/handler/openapi.go 的 OpenAPI 描述中看到与/api/external-mcp系列管理接口并列。使用场景包括平台自带 Web 控制台内部的工具调用、以及通过浏览器扩展等已登录组件的受控集成。外部 MCP 联邦配置、管理 API 与完整字段外部 MCP 是联邦的核心配置写在external_mcp段external_mcp: servers: {}每个 server 的完整配置字段定义在 internal/config/config.go遵循官方 MCP 配置格式兼容 Claude Desktop / Cursor / VS Code 的写法external_mcp: servers: my-tool-server: type: stdio # stdio | sse | httpStreamable HTTPstdio 可省略有 command 时自动推断 command: /path/to/server # stdio 模式启动命令 args: [] # 命令参数 env: {} # 子进程环境变量 url: # HTTP/SSE 模式服务地址 headers: {} # HTTP/SSE 模式自定义请求头如认证 description: # 服务器描述 timeout: 30 # 连接超时秒默认 30 external_mcp_enable: true # 是否启用false 时仅保留配置不连接 tool_enabled: {} # 每个工具的启用状态细粒度开关 # 官方标准字段 disabled: false # 官方 disabled 字段与 external_mcp_enable 取反 autoApprove: [] # 自动批准的工具列表官方字段 # SDK 高级配置对应 MCP Go SDK 传输层参数 max_retries: 5 # Streamable HTTP 断线重连次数默认 5 terminate_duration: 5 # stdio 进程优雅关闭等待秒数默认 5 keep_alive: 0 # 客户端心跳间隔秒数0 禁用所有字符串字段均支持${VAR}与${VAR:-default}环境变量展开语法源码注释明确标注见 internal/config/config.go适合把 Token、密钥放在环境变量中而不落盘到 YAML。除了写配置文件也可以通过 Web 的MCP 管理页面新增、启动、停止和删除外部 MCP界面截图见 images/mcp-management.png对应前端 MCP 管理入口。管理页面的每个操作会同步写回 YAML 配置文件写回前会先创建config.yaml.backup备份见 internal/handler/external_mcp.go 的saveConfig实现降低误操作风险。管理 API 一览方法路径说明GET/api/external-mcp列出全部外部 MCP 配置、状态connected/disconnected/disabled/error/connecting与工具数量GET/api/external-mcp/stats汇总统计total / enabled / disabled / connectedGET/api/external-mcp/:name查询单个外部 MCP 详情PUT/api/external-mcp/:name新增或更新配置校验通过后自动连接POST/api/external-mcp/:name/start启动客户端立即返回后台异步连接POST/api/external-mcp/:name/stop停止客户端DELETE/api/external-mcp/:name删除配置并关闭客户端上述路由与行为在 internal/handler/external_mcp.go 中有完整实现并在 internal/handler/external_mcp_test.go 中有对应测试覆盖含 stdio、http、非法配置、删除、启动/停止等场景。注意几点PUT校验规则validateConfigHTTP 模式必须给urlstdio 模式必须给command否则返回 400不支持的传输类型也会被拒绝无mcp:write权限的会话在查询配置时env与headers中的敏感值会被打码为***internal/handler/external_mcp.go每次 upsert / delete 都会写入平台审计日志Categoryexternal_mcp便于事后追溯这也是原文档安全建议中“变更外部 MCP 后查看审计日志”的实现基础。传输模式stdio 与 HTTP/SSE 的接入关注点stdio适合本机命令启动的工具服务stdio MCP 由平台拉起一个子进程通过标准输入/输出与 MCP 协议通信。接入时关注命令路径必须存在command需为绝对路径或 PATH 内可解析的可执行文件工作目录正确部分 MCP Server 依赖相对路径读取配置启动目录不对会导致初始化失败环境变量完整通过env字段补全服务所需的 Key同样支持${VAR}展开进程退出会导致工具不可用stdio 子进程的生命周期与连接绑定进程异常退出后工具立即失效日志中查看启动失败原因启动失败会以error状态呈现GET /api/external-mcp返回的error字段携带具体原因连接被拒绝connection refused/dial tcp会被记录为 Warn 级“目标服务可能尚未启动”这是正常现象服务就绪后可通过界面手动连接或等待自动重试见 internal/mcp/external_manager.go 的StartAllEnabled。平台为每个已连接的外部 MCP 提供工具列表缓存TTL 60 秒见 internal/mcp/external_manager.go避免每次请求都打远程ListTools连接断开时还会降级使用缓存列表保证临时断网期间 Agent 的工具集不瞬间清空。HTTP / SSE适合远端或长期运行服务HTTPStreamable HTTP与 SSE 模式适合部署在远端或长期运行的服务。接入时关注URL 可达从平台所在主机能访问到目标地址认证头正确通过headers配置Authorization等请求头TLS 证书可信使用自签证书的服务需要先解决平台侧证书信任问题代理和防火墙放行平台与远端之间的网络策略需放行对应端口与协议服务端协议版本兼容MCP 协议版本不匹配会导致 Initialize 握手失败日志中会出现明确的初始化错误。传输类型判定逻辑在ExternalMCPServerConfig.GetTransportType()internal/config/config.go优先读type字段否则根据command→ stdio或url→ http自动推断。客户端统一由官方 MCP Go SDK 的 lazy client 创建newLazySDKClient连接在 Initialize 时完成doConnect默认超时 30 秒internal/mcp/external_manager.go。外部 MCP 生命周期七步全流程外部 MCP 的生命周期不是简单的“添加 URL”而是包含注册、连接、拉取、暴露、执行、恢复、移除的完整状态机注册配置名称、类型stdio/sse/http、命令或 URL、环境变量写入external_mcp.servers并可通过external_mcp_enable控制是否立即启用启动连接stdio 拉起子进程HTTP/SSE 建立客户端并完成 Initialize 握手状态先置为connecting前端立即可见实际连接在后台异步进行拉取工具列表调用ListTools获取工具名、描述与 JSON Schema写入平台工具缓存与工具数量统计空工具列表会记录 Warn 提示internal/mcp/external_manager.go暴露给 Agent工具以服务器名::工具名的格式进入平台工具池命名空间隔离见GetAllTools的前缀拼接并受角色、tool_search、HITL 策略共同约束执行工具参数校验、调用远端、记录执行状态与监控统计超长结果受tool_wait_timeout_seconds默认 300 秒限制到时返回execution_id由后台继续执行Agent 可用wait_tool_execution继续等待、cancel_tool_execution取消internal/mcp/external_manager.go连接恢复进程退出或网络失败后通过指数退避自动重连详见下节停止/删除关闭客户端、清空工具缓存与重连状态并从配置中移除停止时工具数量立即置 0。排错时要确认卡在哪一步是配置没写入、连接握手失败、工具没拉取到、被策略隐藏还是执行环节超时——对应到上一步的产物配置存在性、客户端状态、tool_count、工具可见性、execution_id能快速定位故障层级。连接恢复与韧性机制断连自愈、熔断与并发控制外部 MCP 的可用性保障在 internal/mcp/connection_recovery.go 与 internal/mcp/external_manager.go 中实现包含四层机制自动重连与指数退避检测到ListTools/CallTool失败且错误属于传输断开类型EOF、client is closing、connection reset、broken pipe等context.Canceled与超时除外会标记客户端为 disconnected 并调度重连isConnectionDeadError/handleConnectionDeadinternal/mcp/connection_recovery.go重连采用指数退避最短间隔 30 秒上限 5 分钟externalReconnectMinInterval/externalReconnectMaxBackoff见 internal/mcp/connection_recovery.go同一时刻同一 MCP 只允许一个重连 goroutinereconnecting去重已停用的服务不触发自动重连。熔断Circuit Breaker单个外部 MCP 连续失败达到阈值后进入熔断冷却期冷却期内调用直接快速失败并提示“已临时熔断预计 X 后重试”checkExternalMCPCircuitinternal/mcp/external_manager.go成功调用会清零连续失败计数并关闭熔断阈值与冷却时间可配置见下。并发控制信号量每个外部 MCP 有独立的并发信号量另有全局信号量兜底默认单服务 2、全局 16internal/mcp/external_manager.go获取信号量时遵循上下文取消避免调用方超时后仍占用并发额度。相关配置项config.example.yaml 的agent段agent: tool_wait_timeout_seconds: 300 # 工具本轮最多等待秒到时返回 execution_idworker 继续后台执行 external_mcp_max_concurrent_per_server: 5 # 单个外部 MCP server 同时运行的工具数0默认2负数不限制 external_mcp_max_concurrent_total: 16 # 所有外部 MCP 工具全局并发上限0默认16负数不限制 external_mcp_circuit_failure_threshold: 15 # 单个外部 MCP server 连续失败多少次后熔断0默认3负数关闭熔断 external_mcp_circuit_cooldown_seconds: 60 # 熔断冷却秒数0默认60这些参数会通过ConfigureResilience写入管理器运行时状态含默认值归一化逻辑normalizeExternalMCPResilienceConfig。对高负载或不可靠的外部服务建议显式调大并发上限并调整熔断阈值避免默认值过于保守或过于激进。工具暴露策略用 tool_search 控制上下文成本工具过多会增加上下文成本和误选概率尤其在多代理场景。CyberStrikeAI 通过tool_search机制实现“常用工具常驻、其余按需解锁”multi_agent: eino_middleware: tool_search_enable: true tool_search_min_tools: 20 tool_search_always_visible: 12 tool_search_always_visible_tools: - read_file - glob - grep - tool_search参数语义见 config.example.yaml 的详细注释tool_search_enable: true当工具总数达到tool_search_min_tools默认 20时启用动态工具搜索仅前 N 个工具常驻上下文其余按正则按需解锁省 token、减误选tool_search_always_visible: 12始终直接暴露给模型的工具个数顺序与角色工具列表一致tool_search_always_visible_tools后端内置常驻工具白名单优先级高于数量策略配置示例中的 read_file / glob / grep / tool_search 等为默认推荐集实际默认白名单还包含 analyze_image、write_file、edit_file、execute、task、transfer_to_agent、webshell_、batch_task_、record_vulnerability 等平台关键工具。外部 MCP 接入后其工具默认进入动态池不常驻由tool_search按名称/描述命中后解锁——这既控制了上下文成本也天然降低了“外部工具被误选”的概率。工具是否对当前 Agent 可见还受角色权限与 HITL 策略影响排查“工具看不到”时这三层都要检查。工具命名规范提升命中率、降低误调用工具名应稳定不随版本随意变更避免 Agent 记忆失效小写或 snake_case与平台内置工具风格一致便于tool_search正则匹配表达动作和对象动词 对象让 LLM 一眼理解用途避免和内置工具重名重名会与平台工具产生冲突外部工具统一带服务器名::前缀可缓解但内部命名仍需注意。不建议run execute scan tool1建议burp_send_to_repeater asset_lookup_domain cloud_list_public_buckets好的工具名会提升tool_search命中率也降低 Agent 误调用风险——名称本身就是最廉价的“接口文档”。安全建议与外部 MCP 安全审查清单安全基线建议外部 MCP 只接入可信服务不可信来源的工具描述、参数 schema 都可能被用于诱导 Agent远端 MCP 必须认证通过headers配置 Token / API Key避免裸奔在网络上高风险工具不要常驻上下文利用tool_search把外部工具放入动态池仅在需要时解锁外部 MCP 的文件系统和命令执行能力要单独评估一个能读写本机文件、能执行任意命令的 stdio 服务等于给 Agent 发了一把万能钥匙变更外部 MCP 后查看审计日志管理端 upsert / delete 均写入平台审计audit服务的external_mcp分类配合 docs/zh-CN/audit-and-monitoring.md 审计查询接口可回溯谁在何时改了什么。接入前安全审查清单接入任何一个外部 MCP 前先回答以下问题它能读写本机文件吗它能执行命令吗它会访问哪些网络它是否把请求发给第三方它的工具描述是否可信它的输出是否可能包含 prompt injection它是否需要独立运行用户或容器隔离只要答案不清楚就不要放进生产环境常驻工具池。对外部服务能力边界存疑时优先以独立系统用户或容器运行 stdio 服务缩小权限面对输出包含不可信文本的服务如扫描器结果、网页抓取要考虑 prompt injection 对后续 Agent 推理的污染风险。调试排查从状态到根因的五步法外部 MCP 接入出问题时按以下顺序排查对应 docs/zh-CN/troubleshooting.md 的通用排障思路GET /api/external-mcp/stats查看状态先确认 total / enabled / connected 是否符合预期判断是配置问题还是连接问题检查服务日志连接失败、Initialize 错误、重连尝试都会记录在平台日志中connection refused通常表示目标未启动单独运行 stdio 命令在命令行手动执行command args验证进程能否独立启动、协议是否正常握手用 curl 测试 HTTP/SSE 地址直接请求目标 URL 确认可达性、认证头与协议版本兼容性检查工具是否被角色或 tool_search 策略隐藏即使连接成功、工具已拉取角色权限或tool_search白名单也可能导致工具对当前 Agent 不可见确认tool_count正常后检查角色配置roles/ 下的 YAML与multi_agent.eino_middleware.tool_search_*配置。结合生命周期七步定位stats状态对应第 2 步连接、tool_count对应第 3 步拉取、工具可见性对应第 4 步暴露、execution_id与执行记录对应第 5 步执行。源码锚点速查以下文件是深入理解 MCP 联邦的实现入口外部 MCP Manager注册/启动/停止/调用/统计/熔断/并发控制internal/mcp/external_manager.go连接恢复断连检测、指数退避重连internal/mcp/connection_recovery.goMCP 工具适配工具定义到 Eino InvokableTool 的桥接internal/einomcp/mcp_tools.go外部 MCP Handler管理 API 与配置持久化internal/handler/external_mcp.go工具调用通知Eino run loop 与工具结果的 UI 联动internal/einomcp/tool_invoke_notify.go内置 MCP Server工具/提示词/资源注册internal/mcp/server.go外部 MCP 配置结构体字段定义与环境变量展开internal/config/config.go完整配置示例mcp / external_mcp / agent 弹性参数 / tool_searchconfig.example.yaml管理 API 测试用例internal/handler/external_mcp_test.go【免费下载链接】CyberStrikeAIThe system of action for AI-native cybersecurity—where intent becomes governed execution, evidence becomes operational memory, and every operation improves the next.项目地址: https://gitcode.com/GitHub_Trending/cy/CyberStrikeAI创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考