MCP Aggregator

MCP 聚合器使用说明

MCP Java SDK（io.modelcontextprotocol.sdk:mcp）实现 MCP 服务端聚合与代理调用能力。本文档说明运行方式、配置要点、权限与过滤机制、调用示例及故障排查。

简易MCP聚合 （使用codex编写）   

项目概述

• MCP 端点：/mcp（Streamable HTTP）
• 聚合两类工具：

- 远程 MCP 工具（STDIO / SSE / Streamable HTTP）：通过上游客户端采集工具列表并代理调用 - 本地 API 工具（VIRTUAL）：从数据库维护的 HTTP API 定义生成 MCP 工具并转发请求

• 权限控制：基于访问令牌 Token 进行会话级工具过滤（列表过滤 + 调用兜底）

运行环境

• JDK：21
• 构建：Gradle 8.x
• 数据库：默认 H2（./db/demo），可外置数据库通过 Spring 配置覆盖
• 端口：server.port（默认 18080）

快速开始

# 构建
gradle build -x test

# 开发运行
gradle bootRun

# 生产运行
java -jar build/libs/*-SNAPSHOT.jar

• MCP 端点：http://localhost:18080/mcp
• H2 控制台（默认开启）：/h2-console

上游 MCP 服务配置

支持三种类型：

• STDIO：配置 command + arguments（可选 environment）
• SSE：配置 baseUrl + endpoint（连接前预检 text/event-stream）
• Streamable HTTP：配置 baseUrl + endpoint

同步工具：

• 创建/更新服务会触发工具刷新
• 也可通过“同步工具”操作主动刷新（参考 Controller/Service）

本地 API 工具（VIRTUAL）

• 在数据库维护 HTTP API 定义（URL、PATH、METHOD、HEADERS、超时、输入 Schema）
• 将 API 工具绑定到 VIRTUAL 类型服务，自动生成同名 MCP 工具并由服务端执行 HTTP 请求

相关数据与服务：

• API 工具仓储：src/main/kotlin/com/app/repository/mcp/ApiToolRepository.kt:1
• API 工具业务：src/main/kotlin/com/app/service/mcp/ApiToolService.kt:1
• VIRTUAL 工具生成/同步：src/main/kotlin/com/app/service/mcp/VirtualToolRegistry.kt:1

命名空间与重名规避

• 为避免不同上游工具重名，远程 MCP 工具注册时使用“展示名”：`

.`

• 服务的 prefix 为空时，沿用原始工具名
• 调用远端时仍使用原始工具名（仅注册展示名加前缀）

权限与工具过滤

请求头：

• Authorization: Bearer

工具刷新机制

• 创建/更新 MCP 服务、绑定/解绑 API 工具、远程工具列表同步成功后 → 自动触发注册集刷新
• 刷新策略：计算差异 → addTool/removeTool → notifyToolsListChanged() 通知客户端刷新
• 刷新入口：src/main/kotlin/com/app/mcp/McpAggregator.kt:52

JSON-RPC 调用示例

tools/list：

POST http://localhost:18080/mcp
Content-Type: application/json
Authorization: Bearer 

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "tools/list",
  "params": {}
}

tools/call：

POST http://localhost:18080/mcp
Content-Type: application/json
Authorization: Bearer 

{
  "jsonrpc": "2.0",
  "id": "2",
  "method": "tools/call",
  "params": {
    "name": "",
    "arguments": {
      "k": "v"
    }
  }
}

故障排查

• 远程工具未出现：

- 检查服务是否启用、类型是否正确 - SSE 端点需返回 text/event-stream（预检失败会在日志中提示） - 是否配置了 prefix 导致展示名变化

• 调用被拒：

- Token 是否包含该“展示名”的授权（当服务有 prefix 时应为 .）

• 列表未过滤：

- 是否带了有效 Token - 查看 McpAccessTokenFilter 日志是否建立上下文

变更记录

• 替换 Spring AI → 纯 MCP Java SDK
• 移除：Spring AI 相关依赖与工具回调 Provider
• 新增：McpServletConfig、McpAggregator（服务端直接注册工具并代理调用）
• 加强：基于前缀的命名空间、会话级列表过滤与调用兜底

如需进一步将权限注入迁移到 MCP 传输上下文（替代 ThreadLocal），或增加示例脚本（Postman / HTTPie），请在 Issue 或任务中说明。