【教程】使用ApiPost/Postman 测试 unversal-db-mcp Streamable HTTP 完整指南

之前开源了universal-db-mcp万能数据库连接器，支持了stdio、SSE、Streamable、REST等传输方式。REST方式都比较熟，Streamable在使用ApiPost/Postman进行测试的时候跟REST有一些差异。加上最近看到有佬友在使用universal-db-mcp的时候，使用Postman对Streamable进行测试有些疑问，遂记录一下。
本文介绍如何使用 ApiPost 测试 Universal DB MCP 的 Streamable HTTP 传输方式，当然只要是Streamable HTTP 传输方式的MCP都可以按照下文逻辑进行测试。

什么是 Streamable HTTP？

Streamable HTTP 是 MCP (Model Context Protocol) 2025 规范中引入的新传输方式，专为 AI 与外部工具/服务的交互设计。它基于 HTTP 协议，但采用了 JSON-RPC 2.0 消息格式和 SSE (Server-Sent Events) 流式响应机制。

核心特点

工作流程

┌─────────────┐                      ┌─────────────┐
│   客户端     │                      │   服务器     │
└──────┬──────┘                      └──────┬──────┘
       │                                    │
       │  1. initialize (建立会话)           │
       │  ─────────────────────────────────>│
       │                                    │
       │  2. 返回 session-id + 能力声明      │
       │  <─────────────────────────────────│
       │                                    │
       │  3. tools/list (获取工具列表)       │
       │  ─────────────────────────────────>│
       │                                    │
       │  4. 返回可用工具                    │
       │  <─────────────────────────────────│
       │                                    │
       │  5. tools/call (调用工具)           │
       │  ─────────────────────────────────>│
       │                                    │
       │  6. SSE 流式返回结果                │
       │  <═════════════════════════════════│
       │                                    │

Streamable HTTP vs REST API 对比

Universal DB MCP 同时支持 Streamable HTTP 和 REST API 两种方式访问，以下是它们的详细对比：

协议层面对比

请求方式对比

Streamable HTTP 请求示例：

POST /mcp
Content-Type: application/json
Accept: application/json, text/event-stream
mcp-session-id: xxx

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "execute_query",
    "arguments": {"query": "SELECT * FROM users"}
  }
}

REST API 请求示例：

POST /api/query
Content-Type: application/json
X-Session-ID: xxx

{
  "query": "SELECT * FROM users"
}

响应格式对比

Streamable HTTP 响应（SSE 格式）：

event: message
data: {"jsonrpc":"2.0","id":1,"result":{"content":[{"type":"text","text":"{...}"}]}}

REST API 响应（普通 JSON）：

{"success":true,"data":{"rows":[...],"executionTime":15}}

功能端点对比

适用场景

选择建议

• 选择 Streamable HTTP：当你需要与 AI 平台（如 Claude Desktop、Dify、Coze）集成，或需要遵循 MCP 标准协议时
• 选择 REST API：当你只需要简单的数据库查询功能，或在传统 Web 应用中集成时

前置准备

启动服务

# 启动HTTP模式服务
MODE=http HTTP_PORT=3000 npx universal-db-mcp

或者直接部署在服务器上即可

请求流程概览

1. POST /mcp (initialize)     → 获取 mcp-session-id
         ↓
2. POST /mcp (initialized)    → 通知服务器初始化完成（可选）
         ↓
3. POST /mcp (tools/list)     → 获取可用工具列表
         ↓
4. POST /mcp (tools/call)     → 调用具体工具
         ↓
5. DELETE /mcp                → 关闭会话（可选）

第一步：初始化会话 (Initialize)

请求配置

请求头 (Headers)

重要：Accept 头必须同时包含 application/json 和 text/event-stream，否则会返回错误：

{"jsonrpc":"2.0","error":{"code":-32000,"message":"Not Acceptable: Client must accept both application/json and text/event-stream"},"id":null}

请求体 (Body)

选择 raw → JSON 格式：

{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2026-11-05","capabilities":{},"clientInfo":{"name":"apipost-test","version":"1.0.0"}}}

响应说明

响应采用 SSE (Server-Sent Events) 格式：

实际 JSON 数据在 data: 后面，解析后为：

{"result":{"protocolVersion":"2026-11-05","capabilities":{"tools":{}},"serverInfo":{"name":"universal-db-mcp","version":"1.0.0"}},"jsonrpc":"2.0","id":1}

获取 Session ID

重要：查看 ApiPost 的响应头 (Response Headers)，找到 mcp-session-id 字段：

mcp-session-id: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

复制此值，后续所有请求都需要在请求头中带上它。

ApiPost示例

第二步：发送 initialized 通知（可选）

此步骤用于通知服务器客户端已完成初始化，属于 MCP 协议的握手确认机制。大多数情况下可以跳过。

请求头 (Headers)

请求体 (Body)

{"jsonrpc":"2.0","method":"notifications/initialized"}

注意：这是一个通知（notification），没有 id 字段，服务器不会返回响应。

ApiPost示例

第三步：获取可用工具列表

请求头 (Headers)

请求体 (Body)

{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}

预期响应

返回 4 个可用工具：

ApiPost示例

第四步：调用工具

4.1 获取数据库结构 (get_schema)

请求头 (Headers)

请求体 (Body)

{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"get_schema","arguments":{"forceRefresh":false}}}

ApiPost示例

4.2 执行 SQL 查询 (execute_query)

请求头 (Headers)

请求体 (Body)

{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"execute_query","arguments":{"query":"SELECT * FROM your_table LIMIT 10"}}}

带参数的查询（防 SQL 注入）

{"jsonrpc":"2.0","id":5,"method":"tools/call","params":{"name":"execute_query","arguments":{"query":"SELECT * FROM users WHERE id = ?","params":["123"]}}}

ApiPost示例

4.3 获取表详细信息 (get_table_info)

请求体 (Body)

{"jsonrpc":"2.0","id":6,"method":"tools/call","params":{"name":"get_table_info","arguments":{"tableName":"users","forceRefresh":false}}}

ApiPost示例

4.4 清除缓存 (clear_cache)

请求体 (Body)

{"jsonrpc":"2.0","id":7,"method":"tools/call","params":{"name":"clear_cache","arguments":{}}}

ApiPost示例

第五步：关闭会话（可选）

请求配置

请求头 (Headers)

预期响应

{"success":true,"message":"Session closed"}

ApiPost示例

支持的数据库类型

在 X-DB-Type 头中可以使用以下值：

常见问题

Q1: 返回 “Not Acceptable” 错误

原因：缺少 Accept 头或值不正确

解决：确保请求头包含：

Accept: application/json, text/event-stream

Q2: 返回 “Bad Request: No valid session ID provided”

原因：非初始化请求缺少 mcp-session-id 头

解决：从第一步的响应头中获取 mcp-session-id，并在后续请求中携带

Q3: 响应是 SSE 格式，如何解析？

说明：Streamable HTTP 使用 SSE 格式返回数据

格式：

event: messagedata: {实际的JSON数据}

提取 data: 后面的内容即为实际响应 JSON。

Q4: SQLite 数据库如何配置？

SQLite 使用文件路径而非网络连接：

原文【开源自荐5】MCP 数据库万能连接器：用自然语言查询和分析数据