DEV Community

Bhavy Shekhaliya
Bhavy Shekhaliya

Posted on

Postman Collection to MCP: From Requests to MCP Tools

#ai #programming #mcp #api

A Postman collection can be a surprisingly useful starting point for an MCP server.

Many teams have Postman collections before they have polished OpenAPI documentation. The collection already contains working requests, paths, query parameters, headers, bodies, example responses, and authentication notes. That is enough to begin thinking about MCP tools.

But there is a catch.

A Postman request is still a developer artifact. An MCP tool is an AI-facing capability. Converting one into the other takes review, naming, schema cleanup, authentication decisions, testing, and production preparation.

This article walks through the practical path from Postman requests to MCP tools.

Start by cleaning the collection

Before importing a Postman collection anywhere, clean it.

A real collection often contains more than production-ready API requests:

  • experiments
  • duplicate requests
  • old API versions
  • internal debug endpoints
  • local host URLs
  • temporary headers
  • personal API keys
  • copied Bearer tokens
  • test-only request bodies
  • admin or destructive operations

Do not treat the collection as safe because it works in Postman.

Before using it for MCP, check:

  • Is this the current collection?
  • Does it point to the intended API environment?
  • Are request names clear?
  • Are variables understandable?
  • Are secrets removed?
  • Are test-only requests removed?
  • Are old endpoints removed or marked as legacy?
  • Are destructive requests separated for review?

This cleanup step matters because the MCP tool list will inherit a lot of meaning from the collection. If the collection is messy, the MCP server will probably be messy too.

Understand what maps from Postman to MCP

At a high level, each useful Postman request can become a candidate MCP tool.

A request like this:

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

Can become a tool like:

{
  "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"]
  }
}
Enter fullscreen mode Exit fullscreen mode

The mapping includes more than method and URL.

You need to review:

  • request name
  • folder name
  • HTTP method
  • path variables
  • query parameters
  • headers
  • request body
  • authentication
  • example response
  • expected error behavior

Postman gives you the raw request shape. MCP needs a clear tool contract.

Map path variables into required inputs

Path variables usually become required tool inputs.

For example:

GET /v1/customers/{{customer_id}}
Enter fullscreen mode Exit fullscreen mode

Should map to:

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

If the endpoint cannot run without customer_id, the MCP schema should mark it as required.

Bad schema:

{
  "customer_id": {
    "type": "string"
  }
}
Enter fullscreen mode Exit fullscreen mode

Better schema:

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

Path variables deserve clear descriptions because the AI client may have several IDs in context. customer_id, workspace_id, ticket_id, and invoice_id should not be blurred into a generic id.

Map query parameters into optional filters

Query parameters often become optional tool inputs.

Example:

GET /v1/tickets?customer_id={{customer_id}}&status={{status}}&limit={{limit}}
Enter fullscreen mode Exit fullscreen mode

Candidate schema:

{
  "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"]
}
Enter fullscreen mode Exit fullscreen mode

Good query-parameter mapping should answer:

  • Which filters are required for safe use?
  • Which filters are optional?
  • Are enum values documented?
  • Are default limits safe?
  • Can the request return too much data?
  • Is pagination clear?

For AI clients, unbounded list endpoints are risky. If your API supports limit, cursor, page, or offset, make those fields clear.

Handle request bodies carefully

Postman bodies often contain example payloads.

That does not automatically mean the MCP tool should accept the same raw JSON blob.

A request like:

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

{
  "customer_id": "{{customer_id}}",
  "subject": "{{subject}}",
  "priority": "{{priority}}",
  "message": "{{message}}"
}
Enter fullscreen mode Exit fullscreen mode

Can become:

{
  "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"]
  }
}
Enter fullscreen mode Exit fullscreen mode

Avoid schemas that accept one giant payload object unless the API genuinely needs arbitrary JSON. A specific schema gives the AI client better boundaries and gives your team better validation tests.

For write operations, the description should also say what changes.

Do not turn auth requests into normal tools

Many Postman collections contain requests like:

