mirror of
https://github.com/Postman-Devrel/postman-claude-code-plugin.git
synced 2026-04-16 10:29:58 +00:00
100 lines
2.9 KiB
Markdown
100 lines
2.9 KiB
Markdown
---
|
|
description: Set up Postman MCP Server. Configure API key, verify connection, select workspace.
|
|
allowed-tools: 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."
|