企业官网建设流程全解析

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_source=taotoken_aicg_blog_end&utm_content=model_chat&utm_campaign=rewrite ，确认模型侧没问题再往下配 MCP，能省掉不少排查时间。

2. 前置准备：TaoToken 凭证与 FastGPT 环境

在动 MCP 配置之前，先把两样东西备齐：一个能正常调用的模型凭证，一个跑起来的 FastGPT 实例。

模型凭证这块，TaoToken 提供 OpenAI 兼容的接口，FastGPT 里配置模型渠道时直接填就行。先到控制台创建 API Key：https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite ，然后在 API Keys 页面生成密钥：https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api_keys&utm_campaign=rewrite 。接口地址用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_source=taotoken_aicg_blog_end&utm_content=coding_plan&utm_campaign=rewrite 。

3. 可复制配置：config.toml 与 settings.json 骨架

下面给出两套骨架。config.toml用于 FastGPT 主应用和独立 MCP Server 的部署配置，settings.json用于 MCP 客户端侧的连接配置。

3.1 config.toml：FastGPT 主应用与 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_ENDPOINT不要填公网地址，容器间走内网更稳；SSE_MCP_SERVER_PROXY_ENDPOINT不要填内网地址，否则外部客户端访问不到。

3.2 settings.json：MCP 客户端连接配置

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 服务时生成的 key，YOUR_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/call：

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": 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?sessionId=YOUR_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 但没回退 SSE

FastGPT 的回退逻辑只在 Streamable HTTP 返回 4xx 时触发。如果你看到连接直接失败，先确认错误码：网络错误或 5xx 不会回退，这是有意设计，避免掩盖真实故障。检查远端服务是否真的支持 Streamable HTTP，或者手动把客户端配置改成 SSE 地址。

5.2 SSE 连上了但发消息没响应

最常见的原因是 sessionId 没带对。SSE 的 POST 端点必须带?sessionId=xxx，这个值来自 SSE 连接建立时服务端推送的endpoint事件。另一个原因是SSE_MCP_SERVER_PROXY_ENDPOINT配错，前端拼出来的地址外部访问不到。

5.3 工具列表为空

先确认 MCP 服务绑定的应用类型。FastGPT 只允许simple、workflow、workflowTool三类应用发布成 MCP Tool，mcpToolSet和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_source=taotoken_aicg_blog_end&utm_content=api_keys&utm_campaign=rewrite 和 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite 。如果你要验证模型在工具调用场景下的表现，去模型对话页实测：https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_content=model_chat&utm_campaign=rewrite 。如果你在搭长期编码或 Agent 工作流，Coding Plan 的额度模型更合适：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding_plan&utm_campaign=rewrite 。

Claude Code 相关的 Anthropic 兼容接入，可以参考：https://taotoken.net/claude-code-anthropic?utm_source=taotoken_aicg_blog_end&utm_content=claude_code&utm_campaign=rewrite 。

我自己的习惯是：先把 Streamable HTTP 端点用 curl 跑通tools/list和tools/call，确认工具能正常返回，再去配客户端。这样出问题时能快速定位是服务端还是客户端的问题。SSE 通道留到最后再验，因为它依赖 session 状态，排查链路更长。