Logo
4 mins read

MCP 配置与排障说明

围绕 client_id=3001 的 MCP 传输方式、配置链路与测试流程的排障笔记

#MCP #排障 #配置
MCP 配置与排障说明

本文整理本次排障涉及的关键问题、原因、改动与验证步骤，覆盖 MCP 三种传输方式、数据库关联链路，以及两种测试流程。

NOTE

本文示例以 client_id=3001 为准，其他环境只需替换对应 ID 与 endpoint。

传输方式对照h2

传输方式入口协议默认路径适用场景
stdio本地进程stdin/stdout-本地工具或脚本
sseHTTP事件流/sse事件流推送
streamableHTTP流式请求/mcpHTTP 流式 MCP
IMPORTANT

transport_type 必须与 endpoint 对应，/mcp 只能走 streamable，不要用 SSE 请求它。

常见问题（Q&A）h2

Q1：为什么 stdio MCP 会报 “Access denied - path outside allowed directories”？

filesystem MCP 只允许访问启动参数指定路径。反斜杠里的 \\n 会被解析成换行，导致路径被截断。请使用正斜杠路径，例如 E:/Java_study/new_start/txt.md。

Q2：SSE 和 streamable 是同一种吗？

不是。stdio 是本地 stdin/stdout；SSE 是事件流；streamable 是 HTTP 流式入口。三者是不同传输方式。

Q3：为什么配置了 /mcp 却触发 SSE 405？

当 transport_type=sse 时，客户端会用 SSE GET 访问 /mcp，服务端会拒绝（405）。应改为 streamable。

Q4：为什么最终只拿到 model_id=2001，还需要那么多节点流程？

规则树节点负责依次装配 API、MCP 工具和模型。model_id=2001 是最终结果，但依赖的配置来自前面的节点。

核心改动与原理h2

1) 增加 streamable 传输类型h3

  • 原理：把 /mcp 从 SSE 中剥离为独立传输类型，避免协议混用。

2) createMcpSyncClient 三分支处理h3

  • stdio：StdioClientTransport + JacksonMcpJsonMapper
  • sse：HttpClientSseClientTransport（默认 /sse）
  • streamable：HttpClientStreamableHttpTransport（默认 /mcp）
  • resolveHttpEndpoint 统一处理 baseUri + endpoint

3) 数据库示例配置更新h3

  • transport_type 扩展为 sse/stdio/streamable
  • 示例 5002 调整为 streamable + /mcp

4) 规则树节点注释h3

  • 明确 RootNode、ApiNode、ToolMcpNode、ModelNode 的装配职责

5) 测试提示词修复h3

  • 路径改为正斜杠，避免 \\n 被解析成换行
  • 提示词明确调用 write_file 并写入 hello
涉及文件清单
  • ai-agent-station-domain/src/main/java/cn/zy/domain/agent/model/valobj/AiClientToolMcpVO.java
  • ai-agent-station-infrastructure/src/main/java/cn/zy/infrastructure/dao/po/AiClientToolMcp.java
  • ai-agent-station-infrastructure/src/main/java/cn/zy/infrastructure/adapter/repository/AgentRepository.java
  • ai-agent-station-domain/src/main/java/cn/zy/domain/agent/service/armory/AiClientToolMcpNode.java
  • docs/dev-ops/mysql/sql/ai-agent-station-study.sql
  • ai-agent-station-domain/src/main/java/cn/zy/domain/agent/service/armory/RootNode.java
  • ai-agent-station-domain/src/main/java/cn/zy/domain/agent/service/armory/AiClientApiNode.java
  • ai-agent-station-domain/src/main/java/cn/zy/domain/agent/service/armory/AiClientModelNode.java
  • ai-agent-station-app/src/test/java/cn/zy/ai/test/domain/AgentTest.java

createMcpSyncClient 逻辑速览h2

  • stdio：本地进程直连
  • sse：baseUri + sseEndpoint（默认 /sse）
  • streamable：baseUri + streamableEndpoint（默认 /mcp）
  • 关键点：配置决定协议，不再通过 /mcp 自动推断

数据库关联链路（client_id=3001）h2

  • ai_agent_flow_config：agent_id=1 -> client_id=3001
  • ai_client：client_id=3001
  • ai_client_config（client 维度）：model 2001、prompt 6001、advisor 4001/4002/4003
  • ai_client_model：model_id=2001 -> api_id=1001
  • ai_client_api：api_id=1001
  • ai_client_config（model 维度）：tool_mcp 5001/5002
  • ai_client_tool_mcp：5001 stdio filesystem；5002 streamable /mcp

测试方法执行流程h2

1) AgentTest.test_aiClientApiNodeh3

  1. 通过 DefaultArmoryStrategyFactory 执行规则树
  2. RootNode 加载 ai_client_* 数据到动态上下文
  3. AiClientApiNode 注册 OpenAiApi Bean（1001）
  4. 测试用 applicationContext.getBean(ai_client_api_1001) 获取 API 实例

结果：验证 API Bean 是否能被正确装配。

2) AgentTest.test_aiClientModelNodeh3

  1. 规则树：RootNode -> ApiNode -> ToolMcpNode -> ModelNode
  2. AiClientToolMcpNode 初始化 MCP 客户端
  3. AiClientModelNode 组装 OpenAiChatModel (model_id=2001)
  4. applicationContext.getBean(ai_client_model_2001) 获取模型
  5. 提示词要求调用 write_file，写入 E:/Java_study/new_start/txt.md

结果：模型调用 MCP filesystem 工具完成文件写入。

TIP

若要强制工具调用，可设置 toolChoice=required，并确保提示词包含明确的写入路径。

排障清单h2

  • 确认 transport_type 与 endpoint 完全匹配
  • 校验 baseUri + endpoint 拼接后可访问
  • stdio MCP 的允许路径包含目标目录
  • 测试路径使用正斜杠
  • 如需强制工具调用，启用 toolChoice=required