Postman 集合一键转为 MCP 工具：实操路径

一个 Postman 集合可以作为一个 MCP 服务器出人意料的起点。

很多团队在拥有完善的 OpenAPI 文档之前，就已经有了 Postman 集合。集合中已经包含了可用的请求、路径、查询参数、请求头、请求体、响应示例以及认证说明。这些已经足够开始构思 MCP 工具了。

但有一个问题。

Postman 请求终究是开发者的产物。MCP 工具则是面向 AI 的能力。将前者转换为后者需要审查、命名、schema 整理、认证决策、测试以及生产准备。

这篇文章将带你走过从 Postman 请求到 MCP 工具的实用路径。

先清理集合

在任何地方导入 Postman 集合之前，先把它清理干净。

一个真实的集合往往包含的不仅仅是可以直接用于生产的 API 请求：

• 内部调试端点
• 仅用于测试的请求体
• 管理或破坏性操作

不要因为一个集合在 Postman 里能跑，就认为它是安全的。

在将其用于 MCP 之前，检查以下事项：

• 这是最新的集合吗？
• 它指向的是目标 API 环境吗？
• 请求名称清晰吗？
• 变量可理解吗？
• 仅用于测试的请求删除了吗？
• 旧端点删除了或标记为遗留了吗？
• 破坏性请求分离出来供审查了吗？

这个清理步骤很重要，因为 MCP 工具列表会从集合中继承大量语义。如果集合是乱的，MCP 服务器大概率也会是乱的。

理解 Postman 到 MCP 的映射关系

从高层来看，每个有用的 Postman 请求都可以成为一个候选的 MCP 工具。

GET {{baseUrl}}/v1/customers/{{customer_id}}/tickets?status=open
Authorization: Bearer {{token}}

可以变成这样的工具：

{
  "name": "list_open_customer_tickets",
  "description": "List open support tickets for one customer.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "customer_id": {
        "type": "string",
        "description": "The customer ID to search tickets for."
      },
      "limit": {
        "type": "integer",
        "description": "Maximum number of tickets to return."
      }
    },
    "required": ["customer_id"]
  }
}

映射关系包含的不仅仅是方法和 URL，还有预期错误行为。

Postman 给你的是原始请求的形状。MCP 需要的是清晰的工具契约。

路径变量映射为必填输入

路径变量通常会成为必填的工具输入。

GET /v1/customers/{{customer_id}}

{
  "customer_id": {
    "type": "string",
    "description": "The unique ID of the customer to retrieve."
  }
}

如果端点没有 customer_id 就无法运行，MCP schema 应该将其标记为 required。

{
  "customer_id": {
    "type": "string"
  }
}

{
  "customer_id": {
    "type": "string",
    "description": "The customer ID from your application."
  }
}

路径变量值得清晰的描述，因为 AI 客户端上下文中可能有多个 ID。customer_id、workspace_id、ticket_id 和 invoice_id 不应该被混为一个通用的 id。

查询参数映射为可选过滤器

查询参数通常会成为可选的工具输入。

GET /v1/tickets?customer_id={{customer_id}}&status={{status}}&limit={{limit}}

{
  "type": "object",
  "properties": {
    "customer_id": {
      "type": "string",
      "description": "Return tickets for this customer."
    },
    "status": {
      "type": "string",
      "enum": ["open", "pending", "resolved"],
      "description": "Optional ticket status filter."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 50,
      "description": "Maximum number of tickets to return."
    }
  },
  "required": ["customer_id"]
}

好的查询参数映射应该回答以下问题：

• 哪些过滤器是安全使用所必需的？
• 哪些过滤器是可选的？
• 枚举值有文档吗？
• 默认限制安全吗？
• 请求是否会返回过多数据？

对于 AI 客户端来说，无边界的列表端点是有风险的。如果你的 API 支持 limit、cursor、page 或 offset，要让这些字段清晰可见。

谨慎处理请求体

Postman 的请求体通常包含示例载荷。

但这并不意味着 MCP 工具就应该接受同样的原始 JSON 对象。

POST /v1/tickets
Content-Type: application/json

{
  "customer_id": "{{customer_id}}",
  "subject": "{{subject}}",
  "priority": "{{priority}}",
  "message": "{{message}}"
}

{
  "name": "create_support_ticket",
  "description": "Create a support ticket for a customer.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "customer_id": {
        "type": "string",
        "description": "The customer the ticket belongs to."
      },
      "subject": {
        "type": "string",
        "description": "Short ticket subject."
      },
      "priority": {
        "type": "string",
        "enum": ["low", "normal", "high"],
        "description": "Ticket priority."
      },
      "message": {
        "type": "string",
        "description": "Initial support message."
      }
    },
    "required": ["customer_id", "subject", "message"]
  }
}

