Postman
Full API lifecycle management through the Postman MCP Server (111+ tools for workspaces, collections, specs, environments, mocks, and monitors). Sync specs, generate code, run tests, create mocks, publish docs, and audit security.
Prerequisites
Setup check: Call getAuthenticatedUser via MCP. If it succeeds, you're connected. If it fails, walk through Setup below.
Setup
If MCP tools are not available or getAuthenticatedUser fails:
- Get a Postman API key at https://postman.postman.co/settings/me/api-keys — "Generate API Key", name it "Claude Code", copy the key (starts with
PMAK-).
- Set the environment variable —
export POSTMAN_API_KEY=PMAK-your-key-here (add to ~/.zshrc or ~/.bashrc to persist).
- Verify: call
getAuthenticatedUser, then list workspaces and collection counts so the user sees they're connected.
Routing
Match the user's intent to a workflow, then read that workflow's reference file and follow it. Each file is loaded on demand — read one only when the task needs that depth (progressive disclosure).
| User intent |
Workflow reference |
| Import a spec, push spec to Postman, create collection from spec, sync changes |
references/sync-collections.md |
| Generate client code, SDK, wrapper, typed client, consume an API |
references/generate-client-code.md |
| Find API, search endpoints, what's available, discover APIs |
references/discover-apis.md |
| Run tests, check if tests pass, validate API, test collection |
references/run-collection-tests.md |
| Create mock server, fake API, mock for frontend, mock URL |
references/create-mock-servers.md |
| Generate docs, improve documentation, publish docs, API docs |
references/api-documentation.md |
| Security audit, vulnerabilities, OWASP, security check |
references/security-audit.md |
Routing rules:
- Specific workflows take priority. If intent clearly maps to one, use it.
- Ambiguous requests: ask the user what they need.
- Multi-step requests chain workflows. "Import my spec and run tests" = Sync then Test.
- Only use
mcp__postman__* tools directly for single targeted updates or when the user explicitly asks.
References
references/mcp-limitations.md — known MCP behaviors and workarounds (300KB+ payloads from getWorkspaces/getCollection model=full, async HTTP 202 polling, plan-gated tag tools, aggregate-only runCollection, public-only searchPostmanElements) · read before composing any tool calls a workflow doesn't already cover.references/mcp-tools.md — the complete tool catalog by category · read when picking the right tool outside a workflow.
Error Handling
These patterns apply across all workflows:
| Error |
Response |
| MCP tools not available |
"The Postman MCP Server isn't configured. Set your POSTMAN_API_KEY environment variable and restart your editor." |
| 401 Unauthorized |
"Your Postman API key was rejected. Generate a new one at https://postman.postman.co/settings/me/api-keys" |
| Network timeout |
Retry once. Check https://status.postman.com for outages. |
| Async operation stuck |
If polling shows no progress after 30 seconds, inform user and suggest checking Postman app directly. |
| Collection not found |
"No collection matching that name. Try discovering APIs across your workspace." |
| Empty collection |
"This collection has no requests. Add endpoints in Postman or sync from a local spec." |
| Invalid spec |
Report specific parse errors with line numbers. Offer to fix common YAML/JSON syntax issues. |
| Plan limitations |
"Some features may require a paid Postman plan. Core operations work on all plans." |
1---2name: postman3description: Full API lifecycle via the Postman MCP Server — sync OpenAPI specs to collections, generate typed clients, run API tests, create mocks, publish docs, OWASP audits. Use for Postman, collections, specs, mocks, or SDKs.4---56# Postman78Full API lifecycle management through the Postman MCP Server (111+ tools for workspaces, collections, specs, environments, mocks, and monitors). Sync specs, generate code, run tests, create mocks, publish docs, and audit security.910## Prerequisites1112**Setup check**: Call `getAuthenticatedUser` via MCP. If it succeeds, you're connected. If it fails, walk through Setup below.1314## Setup1516If MCP tools are not available or `getAuthenticatedUser` fails:17181. Get a Postman API key at https://postman.postman.co/settings/me/api-keys — "Generate API Key", name it "Claude Code", copy the key (starts with `PMAK-`).192. Set the environment variable — `export POSTMAN_API_KEY=PMAK-your-key-here` (add to `~/.zshrc` or `~/.bashrc` to persist).203. Verify: call `getAuthenticatedUser`, then list workspaces and collection counts so the user sees they're connected.2122## Routing2324Match the user's intent to a workflow, then read that workflow's reference file and follow it. Each file is loaded on demand — read one only when the task needs that depth (progressive disclosure).2526| User intent | Workflow reference |27|-------------|--------------------|28| Import a spec, push spec to Postman, create collection from spec, sync changes | `references/sync-collections.md` |29| Generate client code, SDK, wrapper, typed client, consume an API | `references/generate-client-code.md` |30| Find API, search endpoints, what's available, discover APIs | `references/discover-apis.md` |31| Run tests, check if tests pass, validate API, test collection | `references/run-collection-tests.md` |32| Create mock server, fake API, mock for frontend, mock URL | `references/create-mock-servers.md` |33| Generate docs, improve documentation, publish docs, API docs | `references/api-documentation.md` |34| Security audit, vulnerabilities, OWASP, security check | `references/security-audit.md` |3536**Routing rules:**371. Specific workflows take priority. If intent clearly maps to one, use it.382. Ambiguous requests: ask the user what they need.393. Multi-step requests chain workflows. "Import my spec and run tests" = Sync then Test.404. Only use `mcp__postman__*` tools directly for single targeted updates or when the user explicitly asks.4142## References4344- `references/mcp-limitations.md` — known MCP behaviors and workarounds (300KB+ payloads from `getWorkspaces`/`getCollection model=full`, async HTTP 202 polling, plan-gated tag tools, aggregate-only `runCollection`, public-only `searchPostmanElements`) · read **before composing any tool calls** a workflow doesn't already cover.45- `references/mcp-tools.md` — the complete tool catalog by category · read when picking the right tool outside a workflow.4647## Error Handling4849These patterns apply across all workflows:5051| Error | Response |52|-------|----------|53| MCP tools not available | "The Postman MCP Server isn't configured. Set your POSTMAN_API_KEY environment variable and restart your editor." |54| 401 Unauthorized | "Your Postman API key was rejected. Generate a new one at https://postman.postman.co/settings/me/api-keys" |55| Network timeout | Retry once. Check https://status.postman.com for outages. |56| Async operation stuck | If polling shows no progress after 30 seconds, inform user and suggest checking Postman app directly. |57| Collection not found | "No collection matching that name. Try discovering APIs across your workspace." |58| Empty collection | "This collection has no requests. Add endpoints in Postman or sync from a local spec." |59| Invalid spec | Report specific parse errors with line numbers. Offer to fix common YAML/JSON syntax issues. |60| Plan limitations | "Some features may require a paid Postman plan. Core operations work on all plans." |
jgamaraalv