Postman

Postman Agent Skill

Full API lifecycle management through the Postman MCP Server. Sync specs, generate code, run tests, create mocks, publish docs, and audit security.

Version: 2.0.1 Requires: Postman MCP Server

Prerequisites

This skill requires the Postman MCP Server to be configured. The MCP server exposes 111+ tools for interacting with Postman workspaces, collections, specs, environments, mocks, monitors, and more.

Setup check: Call getAuthenticatedUser via MCP. If it succeeds, you're connected. If it fails, walk through Setup below.

Important: MCP Tool Behavior

Before using the workflows below, be aware of these behaviors:

• `getWorkspaces` returns ALL workspaces. For large organizations this can be 300KB+. If you already have a workspace ID, use getWorkspace(workspaceId) directly instead.
• `getCollection` default response is a lightweight map with itemRefs (folder/request tree). This is efficient for discovery. Only use model=full when you need complete request/response bodies, and be aware it can exceed 300KB for large collections. Prefer targeted getCollectionRequest and getCollectionResponse calls for specific endpoints.
• `getTaggedEntities` returns 404 for missing tags, not an empty array. Handle this gracefully. Tag functionality may require an Enterprise plan.
• `runCollection` returns aggregate results only (total requests, passed, failed, duration). It does NOT return per-request detail or error messages. For debugging specific failures, examine individual requests with getCollectionRequest and getCollectionResponse after the run.
• `searchPostmanElements` only searches the PUBLIC Postman network, not private workspaces. Always search private workspace first with getCollections.

Setup

If MCP tools are not available or getAuthenticatedUser fails:

1. Get a Postman API key:

• Go to https://postman.postman.co/settings/me/api-keys
• Click "Generate API Key", name it "Claude Code"
• Copy the key (starts with PMAK-)

1. Set the environment variable: `` export POSTMAN_API_KEY=PMAK-your-key-here ` Add to ~/.zshrc or ~/.bashrc` to persist.

1. Verify: Call getAuthenticatedUser. On success, call getWorkspaces to list workspaces, then getCollections with the workspace ID to count resources.

Present:

Connected as: <user name>

Your workspaces:
  - My Workspace (personal) - 12 collections, 3 specs
  - Team APIs (team) - 8 collections, 5 specs

You're all set.

Routing

When the user's request involves Postman or APIs, match their intent to the correct workflow below. Always prefer these structured workflows over raw MCP tool calls.

Routing rules:

1. Specific workflows take priority. If intent clearly maps to one, use it.
2. Ambiguous requests: ask the user what they need.
3. Multi-step requests chain workflows. "Import my spec and run tests" = Sync then Test.
4. Only use mcp__postman__* tools directly for single targeted updates or when the user explicitly asks.

Workflow: Sync Collections

Keep Postman collections in sync with API code. Create new collections from OpenAPI specs, update existing ones, or push endpoint changes.

Step 1: Understand What Changed

Detect or ask:

• Is there a local OpenAPI spec? Search for **/openapi.{json,yaml,yml}, **/swagger.{json,yaml,yml}
• Did the user add/remove/modify endpoints?
• Is there an existing Postman collection to update, or do they need a new one?

Step 2: Resolve Workspace

If the user provides a workspace ID, call getWorkspace(workspaceId) directly. Otherwise, call getCollections with a workspace ID if known, or ask the user which workspace to use. Avoid calling getWorkspaces (no filter) on large org accounts as it returns all workspaces (300KB+).

Step 3: Find or Create the Collection

Updating an existing collection:

1. Call getCollections with the workspace parameter
2. Match by name or ask which collection
3. Call getCollection to get current state

Creating from a spec:

1. Read the local OpenAPI spec
2. Call createSpec with workspaceId, name, type (one of OPENAPI:2.0, OPENAPI:3.0, OPENAPI:3.1, ASYNCAPI:2.0), and files (array of {path, content})
3. Call generateCollection from the spec. This is async (HTTP 202). Poll getGeneratedCollectionSpecs or getSpecCollections until complete.
4. Call createEnvironment with variables from the spec:

• base_url from servers[0].url
• Auth variables from securitySchemes (mark as secret)
• Common path parameters

Step 4: Sync

Spec to Collection (most common):

1. Call createSpec or updateSpecFile with local spec content
2. Call syncCollectionWithSpec to update the collection. Async (HTTP 202). Poll getCollectionUpdatesTasks for completion.
3. Note: syncCollectionWithSpec only supports OpenAPI 3.0. For Swagger 2.0 or OpenAPI 3.1, use updateSpecFile and regenerate via generateCollection.
4. Report what changed

Collection to Spec (reverse sync):

1. Call syncSpecWithCollection to update the spec from collection changes
2. Write the updated spec back to the local file

Manual updates (no spec):

1. createCollectionRequest to add new endpoints
2. updateCollectionRequest to modify existing ones
3. createCollectionFolder to organize by resource
4. createCollectionResponse to add example responses

Step 5: Confirm

Collection synced: "Pet Store API" (15 requests)
  Added:    POST /pets/{id}/vaccinations
  Updated:  GET /pets - added 'breed' filter parameter
  Removed:  (none)

  Environment: "Pet Store - Development" updated
  Spec Hub: petstore-v3.1.0 pushed

Workflow: Generate Client Code

Generate typed client code from Postman collections. Reads private API definitions and writes production-ready code matching the project's conventions.

Step 1: Find the API

1. If workspace ID is known, call getWorkspace(workspaceId) to get the full inventory (collections, specs, environments) in one call. Otherwise ask the user which workspace.
2. Call getCollections with workspace parameter. Use name filter if specified.
3. If no results in private workspace, fall back to searchPostmanElements (public network only)
4. Call getCollection for the lightweight map (default, no model param)
5. Call getSpecDefinition if a linked spec exists (richer type info)

Step 2: Understand the API Shape

For each relevant endpoint:

1. Call getCollectionFolder for resource grouping
2. Call getCollectionRequest for method, URL, headers, auth, body schema, parameters
3. Call getCollectionResponse for status codes, response shapes, error formats
4. Call getEnvironment for base URLs and variables
5. Call getCodeGenerationInstructions for Postman-specific codegen guidance

Step 3: Detect Project Language

If not specified, detect from the project:

• package.json or tsconfig.json -> TypeScript/JavaScript
• requirements.txt or pyproject.toml -> Python
• go.mod -> Go
• Cargo.toml -> Rust
• pom.xml or build.gradle -> Java
• Gemfile -> Ruby

Step 3b: Check for Variable Mismatches