易源合一的两条集成路径：MCP 直连与 OpenAPI 导入 Postman

# 易源合一的两条集成路径：MCP 直连与 OpenAPI 导入 Postman > 集成方式：MCP 服务 / OpenAPI 3.0 | 计费：5.5 厘/次，失败不扣费 | 最后实测核对：2026-09-15 ## 核心要点 - 易源合一提供两种不写业务代码就能调起来的方式：MCP 服务（配到 AI 客户端里）和 OpenAPI 文档（导入 Postman / Swagger UI）。 - MCP 实测可用，握手分三步。**少发 `notifications/initialized` 直接调 `tools/list`，会拿到 `-32601 Method not found`**。 - MCP 返回的三个工具名是**中文**（`智能对话`、`意图分析`、`智能对话(流式)`），不是英文的接口路径。 ## MCP 服务怎么配 MCP 的地址按接口维度提供，一个地址覆盖本接口全部接入点： ```json { "mcpServers": { "showapi-mcp-3054": { "url": "http://www.showapi.com.cn/mcp/3054/{your_appKey}" } } } ``` 把 `{your_appKey}` 换成真实 AppKey，粘进 Cherry Studio、ChatBox 等支持 MCP 的客户端即可。 配完能做什么？客户端里会多出三个工具，分别是智能对话、意图分析、智能对话(流式)。对用户来说，可以直接在对话里问「帮我查快递 7788990011223」，由客户端决定调哪个工具。 ## 手动验证：三步握手 如果你配完没反应，用 curl 手工走一遍最快定位问题。2026-09-15 的完整实测过程如下。 **第一步，initialize。** ```bash curl -s -D headers.txt -X POST "http://www.showapi.com.cn/mcp/3054/YOUR_APPKEY" \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"probe","version":"1.0"}}}' ``` 返回： ```json { "jsonrpc": "2.0", "result": { "protocolVersion": "2024-11-05", "instructions": "Hello, MCP!", "serverInfo": { "name": "lua-resty-mcp", "version": "2.0" }, "capabilities": { "prompts": { "listChanged": true }, "tools": { "listChanged": true }, "completions": {}, "resources": { "subscribe": true, "listChanged": true }, "logging": {} } }, "id": 1 } ``` **响应头里有一个必须拿到的值**： ``` Mcp-Session-Id: aqiqZQ9jy68CAJPX ``` 后续所有请求都要带上它。不带会直接收到 openresty 的 `400 Bad Request`，和 JSON-RPC 的错误格式都不一样。 **第二步，发 initialized 通知。** ```bash curl -s -X POST "http://www.showapi.com.cn/mcp/3054/YOUR_APPKEY" \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -H "Mcp-Session-Id: 上一步拿到的值" \ -d '{"jsonrpc":"2.0","method":"notifications/initialized"}' ``` 返回 HTTP `202`，没有响应体。这一步很容易被漏掉，但漏了就调不通。 **第三步，列出工具。** ```bash curl -s -X POST "http://www.showapi.com.cn/mcp/3054/YOUR_APPKEY" \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -H "Mcp-Session-Id: 上一步拿到的值" \ -d '{"jsonrpc":"2.0","id":3,"method":"tools/list","params":{}}' ``` 返回（SSE 格式，`data:` 后面是 JSON）： ```json { "jsonrpc": "2.0", "id": 3, "result": { "tools": [ { "name": "智能对话(流式)", "description": "流式调用是一种处理连续数据流的技术……", "inputSchema": { "type": "object", "properties": { "text": { "type": "string", "description": "意图内容" }, "args_list": { "type": "array", "description": "相关内容的url或者base64，例如图片的base64" }, "content-type": { "type": "string", "description": "" } } } }, { "name": "意图分析", "description": "借助人工智能技术，对语句中的内容进行分析，以识别文本中的意图。", "inputSchema": { "type": "object", "properties": { "text": { "type": "string", "description": "意图参数" }, "content-type": { "type": "string", "description": "" } } } }, { "name": "智能对话", "description": "智能对话可识别对话中的命令或意图……", "inputSchema": { "type": "object", "properties": { "text": { "type": "string", "description": "意图内容" }, "args_list": { "type": "array", "description": "相关内容的url或者base64，例如图片的base64" }, "content-type": { "type": "string", "description": "" } } } } ] } } ``` 三个工具就是三个接入点。名称是中文，和页面上的接入点名一致。`content-type` 在 OpenAPI 里是 Header 参数，这里被展开到了 `inputSchema.properties` 里。 ## 调用工具拿真实返回 ```bash curl -s -X POST "http://www.showapi.com.cn/mcp/3054/YOUR_APPKEY" \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -H "Mcp-Session-Id: 上一步拿到的值" \ -d '{"jsonrpc":"2.0","id":7,"method":"tools/call","params":{"name":"意图分析","arguments":{"text":"帮我查快递 7788990011223"}}}' ``` 实测返回的 `content[0].text` 里是两段拼起来的内容： ``` { "showapi_res_error": "", "showapi_res_code": 0, "showapi_fee_num": 1, "showapi_res_body": {"ret_msg":"调用成功","ret_code":0, "args":{"express_nu":"7788990011223"},"intent":"query_express", "confidence":98,"name":"快递"} } - 以下是返回参数说明 - 参数名称:ret_code, 参数类型: Number, 参数描述: 0为成功，其余为失败, 参数示例: 0 - 参数名称:confidence, 参数类型: Number, 参数描述: 置信度, 参数示例: 0.99572587013245 - 参数名称:intent, 参数类型: String, 参数描述: 意图标识, 参数示例: weather ``` 注意最后那段参数说明里的 **`confidence` 示例值是 `0.99572587013245`，而同一份返回里的真实值是 `98`**。这段说明是文档里的静态文案，会比你手上的实际数据旧。别拿示例值去写阈值判断，以实际返回为准。 ## 排错对照 | 现象 | 原因 | 处理 | |------|------|------| | `HTTP 400 Bad Request`（openresty 的 HTML 页） | 请求没带 `Mcp-Session-Id` | 用 initialize 响应头里的值补上 | | `{"error":{"code":-32601,"message":"Method not found"}}` | 还没发 `notifications/initialized` | 补发这条通知（返回 202）再调 `tools/list` | | `prompts/list` 或 `resources/list` 返回空数组 | 服务端没定义 prompt 和 resource | 正常现象，实测两个接口都返回 `[]` | | 工具名找不到 | 工具名是中文 | 用 `智能对话`、`意图分析`、`智能对话(流式)`，不要用 `3054-1` 这类路径名 | 服务端信息实测为 `lua-resty-mcp 2.0`，声明的协议版本是 `2024-11-05`，能力集包含 prompts、tools、completions、resources、logging。 ## OpenAPI 文档怎么用 文档地址： ``` https://www.showapi.com/openapi/market/3054.yaml https://www.showapi.com/openapi/market/3054.json ``` 规格是 OpenAPI 3.0.3，`servers` 只有一条 `https://route.showapi.com`。三个 path 分别是 `/3054-1`、`/3054-2`、`/3054-3`。 实测从 YAML 里读出来的几个关键点： - **三个 path 都只声明了 `post`。** 3054-2 的页面文档标注请求方式为 POST/GET，但 OpenAPI 里只有 `post` 一个方法定义。以文档页面为准时用 GET 也能通，但工具生成请求时只会给你 POST。 - **请求体是 `application/x-www-form-urlencoded`，`required` 只有 `text`。** `args_list` 是数组类型，范围标注 0~10000000。 - **鉴权定义在 query。** `securitySchemes.AppKeyAuth` 类型是 `apiKey`、位置 `in: query`、参数名 `appKey`。 - **每个 path 带扩展字段**，`x-pointCode` 是接入点序号，`x-mode` 为 `mapping`，`x-read-timeout` 分别是 60（3054-1）、50（3054-2）、60（3054-3）秒。 - **`externalDocs` 指向 `https://www.showapi.com/apiGateway/view/3054?tab=book`**，也就是页面上的帮助手册标签。 - 文件头部记录生成时间 `generated-at: 2026-09-05T19:43:09.977Z`。文档更新后这个时间会变，可以靠它判断手上的副本是不是新的。 ### 导入 Postman 或 Swagger UI **Postman：** 打开 Postman，`Import` → 选择 `File` 或直接粘贴 YAML 地址 → 导入后会自动生成三个请求模板，`appKey` 作为 query 参数出现在 URL 里，把占位值换成真实 AppKey 就能发。 **Swagger UI / Swagger Editor：** 把 YAML 内容贴进 Swagger Editor，右侧会渲染出三个可交互的接口文档，`Authorize` 里填 AppKey 之后可以直接在页面上试请求。 导入之后有几处要手工确认：`args_list` 在 Swagger UI 里可能被渲染成需要手填的 JSON 数组，中文 `text` 参数在部分客户端里要确认编码是 UTF-8。这两点踩了就会拿到一个和预期完全不同的返回。 ## FAQ **Q1：MCP 的三个工具名为什么是中文？** 服务端就是这样注册的。实测 `tools/list` 返回的 `name` 字段分别是 `智能对话(流式)`、`意图分析`、`智能对话`，与页面上的接入点名称一致。用英文或接口编号当工具名会报找不到工具。 **Q2：配好 MCP 但客户端不响应，先查什么？** 先确认 AppKey 是否放进了 URL，再确认客户端有没有发 `notifications/initialized`。服务端在没收到这条通知时会对 `tools/list` 返回 `-32601 Method not found`，表现和「工具不存在」一样，容易误判。 **Q3：MCP 调用会消耗额度吗？** 会。实测 `tools/call` 调的仍然是 3054 的接入点，返回里带 `showapi_fee_num: 1`，与直接调 HTTP 接口计费一致。 **Q4：OpenAPI 里为什么只有 POST？** 实测 YAML 里三个 path 都只定义了 `post`。3054-2 的页面文档另外标注了支持 GET，但这份机器可读的规格没有覆盖它。做自动化测试生成时按 POST 处理。 **Q5：MCP 服务有没有提供 prompt 或 resource？** 没有。实测 `prompts/list` 和 `resources/list` 都返回空数组，只有 tools 是可用的能力。服务端的能力声明里保留了 prompts 和 resources 的结构，但当前没有内容。 ## 下一步阅读 - [易源合一快速接入：用 curl 把「昆明今天天气」变成结构化数据](https://www.showapi.com/guides/united-api-quickstart-3054) - [易源合一实测能识别哪些意图：8 类 intent 编码逐一验证](https://www.showapi.com/guides/united-api-intent-list-3054) - [易源合一在对话式应用里的位置：意图层与执行层的切分方案](https://www.showapi.com/guides/united-api-dialog-architecture-3054) - **本系列共 12 篇**：查看[易源合一指南总目录](https://www.showapi.com/guides/united-api-guides-3054)