避免接受一个巨大的载荷对象的 schema，除非 API 真的需要任意 JSON。具体的 schema 能给 AI 客户端更好的边界，也给团队更好的验证测试。

对于写操作，描述中还应该说明会产生什么变化。

不要把认证请求变成普通工具

很多 Postman 集合包含这类请求：

POST /login
POST /oauth/token
POST /refresh-token
GET /api-keys

这些通常不是好的 MCP 工具。

认证应该是运行时连接和请求流程的一部分。模型不应该需要在使用产品能力之前先调用 login。

对于需要 API 支持的 MCP 工具，更安全的模式是：

• 用户或客户端通过客户端流程提供凭证
• MCP 服务器接收工具调用
• MCP 服务器将凭证传递给原始 API
• 原始 API 强制执行身份验证、作用域、租户访问和记录权限

在审查 Postman 集合时，从导出文件中删除个人令牌和密钥。将 {{token}} 或 {{apiKey}} 这样的变量保留为占位符，而不是真实凭证。

在 Postman 中用你的个人令牌可以工作的认证，用客户凭证在 MCP 中可能会失败。在生产之前要测试这一点。

选择有用的操作，而非每个请求

一个 Postman 集合可以包含很多对开发者有用但对 AI 代理不友好的请求。

从一个小型工作流开始。

"让 AI 支持助手查询客户上下文并创建工单备注。"

可能有用的请求：

GET /customers/{customer_id}
GET /tickets?customer_id={customer_id}
GET /tickets/{ticket_id}
POST /tickets/{ticket_id}/notes

第一次发布时应排除的请求：

DELETE /customers/{customer_id}
POST /admin/reindex
PATCH /users/{user_id}/role
GET /internal/debug
POST /oauth/token

这是核心的选择规则：

一个请求只有在其映射到一个清晰的、有用的、被授权的 AI 能力时，才能成为 MCP 工具。

工具列表是一份白名单。要把它当作产品和安全决策来对待。

为 AI 客户端重命名工具

Postman 请求名往往是为了人类浏览集合而写的。

Get Customer
Create
Update v2
List
Old invoice route
Test request

这些名字作为 MCP 工具名太弱了。

应该使用稳定的、具体的、以动作为导向的名称：

get_customer
list_customer_tickets
create_ticket_note
get_customer_subscription
list_unpaid_invoices

工具描述应该补充缺失的上下文：

List unpaid invoices for one customer. Use this when the user asks about outstanding billing or payment status.

AI 客户端应该能在不阅读你的 Postman 文件夹结构的情况下选择工具。

如果两个工具听起来一样，在添加更多工具之前先修复名称。

测试导入的工具

导入并选择操作之后，在连接真实客户端工作流之前先测试工具集。

需要检查：

• 缺少必填路径变量
• 意外的上游错误

对于写工具，还要测试：

• 无效的状态转换
• 权限不足
• 带额外字段的载荷
• 缺少必填业务字段的载荷
• 在安全测试环境中的行为

还要确认：

• 只有预期的工具可见吗？
• 工具名称唯一吗？
• 描述具体吗？
• 必填输入显而易见吗？
• 已删除或敏感的请求不存在了吗？
• 资源和提示只在预期情况下可见吗？

这就是 Postman 衍生工具要么变得可靠、要么停留在"在我机器上跑过一次"的阶段。

为生产准备托管服务器

托管的 MCP 服务器需要的不仅仅是成功导入。

生产之前确认：

• 托管端点稳定
• 服务器使用预期的传输方式
• 认证已用真实的运行时凭证路径测试过
• 上游 API 环境正确
• 日志显示足够的调试细节
• 分析能展示请求量、错误率、延迟和能力使用情况
• 选定的工具已版本化
• 坏变更后可以回滚或恢复
• 原始 API 仍然强制执行租户、角色、记录和操作权限

通过 0mcp，团队可以导入 Postman 集合、审查检测到的请求、选择有用的 API 操作、完善工具、在 Playground 中测试，并通过 Streamable HTTP 托管 MCP 服务器。现有 API 认证继续通过 API 密钥、Bearer 令牌或 OAuth 直通使用，客户凭证在请求期间传递而不是由 0mcp 存储。

0mcp 目前支持托管的 Streamable HTTP 服务器，而非本地 stdio 服务器。原始 API 仍然负责业务逻辑、授权、分页、速率限制、租户边界和验证。

有关此工作流的网站版本，请参阅 Postman to MCP。