1. FastGPT 接入 MCP 时为什么传输通道要先想清楚FastGPT 的 MCP 集成设计核心要解决的是「外部工具怎么进来、内部应用怎么出去」这件事。MCP 全称 Model Context Protocol你可以把它理解成一套让模型和外部工具对话的通用插头标准工具方按协议暴露能力调用方按协议发现工具、传参、拿结果。FastGPT 在这里同时扮演两个角色——既能把内部的应用、工作流、Workflow Tool 发布成 MCP Server 给 Cursor、Cherry Studio 这类客户端用也能作为 MCP Client 去接入远端的 MCP Server把别人的工具变成本地 ToolSet 挂到 Agent 或工作流里。真正让人卡住的往往不是「要不要接 MCP」而是传输通道怎么选。MCP 目前主流有两种传输方式Streamable HTTP 和 SSE。Streamable HTTP 是较新的方式一个 POST 端点就能完成请求响应部署简单、对网关友好SSE 是较早的方式靠一条长连接推送事件再用另一个 POST 端点回传消息兼容性好但需要维护 session。FastGPT 的设计是客户端优先尝试 Streamable HTTP遇到 4xx 再回退到 SSE这样新旧服务都能接上。这篇面向的是已经在用 FastGPT、准备把 MCP 接进工作流或 Agent 的开发者。我会给出config.toml和settings.json的可复制骨架演示连通性验证动作并把配置到调用的闭环走一遍。如果你还没拿到可用的模型调用凭证可以先去 TaoToken 的模型对话页试一下工具调用链路是否通https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 确认模型侧没问题再往下配 MCP能省掉不少排查时间。2. 前置准备TaoToken 凭证与 FastGPT 环境在动 MCP 配置之前先把两样东西备齐一个能正常调用的模型凭证一个跑起来的 FastGPT 实例。模型凭证这块TaoToken 提供 OpenAI 兼容的接口FastGPT 里配置模型渠道时直接填就行。先到控制台创建 API Keyhttps://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 然后在 API Keys 页面生成密钥https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 。接口地址用https://taotoken.net/api注意这个地址不带任何查询参数直接填进 FastGPT 的模型渠道 Base URL 即可。FastGPT 侧需要确认三件事。第一主应用能正常启动/api路由可访问。第二如果要兼容只支持 SSE 的 MCP 客户端需要额外部署独立的fastgpt-mcp-server服务它默认监听容器 3000 端口。第三环境变量里SSE_MCP_SERVER_PROXY_ENDPOINT要指向外部客户端能访问到的 SSE 服务公网地址否则前端使用方式页不会显示 SSE 入口。这里有个容易混的点FASTGPT_ENDPOINT是 MCP SSE 服务访问 FastGPT 主应用的内网地址比如http://fastgpt-app:3000而SSE_MCP_SERVER_PROXY_ENDPOINT是外部 MCP Client 访问 MCP SSE 服务的公网地址。两个地址方向相反配反了就连不通。如果你打算长期跑编码类或 Agent 类任务建议顺手了解下 Coding Plan额度模型更适合高频工具调用场景https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 。3. 可复制配置config.toml 与 settings.json 骨架下面给出两套骨架。config.toml用于 FastGPT 主应用和独立 MCP Server 的部署配置settings.json用于 MCP 客户端侧的连接配置。3.1 config.tomlFastGPT 主应用与 MCP Server# FastGPT 主应用环境变量片段 [app] # 主应用对外 API 地址MCP Server 通过它回调 FASTGPT_ENDPOINT http://fastgpt-app:3000 # 外部 MCP Client 访问 SSE 服务的公网地址 SSE_MCP_SERVER_PROXY_ENDPOINT https://your-domain.com/mcp # 独立 SSE MCP Server 服务 [mcp_server] container_name fastgpt-mcp-server image ghcr.io/labring/fastgpt-mcp_server:v4.14.23 ports [3003:3000] restart always [mcp_server.environment] # 容器内部访问主应用的地址走内网 FASTGPT_ENDPOINT http://fastgpt-app:3000 PORT 3000关键参数对照参数作用典型值FASTGPT_ENDPOINTMCP Server 回调主应用的基地址http://fastgpt-app:3000SSE_MCP_SERVER_PROXY_ENDPOINT前端拼接 SSE 地址用的公网前缀https://your-domain.com/mcpPORTMCP Server 监听端口3000注意FASTGPT_ENDPOINT不要填公网地址容器间走内网更稳SSE_MCP_SERVER_PROXY_ENDPOINT不要填内网地址否则外部客户端访问不到。3.2 settings.jsonMCP 客户端连接配置Streamable HTTP 方式地址形如{baseUrl}/mcp/app/{mcpKey}/mcp{ mcpServers: { fastgpt-mcp-http: { url: https://your-domain.com/api/mcp/app/YOUR_MCP_KEY/mcp } } }SSE 方式地址形如{proxyEndpoint}/{mcpKey}/sse{ mcpServers: { fastgpt-mcp-sse: { url: https://your-domain.com/mcp/YOUR_MCP_KEY/sse } } }带自定义请求头的场景比如远端 MCP Server 需要鉴权{ mcpServers: { remote-mcp: { url: https://remote.example.com/mcp, headers: { Authorization: Bearer YOUR_REMOTE_TOKEN } } } }YOUR_MCP_KEY是你在 FastGPT 工作台创建 MCP 服务时生成的 keyYOUR_REMOTE_TOKEN是远端服务要求的凭证。这两个值都属于敏感信息别提交到公开仓库。4. 验证请求从连通性到工具调用配置写完先别急着接 Agent按下面顺序验证。4.1 验证主应用 MCP 端点Streamable HTTP 端点只接受 POST。用 curl 发一个tools/list请求curl -X POST https://your-domain.com/api/mcp/app/YOUR_MCP_KEY/mcp \ -H Content-Type: application/json \ -H Accept: application/json, text/event-stream \ -d { jsonrpc: 2.0, id: 1, method: tools/list, params: {} }正常返回里会有result.tools数组每个工具带name、description、inputSchema。如果返回 405说明你用了 GET换成 POST如果返回invalidResource检查 key 是否正确、MCP 服务是否已创建。4.2 验证工具调用拿到工具名后发tools/callcurl -X POST https://your-domain.com/api/mcp/app/YOUR_MCP_KEY/mcp \ -H Content-Type: application/json \ -H Accept: application/json, text/event-stream \ -d { jsonrpc: 2.0, id: 2, method: tools/call, params: { name: your_tool_name, arguments: { question: 帮我总结一下这段内容 } } }普通应用返回的是最终回答文本Workflow Tool 返回的是pluginOutput的 JSON 字符串。如果返回isError: true看content里的错误信息通常是入参 schema 不匹配。4.3 验证 SSE 通道SSE 需要先建立事件流再发消息。用 curl 分两步# 第一步建立 SSE 连接终端会持续输出事件 curl -N https://your-domain.com/mcp/YOUR_MCP_KEY/sse # 第二步另开终端用返回的 sessionId 发消息 curl -X POST https://your-domain.com/mcp/YOUR_MCP_KEY/messages?sessionIdYOUR_SESSION_ID \ -H Content-Type: application/json \ -d { jsonrpc: 2.0, id: 1, method: tools/list, params: {} }SSE 连接建立后服务端会先推一个endpoint事件里面带sessionId。这个 sessionId 是后续所有 POST 消息的凭证丢了就得重连。4.4 验证 FastGPT 作为 MCP Client反过来让 FastGPT 去接远端 MCP Server。在创建 MCP ToolSet 时FastGPT 会先调getTools解析远端工具列表curl -X POST https://your-domain.com/api/core/app/mcpTools/getTools \ -H Authorization: Bearer YOUR_FASTGPT_TOKEN \ -H Content-Type: application/json \ -d { url: https://remote.example.com/mcp, headerSecret: { Authorization: Bearer YOUR_REMOTE_TOKEN } }返回的工具列表会被保存成AppTypeEnum.mcpToolSet应用子工具 ID 形如mcp-${appId}/${toolName}。调试单个工具用runTool接口参数结构类似。5. 本篇常见错排查5.1 Streamable HTTP 返回 4xx 但没回退 SSEFastGPT 的回退逻辑只在 Streamable HTTP 返回 4xx 时触发。如果你看到连接直接失败先确认错误码网络错误或 5xx 不会回退这是有意设计避免掩盖真实故障。检查远端服务是否真的支持 Streamable HTTP或者手动把客户端配置改成 SSE 地址。5.2 SSE 连上了但发消息没响应最常见的原因是 sessionId 没带对。SSE 的 POST 端点必须带?sessionIdxxx这个值来自 SSE 连接建立时服务端推送的endpoint事件。另一个原因是SSE_MCP_SERVER_PROXY_ENDPOINT配错前端拼出来的地址外部访问不到。5.3 工具列表为空先确认 MCP 服务绑定的应用类型。FastGPT 只允许simple、workflow、workflowTool三类应用发布成 MCP ToolmcpToolSet和httpToolSet本身是工具集合不支持再嵌套发布。如果绑定的是工具集列表自然为空。5.4 调用报 SSRF 相关错误FastGPT 对 MCP URL 做了内网地址校验初始 URL 和每一跳重定向都会检查。如果你填的是内网地址或者远端服务重定向到了内网都会被拦截。这是安全设计不要试图绕过。跨 host 或 protocol 重定向时Authorization、Cookie这类敏感 header 会被移除如果远端服务依赖这些 header需要改成同域重定向。5.5 远端 schema 解析失败MCP Client 在解析远端inputSchema时会做$RefParser.dereference但禁用了外部file和http引用。如果远端 schema 里用了外部$ref解析会失败并回退到原始 schema。建议远端服务把 schema 写成自包含的别依赖外部引用。5.6 权限变动导致集成中断MCP key 是发布凭证创建或更新时校验权限运行时按快照提供工具不再因为创建人权限变化而隐藏工具。如果你发现集成突然不可用先检查 MCP key 是否被删除或更新而不是去调创建人权限。6. 继续往下走配置到调用跑通之后下一步可以按需分流。如果你在排查接入问题重点看 API Keys 和接入文档https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 和 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。如果你要验证模型在工具调用场景下的表现去模型对话页实测https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 。如果你在搭长期编码或 Agent 工作流Coding Plan 的额度模型更合适https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 。Claude Code 相关的 Anthropic 兼容接入可以参考https://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentclaude_codeutm_campaignrewrite 。我自己的习惯是先把 Streamable HTTP 端点用 curl 跑通tools/list和tools/call确认工具能正常返回再去配客户端。这样出问题时能快速定位是服务端还是客户端的问题。SSE 通道留到最后再验因为它依赖 session 状态排查链路更长。