KunanonJ Postman Knowledge Base
Core Postman concepts and MCP tool guidance for making better decisions when working with Postman APIs.
Core Concepts
Collection: A group of API requests organized in folders. The primary unit of work in Postman. Contains requests, examples (saved responses), test scripts, and documentation. Think of it as a living API reference.
Environment: A set of key-value pairs (variables) scoped to a context like dev, staging, or prod. Used to swap base URLs, auth tokens, and config without changing the requests themselves.
Workspace: A container for collections, environments, specs, mocks, and monitors. Can be personal, team, or public. Most users have one primary workspace.
Spec (Spec Hub): An OpenAPI or AsyncAPI definition stored in Postman. Can generate collections automatically and stay synced with them. The source of truth for API shape.
Request: A single API call definition: HTTP method, URL, headers, body, query params, and test scripts. Lives inside a collection, optionally inside a folder.
Response (Example): A saved example response for a request. Includes status code, headers, and body. Used by mock servers to know what to return and by documentation to show expected responses.
Folder: A grouping within a collection, typically by resource (e.g., "Users", "Orders", "Products"). Can contain requests and nested folders.
Tags: Labels on collections for categorization and search. Useful for finding related APIs.
Monitor: A scheduled collection runner that checks API health. Runs on a cron schedule and alerts on failures.
Mock Server: A fake API that returns example responses from a collection. Used for frontend development before the real API is ready, or for testing in isolation.
When to Use What
| Goal | Approach |
|---|---|
| Push code changes to Postman | Spec Hub + sync (createSpec -> syncCollectionWithSpec) |
| Consume a Postman API in code | Read collection + codegen (getCollection -> generate client) |
| Find an API | Search private network (searchPostmanElementsInPrivateNetwork) or user's workspace (getWorkspaces + getCollections) or public network (searchPostmanElementsInPublicNetwork) |
| Test an API | Run collection (runCollection with environment) |
| Fake an API for frontend | Mock server (createMock from collection with examples) |
| Document an API | Analyze collection completeness, fill gaps, improve descriptions |
| Secure an API | Audit spec and collection against OWASP API Top 10 |
MCP Tool Selection Guide
Reading Data
getWorkspaces-- List all accessible workspacesgetCollections-- List collections in a workspacegetCollection-- Get full collection detail (always use full model)getCollectionFolder-- Get folder contentsgetCollectionRequest-- Get request details (method, URL, body, params)getCollectionResponse-- Get saved example responsesgetEnvironment/getEnvironments-- Get environment variablesgetSpecDefinition-- Get the full OpenAPI/AsyncAPI specgetAllSpecs-- List all specs in a workspace
Writing Data
createCollection-- Create new collection (cannot nest folders, use decomposed approach)createCollectionFolder-- Create folder in collectioncreateCollectionRequest-- Create request in collection or foldercreateCollectionResponse-- Save example responsecreateEnvironment-- Create environment with variablescreateSpec-- Upload OpenAPI spec to Spec HubupdateSpecFile-- Update an existing specupdateCollectionRequest-- Modify request detailscreateMock-- Create mock server from collection
Syncing
syncCollectionWithSpec-- Update collection from spec (async, OpenAPI 3.0 only)syncSpecWithCollection-- Update spec from collection changesgenerateCollection-- Generate collection from spec (async)
Running
runCollection-- Execute collection tests
Searching
searchPostmanElementsInPrivateNetwork-- Search private/org APIs (default)searchPostmanElementsInPublicNetwork-- Search public Postman networkgetTaggedEntities-- Find by tag
For detailed limitations and workarounds, see the companion file mcp-limitations.md.