可流式 HTTP (Streamable HTTP) 连接规范
streamable_http 连接类型使 Griptape Nodes 能够通过标准 HTTP/HTTPS 协议与远程 MCP 服务器建立支持客户端与服务端双向流式传输 (Bidirectional Streaming) 的实时全双工通信。
适用场景 (When to Use Streamable HTTP)
- 真正的双向数据流：客户端与服务端双方均需要在会话中持续流式收发数据；
- 高交互性业务应用：实时智能体对话、协同图纸编辑、动态白板与跨团队画布协作；
- 企业现有 HTTP 基础设施：利用现有的 API 网关、WAF 防火墙与负载均衡器开展流量路由；
- 自定制流控机制：需要比传统 SSE 更加细粒度的连接生命周期与会话状态管控；
- 持久化会话纳管 (Session Management)：要求在跨请求网络抖动时维系长久 Session 状态。
典型 Streamable HTTP MCP 服务
- Exa — 先进的高级语义网页检索与深度科研分析中枢。
典型配置范例 (Example Configurations)
实时对话类 MCP 服务配置
{
"name": "chat_app",
"transport": "streamable_http",
"url": "https://api.chat-service.com/mcp/stream",
"headers": {
"Authorization": "Bearer chat-token"
},
"timeout": 60,
"sse_read_timeout": 120,
"terminate_on_close": false,
"description": "面向实时通信与动态协作的双向流服务"
}
字段配置规范参考 (Configuration)
必填字段 (Required Fields)
| 字段名称 |
数据类型 |
物理含义与功能说明 |
典型配置范例 |
url |
字符串 |
暴露 MCP 流式服务能力的 HTTP/HTTPS 终结点地址 |
"https://api.example.com/mcp/stream" |
可选高级字段 (Optional Fields)
| 字段名称 |
数据类型 |
物理含义与功能说明 |
默认值 |
headers |
键值字典 |
随请求携带的 HTTP 报头（如鉴权 Token、API Key 等） |
{} |
timeout |
浮点数 |
基础 HTTP 请求握手与传输超时时间（秒） |
30 |
sse_read_timeout |
浮点数 |
单次流式块读取的等待超时时间（秒） |
60 |
terminate_on_close |
布尔值 |
当连接断开时，是否在远端强制销毁当前会话上下文 |
true |
更多生产级配置范本
基础通用流式服务
{
"name": "streamable_api",
"transport": "streamable_http",
"url": "https://api.example.com/mcp/stream",
"description": "基于双向流式传输的通用客户端-服务端通信接口"
}
带自定义 API Key 与客户端指纹的安全连接
{
"name": "custom_streamable",
"transport": "streamable_http",
"url": "https://mcp.example.com/stream",
"headers": {
"X-API-Key": "your-api-key",
"X-Client-Version": "1.0.0",
"User-Agent": "GriptapeNodes/1.0"
},
"timeout": 90,
"sse_read_timeout": 300,
"terminate_on_close": false
}
Streamable HTTP 与传统 SSE 的技术架构对比
| 架构维度 |
可流式 HTTP (Streamable HTTP) |
传统 SSE (Server-Sent Events) |
| 传输流向 |
全双工双向流动 (客户端 $\leftrightarrow$ 服务端) |
严格单向 (仅服务端 $\rightarrow$ 客户端推送) |
| 底层协议 |
现代分块传输编码 (Chunked) / 双向 HTTP 流 |
标准化单向 MIME (text/event-stream) |
| 核心场景 |
实时问答交互、协同白板、动态输入打断 |
单向股票行情看板、日志监控大屏、通知推送 |
| 断线重连 |
由应用层协议框架深度管控 |
原生依靠浏览器协议层自动重试 |
| 会话持久化 |
支持与 terminate_on_close 深度协同 |
通常依赖 Cookie 或重连 Header |
身份认证配置范式 (Authentication)
1. Bearer Token 规范 (JWT 等)
{
"headers": {
"Authorization": "Bearer your-jwt-token"
}
}
2. 独立 API Key 与客户端标识
{
"headers": {
"X-API-Key": "your-api-key",
"X-Client-ID": "griptape-nodes"
}
}
3. 多租户复杂鉴权
{
"headers": {
"X-Custom-Auth": "your-custom-token",
"X-User-ID": "user123",
"X-Session-ID": "session456"
}
}
会话生命周期控制 (Session Management)
关闭即销毁 (terminate_on_close: true)
- 默认行为。当节点执行完毕关闭连接时，主动通知远端服务端立即清理该会话占用的内存与状态；
- 适用于幂等性工具调用与无状态交互场景。
跨调用持久化会话 (terminate_on_close: false)
- 连接关闭后，远端服务端继续保活当前 Session 状态；
- 极适合需要持续多轮追加上下文、长周期任务追踪或协同画布会话。
生产级部署与调优建议 (Best Practices)
- 全面启用 HTTPS/TLS 加密：生产环境中严禁在明文 HTTP 上暴露 MCP 工具链；
- 合理放宽超时配额：对于生成时间漫长的大模型推理或大数据分析任务，将
sse_read_timeout 适当调大（例如 180~300 秒）；
- 连接池复用：系统会自动复用存活的 TCP/HTTP 连接，降低频繁建立握手的握手延迟；
- 日志排查：遇到流式中断时，检查是否被上游 Nginx 或云防火墙的
proxy_buffering 缓冲阻断，应配置 proxy_buffering off 确保流式数据即刻穿透。
推荐延伸阅读