postman

What this skill does

# 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-)

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

3. 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.

| User Intent | Workflow |
|-------------|----------|
| Import a spec, push spec to Postman, create collection from spec, sync, push changes | **Sync Collections** |
| Generate client code, SDK, wrapper, typed client, consume an API | **Generate Client Code** |
| Find API, search endpoints, what's available, discover APIs | **Discover APIs** |
| Run tests, check if tests pass, validate API, test collection | **Run Collection Tests** |
| Create mock server, fake API, mock for frontend, mock URL | **Create Mock Servers** |
| Generate docs, improve documentation, publish docs, API docs | **API Documentation** |
| Security audit, vulnerabilities, OWASP, security check | **API Security Audit** |
| Is my API agent-ready?, scan my API, analyze spec for AI | Use the **postman-api-readiness** skill |

**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