Postman MCP Server: Wiring Collections and Specs into Agent Context
Postman MCP Server — connect AI agents (Claude Code, Cursor, VS Code Copilot, Gemini CLI) to your Postman collections, OpenAPI specs, and environments via Model Context Protocol (MCP)
At a glance
- What is it?
- Postman's MCP server exposes Postman workspaces, collections, specs and environments to coding agents over the Model Context Protocol, in four tool configurations and two deployment shapes. The judgement: the tool-scoping design is the interesting part, and the remote server's lack of access to your workstation is the constraint that decides which shape you pick.
- Who is it for?
- Adopt the remote server at https://mcp.postman.com/minimal if your agent needs to read and edit collections, specs and environments and you want OAuth with no key handling; move to /code or /mcp only when a specific task needs those tools, because the Full configuration exposes over 100 tools to the model.
- Can I use it commercially?
- Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 7 days ago.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The gap this fills: agents that cannot see your API definitions
An agent writing client code against an internal API has two sources of truth available: the OpenAPI spec sitting in the repository, or the Postman collection and environment that the API team actually maintains. These drift. The spec in the repo is often a stale export, while the collection carries the current base URLs, auth variables and example responses that people use day to day. The Postman MCP Server exists to close that gap by putting Postman's own objects behind Model Context Protocol tools, so an agent can read a collection or a specification rather than being handed a pasted JSON blob.
The intended audience is narrow and identifiable. The README lists Claude Code, Claude Desktop, Cursor, VS Code, Codex, Antigravity CLI, GitHub Copilot CLI and Kiro, with Docker supported only on the local side. That is a list of MCP hosts, not a list of runtimes. If your team does not already run one of these agents, the project has nothing to offer you yet. The second audience is API platform teams who want collection management to happen from inside an editor: creating and tagging collections, updating documentation, adding comments, or acting across multiple collections without switching to the Postman app. That second group is doing write operations through an agent, which is where the configuration choices start to matter.
Four tool configurations, and why Minimal is the default
The server does not present one flat tool surface. It ships four configurations. Minimal is the default and, per the README, includes only essential tools for basic Postman operations, aimed at users modifying a single element such as a collection, workspace or environment. Code adds tools that generate client code from public and internal API definitions. Full includes all available Postman API tools, described as 100+ tools, aimed at advanced collaboration and Enterprise features. Learn searches Postman Docs for guides, tutorials and reference content.
This is a deliberate answer to a real problem in MCP hosts: every tool you expose consumes context and gives the model more ways to pick wrong. A default that ships the small surface and makes you opt into the large one is the right call, and it is the single design decision here that I would point at first. The trade-off is discoverability. A user who installs the Minimal endpoint and then asks the agent to generate a client from a spec will get a refusal or a workaround, and nothing in the URL tells them that /code exists. The Learn configuration is a different kind of tool entirely: it is documentation retrieval, not workspace access, and mixing it into the same mental model as collection editing will confuse what the agent can actually change.
Remote versus local: the network boundary decides it
There are two deployment shapes and they are not interchangeable. The remote server lives at https://mcp.postman.com, with the path selecting the configuration: /minimal, /code, or /mcp for Full. The local server is an npm package, @postman/postman-mcp-server, run through npx, with --code or --full flags for the larger configurations. The README's own use-case section gives the deciding rule: use the local server to test local APIs, because the remote server will not have network access to your workstation.
That single sentence eliminates the remote option for a large class of work. If your agent is meant to run a collection against a service bound to localhost, or against a staging host reachable only from your VPN, the hosted endpoint cannot reach it no matter how the tools are configured. The remote server is for reading and writing Postman objects, not for executing requests against your machine. Teams that skim the quick start and pick the remote URL because it is one line of configuration will discover this at the worst moment, mid-task, when the agent reports it cannot connect.
Authentication: OAuth on the remote server, API keys everywhere else
The README is explicit that OAuth on the remote server is the recommended path for developer experience and setup speed, that it is compliant with the MCP Authorization specification, and that it requires no manual API key configuration. That covers the main remote endpoint. It does not cover everything. The EU remote server and the local server support only Postman API key authentication.
For the local server, the key goes in the POSTMAN_API_KEY environment variable. For EU or API key auth against the remote server, the README gives the header form: Authorization: Bearer <POSTMAN_API_KEY>. The EU endpoints are https://mcp.eu.postman.com/mcp, /code and /minimal, and the STDIO package takes a --region eu flag or the POSTMAN_API_BASE_URL environment variable directly.
The practical consequence is that EU users get a worse setup story than everyone else, and it is not a documentation gap that will close with a config tweak: OAuth simply is not supported there. If your organisation has a policy against long-lived API keys in developer environments, that policy and EU data residency are in direct conflict for this server, and you need to resolve it before installation rather than after. The key is a Postman account credential with whatever scope that account holds, so the blast radius of a leaked key is your Postman workspace, not just this integration.
Getting it running: the actual commands and config values
The remote path is a URL, not a command. Add https://mcp.postman.com/minimal to your MCP host's configuration, and change the trailing segment to /code or /mcp for the Code or Full configurations. If you are on the EU server or using API key auth, add Authorization: Bearer <POSTMAN_API_KEY> as a header on that entry.
The local path is one command: npx @postman/postman-mcp-server. Append --code or --full for the larger tool sets, and set POSTMAN_API_KEY as an environment variable in whatever config file your host reads. For EU on the STDIO package, add --region eu or set POSTMAN_API_BASE_URL. Docker is listed as a local-only option, with the README pointing to Postman's docs for the specifics rather than inlining a compose file.
What the README does not give you is a single canonical JSON snippet for any host. It routes IDE-specific setup to a table of documentation links, one pair per agent and IDE. That is a reasonable choice for a project supporting eight hosts, but it means your first fifteen minutes are spent in Postman's docs, not in this repository. If you want to inspect the tool list before committing, the README points at the Postman MCP Server collection in Postman's public workspace, which offers MCP requests for the Full and Minimal remote servers and for the local server. That is the cheapest way to see what a configuration actually exposes.
Where this is the wrong tool
The clearest failure mode is the one already named: an agent that needs to call an API running on your laptop or inside your private network cannot use the remote server, full stop. The local server solves it, but then you own the process, the key and the Node runtime on every developer machine.
The second limitation is scope. This is a Postman integration, so it can only see what lives in Postman. If your team's API definitions are generated from code annotations and never imported, or if the collection is a hand-maintained artefact that lags the service by weeks, the agent will confidently read stale data. Nothing in the server validates that a collection matches the deployed API. It hands the model what Postman has.
The third is the Full configuration itself. Exposing 100+ tools to a model is a large surface, and the README frames it as being for advanced collaboration and Enterprise features. That framing is honest about who it is for, but it also means the failure mode is not an error message. It is an agent choosing the wrong tool from a long list, or a host that truncates the list and silently drops the one you needed. Start at Minimal and add configurations when a task demands them, not before.
Finally, the release cadence visible in the repository is high: v2.12.0, v2.12.2 and v2.12.3 within roughly three weeks. Frequent patch releases are normal for a young integration, but they mean you should pin a version in your local setup rather than tracking latest through npx, and re-read the release notes before bumping.
The alternative, and the real difference in approach
The obvious alternative is pointing the agent at a checked-in OpenAPI file and letting it read the spec directly from the repository, with no MCP server in the loop. The difference is not capability, it is where the source of truth lives. A file in the repo is versioned alongside the code, reviewable in a pull request, and available offline. It is also frozen at the moment someone exported it. The MCP server reads the live Postman object, which reflects edits made in the Postman app minutes ago by people who never touch the repository.
That cuts both ways. If your API team treats Postman as the working surface and the repo as an afterthought, the server gives the agent better data than the file does. If the opposite is true, the server adds a network dependency, an authentication credential and a third-party service in the path between your agent and a specification that was already sitting in the working tree. For a solo developer with a stable spec, the file wins on every axis. For a platform team where collections are the shared artefact and multiple people edit them, the server is the only way to keep the agent current without a manual export step. A second alternative worth naming: Postman's own app and CLI for collection management. Those are built for a human at a keyboard, and the MCP server's value is precisely that the agent can do the same operations from inside the editor, which is a different workflow rather than a better one.
Maintenance cost, licensing and what to check before you commit
The licence is Apache-2.0, which permits commercial use, modification and redistribution provided you keep the licence and notice files and state significant changes. That covers the code in this repository. It does not cover the Postman service the server talks to, and it does not cover your Postman account terms. Running the local server under Apache-2.0 does not exempt you from whatever plan limits apply to the API calls the tools make, and the README's mention of Enterprise features inside the Full configuration is a signal that some tools map to paid capabilities. Check which of the 100+ tools your plan actually authorises before you build a workflow on them. This is a description of the licence text, not legal advice.
On maintenance, the costs are concrete. The local server needs Node available and a POSTMAN_API_KEY managed per developer, which means key rotation is now an editor-configuration problem as well as a Postman account problem. The remote server moves that to OAuth but introduces an external dependency in the agent's request path and, for EU users, forces the key model back. Version churn is the other recurring cost: with releases landing days apart, an unpinned npx invocation is a moving target across a team.
The thing to verify first is not in this repository. It is how your specific MCP host renders a tool list of the size the Full configuration produces, and whether the agent's Postman account has narrower permissions than your own. Test that with the Minimal endpoint and a read-only account before you point a write-capable agent at a shared workspace.
Editorial conclusion
Adopt the remote server at https://mcp.postman.com/minimal if your agent needs to read and edit collections, specs and environments and you want OAuth with no key handling; move to /code or /mcp only when a specific task needs those tools, because the Full configuration exposes over 100 tools to the model. Choose the local server via npx @postman/postman-mcp-server when the agent must hit APIs running on your own machine, since the documentation states the remote server has no network path to your workstation. EU users must accept API key authentication, because OAuth is not supported there. Before rolling it out, verify two things yourself: how your chosen MCP host handles a tool list of that size, and whether your workspace permissions match what the agent is allowed to touch.
Community notes