AgentField 内置 MCP Server：零配置让 Claude Code 等 AI 工具接入你的 Agent Mesh

AgentField 内置 MCP Server：零配置让 Claude Code 等 AI 工具接入你的 Agent Mesh

【免费下载链接】agentfieldBuild, run and scale AI agents like API and microservices项目地址: https://gitcode.com/gh_mirrors/ag/agentfield

AgentField 是一个让你像 API 和微服务一样构建、运行并扩展 AI Agent 的开源平台，它的控制平面（Control Plane）内置了一个 MCP（Model Context Protocol）Server：与 REST API 共用同一个端口、默认开启、无需额外进程。这意味着你部署好 AgentField 之后，Claude Code 等支持 MCP 的 AI 工具一条命令就能发现并驱动你集群里正在运行的所有 Agent——这就是"零配置"接入 Agent Mesh 的完整指南。

为什么 Agent 平台需要内置 MCP？

过去，如果你希望 Claude Code 这类"AI 编程工具"（业内称为 harness）调用你自己开发的 Agent，通常要写一层胶水代码：起一个独立的 MCP 服务进程、手动做身份认证、自己实现"发现—调用—轮询结果"的逻辑，还要保证它和 Agent 生命周期同步。

AgentField 的做法是把 MCP 端点直接嵌入控制平面本身，它和你熟悉的 REST API 生活在同一个信任域里：

• 端点：POST <server>/mcp（默认http://localhost:8080/mcp）
• 传输方式：streamable HTTP + JSON-RPC 2.0，无状态设计，没有会话协商，客户端不用维护任何连接状态
• 默认开启：想关掉只需设AGENTFIELD_MCP_ENABLED=false，端点会直接返回 404
• 同一套鉴权：如果控制平面配置了AGENTFIELD_API_KEY，MCP 端点同样要求该密钥，不会比 REST API 更宽松

路由注册逻辑可以直接在 routes_mcp.go 中看到，工具的实现则在 mcp.go。官方说明文档在 mcp-integration.md。

30 秒快速接入：Claude Code 连接步骤

整个"接入"过程只有一条命令：

claude mcp add --transport http agentfield http://localhost:8080/mcp

其他任何 MCP 客户端也一样：把 URL 指到<server>/mcp，传输方式选http（streamable-HTTP）即可。由于是无状态传输，没有别的东西需要配置。

如果控制平面开启了 API Key 鉴权，只需在客户端的 MCP 配置里加一个请求头：

X-API-Key: <你的密钥>

就这么多。没有独立进程要守护，没有会话要维护，控制平面重启了 MCP 端点也随它一起恢复。

5 个核心工具：发现、执行、等待，覆盖完整闭环

内置 MCP Server 对外暴露 5 个工具，刚好覆盖"发现 → 执行 → 轮询"的常用闭环：

工具	作用	返回
discover_agents	列出 Agent 及其健康状态、reasoner 列表（"active"只看健康的，"all"包含不健康的）	id、health_status、last_heartbeat、各 reasoner 的描述与标签
get_reasoner_schema	查询某个 reasoner 的输入/输出 JSON Schema、描述和标签	与发现接口一致的 Schema 定义
execute_reasoner	以"node.reasoner"为目标异步启动一次执行，目标不存在时会明确提示先调discover_agents	{ run_id, status: "accepted" }
get_run	查询某次 run 的当前状态	status、result/error及每个执行步骤的摘要
wait_run	服务端持续轮询直到 run 结束或超时（默认 60 秒，硬上限 120 秒）	同get_run，外加timed_out标志

两个值得注意的设计细节：

• 结果统一为紧凑 JSON 文本块——这是 harness 最容易可靠解析的形态；
• 业务错误走 MCP 工具错误（isError: true），而不是传输层错误，模型能看到"目标不存在，请先调 discover_agents"这类提示并自己纠正。

wait_run的超时硬上限尤其贴心：一次工具调用永远不会把整个 harness 挂死（实现见 mcp.go 的 wait 边界定义）。

一次真实调用流程：4 步让 AI 工具替你跑 Agent

假设你的集群里装了一个swe-planner节点，带一个buildreasoner。Claude Code 拿到任务"给仓库加 JWT 认证"后，会自然地按下面 4 步走：

1. discover_agents→ 找到swe-planner节点和它的buildreasoner
2. get_reasoner_schema{ node: "swe-planner", reasoner: "build" }→ 搞清楚输入长什么样
3. execute_reasoner{ target: "swe-planner.build", input: { goal: "Add JWT auth" } }→ 拿到{ run_id, status: "accepted" }
4. wait_run{ run_id, timeout_seconds: 120 }→ 阻塞到执行结束（或timed_out: true），直接读result

全程不需要 AI 工具写一行代码，它只是"看到了你的 Agent 集群，并且知道怎么调用"。这正是 MCP 的价值：把 Agent Mesh 变成 AI 工具的原生工具面。

安全边界与能力分层

• 同一信任域：/mcp和控制平面绑定在同一个地址上，权限模型与 REST API 完全一致——它会启动异步执行、读取运行状态，走的也是同一层服务与全局 API Key 鉴权。不要指望把端口暴露给不可信网络后/mcp会比/api/v1更安全，它并不是。
• 可彻底关闭：AGENTFIELD_MCP_ENABLED=false会直接不注册该路由，/mcp返回 404。
• 能力分层：MCP 覆盖的是"发现 → 执行 → 轮询"的通用路径；afCLI 和 REST API 仍然是全能力路径（会话、流式、取消树、密钥、负载感知调度等），任务更复杂时切换到它们即可。

小结

你关心的	AgentField 内置 MCP Server 的答案
要部署几个进程？	0 个，端点嵌在控制平面里，同端口同生命周期
要写多少配置？	Claude Code 一条命令，可选一个 API Key 头
能做什么？	发现健康 Agent、读 Schema、异步执行、等待结果
安全吗？	与 REST API 同信任域、同鉴权，可一键整体关闭
文档在哪？	docs/mcp-integration.md

AgentField 把 Agent 当作微服务来编排，而内置 MCP Server 则把整个 Agent Mesh 变成 AI 编程工具"开箱即用"的工具集——下一步，你可以参考 README.md 里的示例（如 SWE 工程团队、深度研究引擎）装上几个现成 Agent 节点，让 Claude Code 替你跑起来。

【免费下载链接】agentfieldBuild, run and scale AI agents like API and microservices项目地址: https://gitcode.com/gh_mirrors/ag/agentfield