Solon v4.1.1

harness - MCP 服务接入

</> markdown
2026年10月8日 上午9:12:56

马具可以接入 MCP（Model Context Protocol）服务，把第三方工具网关扩展为 Agent 可调用的工具。MCP 服务既可在构建期静态注册，也可在运行时动态增删。LSP 代码理解服务见 《harness - LSP 服务接入》，OpenAPI 业务接口接入见 《harness - OpenAPI 业务接口接入》。

1、开启 MCP 工具权限

mcp 只出现在 **（全部完整）的展开列表中（AgentFactory.TOOL_ALL_FULL），* 不会开启它，因此需要显式授权：

HarnessEngine engine = HarnessEngine.of("work", ".soloncode/")
        .sessionProvider(sessionProvider)
        .toolsAdd(ToolName.TOOL_MCP)        // 开启 mcp 工具权限
        .build();

也可以在运行时动态授权：

engine.allowTool("mcp");

2、构建期静态注册

McpServerParameters 是普通 Java Bean（提供 then(...) 与 setter，没有 builder）。URL 方式必须设置 type（或 transport），否则建立连接时会抛 IllegalArgumentException：

McpServerParameters github = new McpServerParameters();
github.setType("streamable");                   // 或 "sse"
github.setUrl("http://localhost:8080/mcp");
github.setTimeout(Duration.ofSeconds(30));

HarnessEngine engine = HarnessEngine.of("work", ".soloncode/")
        .sessionProvider(sessionProvider)
        .toolsAdd(ToolName.TOOL_MCP)
        .mcpServerAdd("github", github)
        .build();

也可以用 then(...) 链式构造：

McpServerParameters github = new McpServerParameters().then(p -> {
    p.setType("streamable");
    p.setUrl("http://localhost:8080/mcp");
});

stdio 方式则改为配置启动命令：

McpServerParameters filesystem = new McpServerParameters();
filesystem.setCommand("npx");
filesystem.addArgVar("-y");
filesystem.addArgVar("@modelcontextprotocol/server-filesystem");
filesystem.addEnvVar("HOME", "/Users/me");

多个 MCP 服务可以继续追加：

HarnessEngine engine = HarnessEngine.of("work", ".soloncode/")
        .sessionProvider(sessionProvider)
        .toolsAdd(ToolName.TOOL_MCP)
        .mcpServerAdd("github", githubMcpServer)
        .mcpServerAdd("slack", slackMcpServer)
        .build();

McpServerParameters 常用字段：

字段说明
type / transport通道类型：stdio、sse、streamable、streamable_stateless；设置了 url 时必填，未设置 url 时按 stdio 处理
url远程服务地址（sse / streamable 等）
headers请求头，可用 addHeaderVar(key, value) 追加
command / args / envstdio 方式的启动命令、参数与环境变量；参数用 addArgVar(arg)、环境变量用 addEnvVar(key, value) 追加
allowedTools / disallowedTools工具白名单 / 黑名单，getToolsActivated() 按此裁剪；可用 addAllowedTool / addDisallowedTool 追加
timeoutHTTP 超时，类型为 Duration
enabled是否启用，默认 true

注意：构建期注册的 MCP 服务，如果 McpServerParameters.isEnabled() 返回 false，则不会被连接，只会保留配置（仅登记到管理表，不出工具）。运行时添加的服务同样遵循 isEnabled()：启用时立即建立连接并把工具加入索引，禁用时只登记不出工具。

3、运行时动态管理

引擎启动后，仍可动态添加、刷新或移除 MCP 服务：

engine.addMcpServer("slack", mcpServerParameters);   // 添加并连接
engine.getMcpServer("slack");                        // 获取 McpClientProvider
engine.refreshMcpServer("slack");                    // 刷新（权限变更后）
engine.removeMcpServer("slack");                     // 移除并关闭连接

动态注册会同步到引擎配置中，并即时对后续会话生效。

4、说明

配置 / 权限说明
ToolName.TOOL_MCP开启 MCP 工具权限
mcp工具权限名，运行时可通过 allowTool("mcp") 授权
mcpServersMCP 服务配置集合
mcpRetriesMCP 调用重试次数，默认 3
McpServerParameters.isEnabled()MCP 服务是否启用，禁用的服务不会被连接

MCP 工具由 McpGatewayTalent 统一网关管理。授权方式见 《harness - 配置参考》。