ApiPost(PostMan、ApiFox)测试MCP(Streamable-HTTP)完整指南

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

1. 什么是 Streamable HTTP？ #

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

1.1 核心特点 #

1.2 工作流程 #

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

2. Streamable HTTP vs REST API 对比 #

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

2.1 协议层面对比 #

2.2 请求方式对比 #

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"
}

2.3 响应格式对比 #

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
  }
}

2.4 功能端点对比 #

2.5 适用场景 #

2.6 选择建议 #

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

3. 前置准备 #

3.1 启动服务 #

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

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

3.2 请求流程概览 #

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

现在PostMan、ApiFox都已经支持直接对MCP进行调试了，但是ApiPost还不支持。所以下面将有两种方法对其进行测试，一种是支持MCP模式的，一种是不支持的

4. 不支持直接MCP测试的情况（ApiPost） #

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

4.1.1 请求配置 #

4.1.2 请求头 (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}

4.1.3 请求体 (Body) #

选择 raw → JSON 格式：

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

4.1.4 响应说明 #

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

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

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

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

4.1.5 获取 Session ID #

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

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

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

4.1.6 ApiPost示例 #

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

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

4.2.1 请求头 (Headers) #

4.2.2 请求体 (Body) #

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

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

4.2.3 ApiPost示例 #

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

4.3.1 请求头 (Headers) #

4.3.2 请求体 (Body) #

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

4.3.3 预期响应 #

返回 4 个可用工具：

4.3.4 ApiPost示例 #

4.4 第四步：调用工具 #

4.4.1 获取数据库结构 (get_schema) #

4.4.1.1 请求头 (Headers) #

4.4.1.2 请求体 (Body) #

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

4.4.1.3 ApiPost示例 #

4.4.2 执行 SQL 查询 (execute_query) #

4.4.2.1 请求头 (Headers) #

4.4.2.2 请求体 (Body) #

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

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

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

4.4.2.4 ApiPost示例 #

4.4.3 获取表详细信息 (get_table_info) #

4.4.3.1 请求体 (Body) #

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

4.4.3.2 ApiPost示例 #

4.4.4 清除缓存 (clear_cache) #

4.4.4.1 请求体 (Body) #

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

4.4.4.2 ApiPost示例 #

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

4.5.1 请求配置 #

4.5.2 请求头 (Headers) #

4.5.3 预期响应 #

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

4.5.4 ApiPost示例 #

4.6 支持的数据库类型 #

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

4.7 常见问题 #

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: message
data: {实际的JSON数据}

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

Q4: SQLite 数据库如何配置？ #

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

5. 支持直接MCP测试的情况（PostMan、ApiFox） #

5.1 新建一个 MCP Client #

5.2 填写 URL 和 Token #

• URL 默认的话就是 http://localhost:3000/mcp
• Auth Type 选 Bearer Token，填写你的 token

5.3 在 Header 填写数据库信息 #

我是连接本地的 MongoDB，配置 X-DB-Type、X-DB-Host、X-DB-Port 即可

5.4 点击连接，选择工具，即可调试 #

这样就不用关注那些网络协议的细节了，直接测试 MCP 工具本身。