在 AI 客户端和 Postman 里接入银行卡归属地查询：MCP 服务与 OpenAPI 文档配置
银行卡归属地查询MCP服务OpenAPIPostmanSwagger UI # 在 AI 客户端和 Postman 里接入银行卡归属地查询：MCP 服务与 OpenAPI 文档配置
> 接口：银行卡归属地查询（apiCode=30）· 接入点：`30-7` · 集成方式：MCP 服务（接口级）、OpenAPI 3.0 文档（接口级） · 适用人群：AI 客户端用户、注重接口治理的团队 · 阅读时间：约 7 分钟
> 最后实测核对：2026-09-15
一句话结论：银行卡归属地查询提供接口级的 MCP 服务和 OpenAPI 3.0 文档，MCP 配置只需三行 JSON（`http://www.showapi.com.cn/mcp/30/{your_appKey}`），OpenAPI 文档可以从 `https://www.showapi.com/openapi/market/30.yaml` 下载后导入 Postman 或 Swagger UI，里面还带着页面上不展示的超时配置。
## MCP 服务怎么配
本接口的 MCP 服务是**接口级**的，覆盖 `30-7` 这个接入点。配置 JSON 如下：
```json
{
"mcpServers": {
"showapi-mcp-30": {
"url": "http://www.showapi.com.cn/mcp/30/{your_appKey}"
}
}
}
```
把 `{your_appKey}` 换成真实 AppKey 即可。这类配置用于 Cherry Studio、ChatBox 等支持 MCP 的客户端，配置完成后可以直接在 AI 对话里发起银行卡归属查询，不需要自己写 HTTP 代码。
AppKey 的管理入口在 [https://www.showapi.com/console#/myApp](https://www.showapi.com/console#/myApp)。
### 配置完成后怎么验证
在 AI 客户端里提一个具体问题，比如「查一下卡号 6228480402564890018 的开户行和归属地」。**重点看返回里有没有 `formatBankName`、`area`、`cardType` 这几个字段名**——有，说明 MCP 服务连通到了真实接口；如果 AI 直接凭常识编了一个答案，通常不会有这些字段名。
## OpenAPI 文档怎么拿
接口页提供三种获取方式：
| 方式 | 地址 |
|------|------|
| 在线查看 YAML | 接口页「OpenAPI 文档」区块 |
| 下载 YAML | `https://www.showapi.com/openapi/market/30.yaml` |
| 查看 JSON | 接口页「查看 JSON」按钮 |
文档是标准 OpenAPI 3.0 格式（`openapi: 3.0.3`），覆盖本接口全部接入点，可以导入 Postman 或 Swagger UI，也可以直接给 AI Agent 消费。
## 从 YAML 里能读到哪些页面上没有的信息
这是 OpenAPI 文档相比接口页更有用的地方。四类信息在接口页上看不到：
**超时配置。** 路径节点上带着：
```yaml
paths:
/30-7:
x-pointCode: 7
x-mode: mapping
x-read-timeout: 30
x-connect-timeout: 30
```
读超时与连接超时都是 30 秒。写代码时按这个值设置，比拍一个默认值靠谱。
**鉴权位置。** 在 `securitySchemes` 里：
```yaml
components:
securitySchemes:
AppKeyAuth:
type: apiKey
in: query
name: appKey
```
`in: query` 明确了 AppKey 放在查询参数里，不是请求头。
**必填参数的机器可读形式。** `required: [cardNum]` 写在请求体的 schema 里，比文档表格更容易被工具消费：
```yaml
requestBody:
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
cardNum:
type: string
description: 银行卡号
needBin:
type: string
description: 是否需要返回银行卡BIN码信息和银联luhn效验。1表示需要，0表示不需要，默认不会返回这些信息，返回这些信息将使得查询更加耗时。
required:
- cardNum
```
**统一返回包裹的定义。** `ShowapiResEnvelope` 把外层四个字段定义齐了：
```yaml
ShowapiResEnvelope:
type: object
properties:
showapi_res_code:
type: integer
description: API 返回的状态码
showapi_res_error:
type: string
description: API 返回的错误信息
showapi_res_id:
type: string
description: API 请求的唯一标识
showapi_fee_num:
type: integer
description: API 调用计费次数
```
`showapi_fee_num` 在 schema 里的说明是「API 调用计费次数」，可以直接作为调用量核对字段使用。
## 导入 Postman 的操作步骤
1. 浏览器打开 `https://www.showapi.com/openapi/market/30.yaml`，另存为 `30.yaml`。
2. 打开 Postman，选择 Import，把 `30.yaml` 拖进去。Postman 会识别出 OpenAPI 3.0 格式，自动生成一个 Collection，里面有一条 `POST /30-7` 请求。
3. 生成的请求模板里，`cardNum` 是必填参数，`needBin` 是可选项。
4. 在请求的 Query Params 里手工加一条 `appKey`，值为你的真实 AppKey。
5. 发送，检查返回体里的 `showapi_res_code` 是否为 `0`。
第 4 步需要手工加。原因是 OpenAPI 里的 `AppKeyAuth` 定义用的是 `apiKey in: query`，导入后 Postman 通常会生成一个名为 `appKey` 的空占位参数，但没有值，需要你填。
## 导入 Swagger UI 的操作步骤
1. 打开 Swagger Editor 或本地部署的 Swagger UI。
2. 在 Swagger Editor 里粘贴 `30.yaml` 内容，右侧会渲染出接口文档，`/30-7` 下的参数、返回结构都可以展开查看。
3. 用 Swagger UI 的 Try it out 功能时，同样需要手工填 `appKey`。
Swagger UI 更适合给团队做接口文档共享——`ShowapiResEnvelope` 与业务字段的 schema 都会渲染成结构化表格，省掉手工写文档的功夫。
## 一次调用的完整参数与预期
用 Postman 或 Swagger UI 发出请求后，下面是 2026-09-15 实测的返回形态，可以拿来对照：
```json
{
"showapi_res_error": "",
"showapi_res_id": "6aa8e433fb638c2f69478484",
"showapi_res_code": 0,
"showapi_fee_num": 1,
"showapi_res_body": {
"logo": "http://static1.showapi.com/app2/banklogo/abc.png",
"cardNum": "6228480402564890018",
"area": "江苏 - 苏州",
"cardType": "借记卡",
"bankName": "中国农业银行",
"formatBankName": "农业银行",
"isLuhn": "1",
"card_digits": "19",
"brand": "金穗通宝卡(银联卡)",
"simpleCode": "ABC",
"bin_digits": "6",
"url": "www.abchina.com",
"card_bin": "622848",
"tel": "95599",
"ret_code": 0
}
}
```
`showapi_res_code` 为 `0` 表示请求被受理，`ret_code` 为 `0` 表示查到结果。两层都要看，具体判定逻辑见[银行卡归属地查询排错：三种失败形态怎么区分](https://www.showapi.com/guides/bank-card-attribution-error-codes-30)。
## FAQ
**Q1：MCP 配置里的 URL 域名和接口地址不一样，是正常的吗？**
正常。MCP 服务的地址是 `http://www.showapi.com.cn/mcp/30/{your_appKey}`，走的是 MCP 服务入口；接口本身的调用地址是 `https://route.showapi.com/30-7`。两者是不同的接入通道。
**Q2：MCP 配置是接口级的还是接入点级的？**
接口级。本接口只有 `30-7` 一个接入点，这份 MCP 服务覆盖本接口全部接入点。
**Q3：OpenAPI 文档里的超时是多少？**
`x-read-timeout: 30`、`x-connect-timeout: 30`，单位是秒。这两个值在接口页上看不到，只在 OpenAPI 文档里。
**Q4：导入 Postman 后为什么请求发不通？**
最常见的原因是 Query Params 里的 `appKey` 没有填值。OpenAPI 定义的是 `apiKey in: query`，导入后不会自动带值。
**Q5：`showapi_fee_num` 是干什么的？**
OpenAPI 里对它的定义是「API 调用计费次数」。实测成功调用返回 `1`，失败调用返回 `0`，可以用来核对计费。
**Q6：除了 Postman 和 Swagger UI，这份 YAML 还能用在哪？**
标准 OpenAPI 3.0 文档可以给支持该格式的 API 网关、Mock 服务、代码生成器或 AI Agent 消费。文档是接口级的，`paths` 下就是这个接口的全部接入点。
## 下一步阅读
- [银行卡归属地查询：用 Python 跑通 30-7 接口的第一条请求](https://www.showapi.com/guides/bank-card-attribution-quickstart-30)——不用工具，直接写代码调通
- [银行卡归属地查询方案怎么选：自建 BIN 库、公开数据源、付费接口的适用条件](https://www.showapi.com/guides/bank-card-attribution-selection-30)——三条路线的能力对照
- [银行卡归属地查询枚举速查](https://www.showapi.com/guides/bank-card-attribution-enum-reference-30)——249 / 646 / 1929 三组枚举全量清单
- **本系列共 10 篇**：查看[银行卡归属地查询指南总目录](https://www.showapi.com/guides/bank-card-attribution-guides-30)
