postman-claude-code-plugin/commands/mock.md

description, allowed-tools

description	allowed-tools
Create Postman mock servers for frontend development. Generates missing examples, provides integration config.	Bash, Read, Write, Glob, Grep, mcp__postman__*

Create Mock Servers

Spin up a Postman mock server from a collection or spec. Get a working mock URL for frontend development, integration testing, or demos.

Prerequisites

The Postman MCP Server must be connected. If MCP tools aren't available, tell the user: "Run /postman:setup to configure the Postman MCP Server."

Workflow

Step 1: Find the Source

Call getWorkspaces to get the user's workspace ID. If multiple workspaces exist, ask which to use.

From existing collection:

• Call getCollections with the workspace parameter
• Select the target collection

From local spec:

• Find OpenAPI spec in the project
• Import it first:
  1. Call createSpec with workspaceId, name, type, and files
  2. Call generateCollection. Async (HTTP 202). Poll getGeneratedCollectionSpecs or getSpecCollections for completion. Note: getAsyncSpecTaskStatus may return 403 on some plans.

Step 2: Check for Examples

Mock servers serve example responses. Call getCollection and check if requests have saved responses.

If examples are missing:

Your collection doesn't have response examples. Mock servers need
these to know what to return.

Generating realistic examples from your schemas...

For each request without examples:

1. Call getCollectionRequest to get the schema
2. Generate a realistic example response from the schema
3. Call createCollectionResponse to save the example

Step 3: Check for Existing Mocks

Before creating a new mock, call getMocks to check if one already exists for this collection. If found, call getMock to get its URL and present it. Only create a new mock if none exists or the user explicitly wants a new one.

Step 4: Create Mock Server

Call createMock with:

• Workspace ID
• Collection UID in ownerId-collectionId format (from getCollection response's uid field)
• Environment ID (if applicable)
• Name: <api-name> Mock
• Private: false (or true if user prefers)

Step 5: Present Mock URL

Mock server created: "Pet Store API Mock"
  URL: https://<mock-id>.mock.pstmn.io
  Status: Active

  Try it:
    curl https://<mock-id>.mock.pstmn.io/pets
    curl https://<mock-id>.mock.pstmn.io/pets/1
    curl -X POST https://<mock-id>.mock.pstmn.io/pets -d '{"name":"Buddy"}'

  The mock serves example responses from your collection.
  Update examples in Postman to change mock behavior.

Step 6: Integration

Quick integration:

  # Add to your project .env
  API_BASE_URL=https://<mock-id>.mock.pstmn.io

  # Or in your frontend config
  const API_URL = process.env.API_BASE_URL || 'https://<mock-id>.mock.pstmn.io';

Step 7: Publish (optional)

If the user wants the mock publicly accessible:

• Call publishMock to make it available without authentication
• Useful for demos, hackathons, or public documentation
• Call unpublishMock to make it private again

Error Handling

• MCP not configured: "Run /postman:setup to configure the Postman MCP Server."
• No examples in collection: Auto-generate from schemas (Step 2). If no schemas either, ask the user to provide sample responses.
• 401 Unauthorized: "Your Postman API key was rejected. Generate a new one at https://postman.postman.co/settings/me/api-keys and run /postman:setup."
• MCP timeout: Retry once. If it still fails, check https://status.postman.com for outages.
• Plan limitations: "Mock server creation may require a Postman Basic plan or higher for increased usage limits."