POST /login
POST /oauth/token
POST /refresh-token
GET /api-keys
Enter fullscreen mode Exit fullscreen mode

Those are usually not good MCP tools.

Authentication should be part of the runtime connection and request flow. The model should not need to call login before using product capabilities.

For API-backed MCP tools, the safer pattern is:

  1. the user or client provides credentials through the client flow
  2. the MCP server receives a tool call
  3. the MCP server passes the credential to the original API
  4. the original API enforces identity, scopes, tenant access, and record permissions

When reviewing a Postman collection, remove personal tokens and secrets from the export. Keep variables like {{token}} or {{apiKey}} as placeholders, not real credentials.

Then test:

  • missing API key
  • invalid API key
  • expired Bearer token
  • revoked OAuth access
  • insufficient scope
  • wrong tenant

Authentication that works in Postman with your personal token may fail in MCP for a customer credential. Test that before production.

Select useful operations, not every request

A Postman collection can contain a lot of requests that are useful for developers and bad for AI agents.

Start with a small workflow.

For example:

"Let an AI support assistant look up customer context and create ticket notes."

Useful requests might be:

GET /customers/{customer_id}
GET /tickets?customer_id={customer_id}
GET /tickets/{ticket_id}
POST /tickets/{ticket_id}/notes
Enter fullscreen mode Exit fullscreen mode

Requests to exclude from the first release might be:

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

This is the core selection rule:

A request should become an MCP tool only when it maps to a clear, useful, authorized AI capability.

The tool list is an allowlist. Treat it like a product and security decision.

Rename tools for the AI client

Postman request names are often written for humans browsing a collection.

Examples:

Get Customer
Create
Update v2
List
Old invoice route
Test request
Enter fullscreen mode Exit fullscreen mode

Those names are weak MCP tool names.

Prefer names that are stable, specific, and action-oriented:

get_customer
list_customer_tickets
create_ticket_note
get_customer_subscription
list_unpaid_invoices
Enter fullscreen mode Exit fullscreen mode

Tool descriptions should add the missing context:

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

The AI client should be able to choose the tool without reading your Postman folder structure.

If two tools sound the same, fix the names before adding more tools.

Test the imported tools

After importing and selecting operations, test the tool set before connecting a real client workflow.

For each tool, test:

  • valid minimum input
  • valid full input
  • missing required path variable
  • invalid query value
  • invalid enum
  • empty response
  • missing record
  • unauthorized request
  • wrong tenant
  • rate limit
  • timeout
  • unexpected upstream error

For write tools, also test:

  • duplicate submission
  • invalid state transition
  • insufficient permission
  • payload with extra fields
  • payload missing required business fields
  • behavior in a safe test environment

Then test discovery:

  • Are only the intended tools visible?
  • Are tool names unique?
  • Are descriptions specific?
  • Are required inputs obvious?
  • Are removed or sensitive requests absent?
  • Are resources and prompts visible only if intended?

This is where Postman-derived tools either become reliable or stay as "requests that worked once on my machine."

Prepare the hosted server for production

A hosted MCP server needs more than a successful import.

Before production, confirm:

  • the hosted endpoint is stable
  • the server uses the expected transport
  • HTTPS works
  • authentication is tested with real runtime credential paths
  • the upstream API environment is correct
  • logs show enough detail to debug calls
  • analytics can show request volume, error rate, latency, and capability usage
  • selected tools are versioned
  • rollback or restore is possible after a bad change
  • the original API still enforces tenant, role, record, and action permissions

With 0mcp, teams can import Postman collections, review detected requests, select useful API operations, refine tools, test in the Playground, and host the MCP server over Streamable HTTP. Existing API authentication continues to be used through API key, Bearer token, or OAuth pass-through, and customer credentials are passed through during requests rather than stored by 0mcp.

0mcp currently supports hosted Streamable HTTP servers, not local stdio servers. The original API remains responsible for business logic, authorization, pagination, rate limits, tenant boundaries, and validation.

For the website version of this workflow, see Postman to MCP.

Top comments (0)