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

description, allowed-tools

description	allowed-tools
Set up Postman MCP Server. Configure API key, verify connection, select workspace.	mcp__postman__*

First-Run Configuration

Walk the user through Postman setup for Claude Code. Validate everything works before they use other commands.

Workflow

Step 1: Check MCP Connection

Verify the Postman MCP Server is available by calling getAuthenticatedUser.

If it works: Skip to Step 3 (workspace verification).

If it fails or tools aren't available: Proceed to Step 2.

Step 2: Configure API Key

Let's set up Postman for Claude Code.

1. Go to: https://postman.postman.co/settings/me/api-keys
2. Click "Generate API Key"
3. Name it "Claude Code"
4. Copy the key (starts with PMAK-)

Then set it as an environment variable:

  export POSTMAN_API_KEY=PMAK-your-key-here

Add it to your shell profile (~/.zshrc or ~/.bashrc) to persist across sessions.

Wait for the user to confirm they've set the key. Then verify with getAuthenticatedUser.

If 401: "API key was rejected. Check for extra spaces or generate a new one at https://postman.postman.co/settings/me/api-keys"

If timeout: "Can't reach the Postman MCP Server. Check your network and https://status.postman.com"

Step 3: Workspace Verification

After successful connection:

1. Call getWorkspaces to list workspaces
2. Call getCollections with the first workspace ID to count collections
3. Call getAllSpecs with the workspace ID to count specs

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.

If workspace is empty:

Your workspace is empty. You can:
  /postman:sync     — Push a local OpenAPI spec to Postman
  /postman:search   — Search for APIs across your org's private network or the public Postman network

Step 4: Suggest First Command

Based on what the user has:

Has collections:

Try one of these:
  /postman:search   — Find APIs across your workspace
  /postman:test     — Run collection tests
  /postman:codegen  — Generate client code from a collection

Has specs but no collections:

Try this:
  /postman:sync — Generate a collection from one of your specs

Empty workspace:

Try this:
  /postman:sync — Import an OpenAPI spec from your project

Error Handling

• MCP tools not available: "The Postman MCP Server isn't loaded. Make sure the plugin is installed and restart Claude Code."
• API key not set: Walk through Step 2 above.
• 401 Unauthorized: "Your API key was rejected. Generate a new one at https://postman.postman.co/settings/me/api-keys"
• Network timeout: "Can't reach the Postman MCP Server. Check your network and https://status.postman.com for outages."
• Plan limitations: "Some features (team workspaces, monitors) require a paid Postman plan. Core commands work on all plans."