---
title: "harness - MCP 服务接入"
---


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

### 1、开启 MCP 工具权限

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

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

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

```java
engine.allowTool("mcp");
```

### 2、构建期静态注册

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

```java
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(...)` 链式构造：

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

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

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

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

```java
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` / `env` | `stdio` 方式的启动命令、参数与环境变量；参数用 `addArgVar(arg)`、环境变量用 `addEnvVar(key, value)` 追加 |
| `allowedTools` / `disallowedTools` | 工具白名单 / 黑名单，`getToolsActivated()` 按此裁剪；可用 `addAllowedTool` / `addDisallowedTool` 追加 |
| `timeout` | HTTP 超时，类型为 `Duration` |
| `enabled` | 是否启用，默认 `true` |

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

### 3、运行时动态管理

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

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

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

### 4、说明

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

> MCP 工具由 `McpGatewayTalent` 统一网关管理。授权方式见 [《harness - 配置参考》](/article/1427)。