news 2026/7/30 17:57:06

用Spring Boot搭建企业MCP工具网关：统一接入、租户隔离、白名单与审计

作者头像

张小明

前端开发工程师

1.2k 24
文章封面图
用Spring Boot搭建企业MCP工具网关：统一接入、租户隔离、白名单与审计

文章摘要

企业接入多个MCP Server后，如果让每个Agent直接连接订单、仓储、客户、知识库和文件工具，会快速出现认证分散、工具重名、权限不一致、审计缺失和服务端地址泄露等问题。本文使用Spring Boot设计一个MCP工具网关：上游连接多个MCP Server，下游向Agent提供统一工具目录，并在调用前执行租户校验、工具白名单、风险审批、参数脱敏、超时和审计。文章给出核心数据模型、路由代码和生产配置思路。

一、为什么需要MCP工具网关

没有网关时：

Agent A ├─ 订单MCP ├─ 仓储MCP ├─ CRM MCP └─ 知识库MCP Agent B ├─ 订单MCP ├─ 仓储MCP └─ 财务MCP

问题包括：

  • 每个Agent保存多套凭证；
  • MCP Server地址暴露给业务应用；
  • 权限规则分散；
  • 工具名称冲突；
  • 无法统一限流；
  • 无法统一审计；
  • Server升级需要修改多个客户端；
  • 模型可能看到不该看到的工具；
  • 故障降级困难。

引入网关：

Agent → MCP Tool Gateway → Order MCP → WMS MCP → CRM MCP → Knowledge MCP

网关成为控制面，而不是简单反向代理。

二、网关应该负责什么

MCP Server注册 工具发现 工具名称规范化 租户与用户权限 工具白名单 风险分级 审批 限流 超时 重试 幂等 审计 可观测性 降级

网关不应该承载所有业务逻辑。

订单查询逻辑仍在订单服务，网关只负责是否允许调用以及如何安全路由。

三、项目结构

mcp-tool-gateway ├── config │ ├── McpClientConfig.java │ └── SecurityConfig.java ├── catalog │ ├── ToolCatalog.java │ ├── ToolDescriptor.java │ └── ToolCatalogRefresher.java ├── policy │ ├── ToolPolicyService.java │ ├── RiskLevel.java │ └── PermissionDecision.java ├── routing │ ├── ToolRouter.java │ └── UpstreamMcpServer.java ├── execution │ ├── ToolExecutionService.java │ ├── IdempotencyService.java │ └── ApprovalService.java ├── audit │ ├── ToolAuditService.java │ └── ToolAuditEvent.java └── web ├── ToolCatalogController.java └── ToolExecutionController.java

四、依赖

<dependencyManagement><dependencies><dependency><groupId>org.springframework.ai</groupId><artifactId>spring-ai-bom</artifactId><version>2.0.0</version><type>pom</type><scope>import</scope></dependency></dependencies></dependencyManagement><dependencies><dependency><groupId>org.springframework.ai</groupId><artifactId>spring-ai-starter-mcp-client-webflux</artifactId></dependency><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-webflux</artifactId></dependency><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-security</artifactId></dependency><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-actuator</artifactId></dependency><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-validation</artifactId></dependency></dependencies>

五、上游Server配置

enterprise:mcp:servers:order:url:https://internal.example.com/order/mcptimeout:20sname-prefix:orderwarehouse:url:https://internal.example.com/wms/mcptimeout:30sname-prefix:wmsknowledge:url:https://internal.example.com/knowledge/mcptimeout:15sname-prefix:knowledge

不要把Token直接写进YAML。

使用：

  • Vault；
  • Kubernetes Secret；
  • 云Secret Manager；
  • OAuth客户端凭证；
  • 工作负载身份。

六、统一工具描述模型

publicrecordToolDescriptor(StringgatewayToolName,StringupstreamServer,StringupstreamToolName,Stringdescription,StringinputSchema,RiskLevelriskLevel,Set<String>requiredScopes,booleanapprovalRequired,Durationtimeout){}

风险等级：

publicenumRiskLevel{LOW,MEDIUM,HIGH,CRITICAL}

示例：

knowledge_search_policy → LOW order_query_status → LOW order_cancel → HIGH finance_refund → CRITICAL

七、工具名称规范化

上游可能都存在：

search get_status create

网关统一命名：

order_get_status wms_get_inventory crm_search_customer knowledge_search_policy

映射：

publicStringgatewayName(Stringprefix,StringupstreamName){returnnormalize(prefix)+"_"+normalize(upstreamName);}

名称一旦对模型开放，应保持稳定。

上游改名时，网关可以保留旧别名，避免Prompt和评测集全部失效。

八、工具目录刷新

@ComponentpublicclassToolCatalogRefresher{privatefinalToolCatalogcatalog;privatefinalList<McpSyncClient>clients;@Scheduled(fixedDelayString="${enterprise.mcp.refresh:PT5M}")publicvoidrefresh(){for(McpSyncClientclient:clients){refreshClient(client);}}privatevoidrefreshClient(McpSyncClientclient){varresult=client.listTools();catalog.replace(client.getServerInfo().name(),result.tools());}}

生产代码需要处理：

  • 单个Server失败不清空旧目录；
  • 保存最后成功版本；
  • 记录刷新时间；
  • 校验工具Schema；
  • 检查高风险工具是否有策略；
  • 支持listChanged主动刷新。

九、租户和用户上下文

publicrecordGatewayRequestContext(StringrequestId,StringtenantId,StringuserId,Set<String>scopes,StringclientId){}

这些信息应从认证系统获取，而不是信任模型生成的参数。

错误：

{"tenantId":"T002"}

模型可以随意修改。

正确：

Access Token → SecurityContext → GatewayRequestContext

十、工具白名单

每个租户可以配置：

允许工具 禁止工具 按环境允许 按用户角色允许

数据模型：

publicrecordToolAccessPolicy(StringtenantId,StringtoolName,booleanenabled,Set<String>allowedRoles,Set<String>requiredScopes,intcallsPerMinute){}

决策：

publicPermissionDecisiondecide(GatewayRequestContextcontext,ToolDescriptortool){if(!tenantPolicy.enabled(tool.gatewayToolName())){returnPermissionDecision.deny("租户未启用该工具");}if(!context.scopes().containsAll(tool.requiredScopes())){returnPermissionDecision.deny("缺少必要Scope");}returnPermissionDecision.allow();}

十一、执行前参数校验

模型提交参数后先做：

JSON Schema校验 Bean Validation 业务范围校验 资源归属校验 敏感字段检测

例如：

publicrecordCancelOrderArgs(@NotBlankStringorderId,@NotBlankStringreason){}

还要验证：

订单是否属于当前租户 订单是否允许取消 当前用户是否有操作权限

JSON Schema合法并不代表业务合法。

十二、高风险工具审批

if(tool.approvalRequired()){ApprovalRequestapproval=approvalService.create(context,tool,sanitizedArguments);returnToolExecutionResult.pendingApproval(approval.id());}

审批页面展示：

  • 工具名称；
  • 业务影响；
  • 参数；
  • 当前用户；
  • 当前租户；
  • 风险原因；
  • 幂等键；
  • 预计执行结果。

批准后重新读取最新权限与业务状态，不能直接使用旧审批上下文永久执行。

十三、幂等设计

写操作需要幂等键：

tenantId ＋toolName ＋businessObjectId ＋requestIntentHash
publicStringbuildIdempotencyKey(GatewayRequestContextcontext,ToolDescriptortool,StringobjectId,StringargumentHash){returnString.join(":",context.tenantId(),tool.gatewayToolName(),objectId,argumentHash);}

重复请求：

返回第一次执行结果 而不是再次取消订单或重复退款

十四、调用路由

@ServicepublicclassToolRouter{privatefinalMap<String,McpSyncClient>clients;privatefinalToolCatalogcatalog;publicCallToolResultroute(StringgatewayToolName,Map<String,Object>arguments){ToolDescriptordescriptor=catalog.require(gatewayToolName);McpSyncClientclient=clients.get(descriptor.upstreamServer());returnclient.callTool(descriptor.upstreamToolName(),arguments);}}

实际API方法应按使用的MCP Java SDK版本调整，但架构原则一致。

十五、超时与重试

查询类工具：

可有限重试

写操作：

只有确认幂等后才能重试

策略：

工具超时重试
知识检索10秒1次
订单查询5秒1次
取消订单15秒默认0次
退款30秒默认0次

不要让HTTP客户端、MCP客户端、网关和Agent四层同时重试。

十六、审计事件

publicrecordToolAuditEvent(StringrequestId,StringtenantId,StringuserId,StringtoolName,StringupstreamServer,StringargumentHash,StringresultStatus,longdurationMs,StringapprovalId,Instanttimestamp){}

日志中不要直接记录：

  • 密码；
  • Token；
  • 身份证；
  • 银行卡；
  • 完整客户隐私；
  • 文件正文。

保存：

脱敏参数 参数Hash 结果状态 影响对象ID

十七、向Agent暴露工具

网关可以有两种方式：

方式一：网关本身作为MCP Server

Agent MCP Client → Gateway MCP Server → Upstream MCP Servers

优点是协议统一。

方式二：转换为Spring AI ToolCallback

ChatClient → ToolCallback → Gateway内部路由

适合只服务Spring AI应用。

企业更通用的方式是让网关对外暴露标准MCP Server。

十八、健康检查

每个上游记录：

connected protocol_version tool_count last_refresh last_success error_rate P95_latency

网关整体不能因为一个非核心Server失败就完全不可用。

工具级降级：

知识工具不可用 → 隐藏知识工具 订单查询不可用 → 返回明确错误 退款工具不可用 → 禁止执行并转人工

十九、监控指标

mcp_gateway_tool_call_count mcp_gateway_tool_denied_count mcp_gateway_approval_count mcp_gateway_upstream_latency mcp_gateway_upstream_error mcp_gateway_catalog_tool_count mcp_gateway_catalog_refresh_failure mcp_gateway_idempotency_hit mcp_gateway_cross_tenant_denied

二十、生产检查清单

□ 上游Server统一注册 □ 工具名称稳定且不冲突 □ 凭证不下发给业务Agent □ 工具目录按租户过滤 □ 执行时再次鉴权 □ 高风险工具要求审批 □ 写操作具有幂等键 □ 参数和结果日志已脱敏 □ 超时与重试按工具配置 □ 上游故障支持工具级降级 □ 每次调用可以追溯 □ 跨租户请求默认拒绝

总结

企业MCP工具网关的价值不是把多个URL合并成一个URL，而是建立统一的工具控制面：

发现 ＋命名 ＋权限 ＋审批 ＋幂等 ＋审计 ＋观测

当工具数量、Agent数量和租户数量增长后，这一层会成为MCP进入生产环境的关键基础设施。

版权声明: 本文来自互联网用户投稿，该文观点仅代表作者本人，不代表本站立场。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。如若内容造成侵权/违法违规/事实不符，请联系邮箱：809451989@qq.com进行投诉反馈，一经查实，立即删除！
网站建设 2026/7/30 17:52:34

PRD 的工程化：从模糊需求到可验收交付

很多人把 PRD 理解成一份"需求记录文档"——需求先存在于某个地方&#xff0c;然后被写进文档。这个过程恰恰是反的。需求不是被记录的&#xff0c;是被构造的。用户说"我想要一个搜索功能"&#xff0c;这不是需求&#xff0c;这是一个愿望。PRD 的工作是把…

作者头像 李华
网站建设 2026/7/30 17:51:01

dg-ai-notes扩展系统：零代码为Agent添加新能力的终极指南

dg-ai-notes扩展系统&#xff1a;零代码为Agent添加新能力的终极指南 【免费下载链接】dg-ai-notes 项目地址: https://gitcode.com/gh_mirrors/dg/dg-ai-notes dg-ai-notes项目的Pi-Agent框架提供了强大的扩展系统&#xff0c;让开发者无需修改核心源码就能为AI Agent…

作者头像 李华
网站建设 2026/7/30 17:49:27

机器狗终于能倒猫粮了Vbot大头EDU发布

现在市面上机器狗可真不少&#xff0c;能自己躲开障碍、跟在主人后头溜达、在房间自由穿行&#xff0c;甚至还能摆个表情逗你开心。可问题是&#xff0c;当它站到一袋猫粮跟前&#xff0c;却拿那袋猫粮没辙——不会倒进碗里&#xff0c;也没法拉窗帘&#xff0c;你说“帮我把这…

作者头像 李华