> This page is for Postman Docs, version Latest (v12) (default). > For other versions, use one of these documentation indexes: > - Latest (v12) (default): https://learning.postman.com/latest-v-12/llms.txt > - v11: https://learning.postman.com/v11/llms.txt > For clean Markdown content of this page, append .md to this URL. For the complete documentation index, see https://learning.postman.com/llms.txt. # Postman CLI MCP commands `(postman mcp)` > Inspect a Model Context Protocol (MCP) server and list and call its tools, resources, and prompts from the command line using MCP commands. This topic covers Model Context Protocol (MCP) commands for the [Postman CLI](/docs/postman-cli/postman-cli-overview/). The `postman mcp` commands connect to a live MCP server and report what it offers, so you can explore a server and check an integration from your terminal. These commands are an MCP client. They connect through the same engine that [`postman collection run`](/docs/postman-cli/postman-cli-run-collection/) uses, so a server behaves the same way in both. No `postman mcp` command edits your project files. Because each command runs once and exits, a server that asks the client for sampling or elicitation mid-operation gets no answer: the request is declined. To save an MCP request in a collection, use [`postman collection request add --type mcp`](/docs/postman-cli/postman-cli-collections/#postman-collection-request-add). ## Options Every `postman mcp` command needs [a target MCP server to connect to](#target-options). In addition, it accepts any of the [options that apply to every command](#common-options) and any options specific to the command. ### Target options Every `postman mcp` command targets one MCP server. Passing two targets is a usage error that exits with code `2`. **`--request `** Reuses a saved local-mode MCP request. Pass the path to a `.request.yaml` file, or the ID of an MCP request under `postman/collections/`. The command uses the request's URL or command, headers, authentication, and settings, along with its collection's variables and its collection's and folders' authentication and MCP scripts. A saved request with no URL, or a STDIO request with no command, exits with code `2`. A saved STDIO command runs in the current directory, so run a request with a relative command from its own project. --- **`--url `** Connects to a remote server over HTTP, using streamable HTTP and falling back to server-sent events (SSE). --- **`--command `** Starts a local server and talks to it over STDIO. Always requires `--allow-stdio`. Without it, the command exits with code `8` and starts nothing. The value is split into words at every space, including inside quotes. Every word after an absolute path in the first argument position is read as part of that path, so `node /Users/me/my server.js` starts `/Users/me/my server.js`, and `node /Users/me/server.js --port 3000` can't start. The Postman CLI warns about both. Give the script a path relative to the current directory instead: ```bash postman mcp tools list --allow-stdio -- node ../server/index.js --transport stdio ``` > **Warning** > > The server runs with your permissions, so starting it can change your machine, whether you go on to call one of its tools. What a server's tools additionally do when called is up to the server. --- **`-- [args...]`** The same as `--command`, with the command and its arguments written after `--` instead of in one quoted string. Each word reaches the server as written. Put the subcommand's own arguments and options before `--`. --- ### Common options These options apply to every `postman mcp` command, alongside the target you choose in [Target options](#target-options) and any options specific to the command. **`-H, --header `** Adds an HTTP header. Repeat the option for more than one. Applies to HTTP targets only. An `Authorization` header replaces the authentication that a `--request` target saves or inherits. --- **`--command-env `** Sets an environment variable for the STDIO server. Repeat the option for more than one. The server otherwise gets only a minimal environment. On macOS and Linux, that's `HOME`, `LOGNAME`, `PATH`, `SHELL`, `TERM`, and `USER`. --- **`--allow-stdio`** Allows the command to start a local process. Required for every STDIO target. --- **`--transport `** `'http' | 'stdio'` Checks that the target uses this transport. --- **`-k, --insecure`** Skips TLS certificate verification. Verification is on by default. --- **`--timeout-request `** — default: 60000 Sets the time limit for each MCP operation, including the handshake and every request. Use `0` for no limit. Overrides a saved request's `settings.requestTimeout`. --- **`--protocol-version `** `'auto' | 'legacy' | '2026-07-28'` Sets protocol negotiation. Defaults to the saved request's `settings.version`, or `auto`, which tries the stateless `2026-07-28` protocol first and falls back to the legacy protocol. `legacy` can't connect to a server that offers only `2026-07-28`. You can't pin other protocol dates. --- **`-e, --environment `** Resolves `{{variables}}` in the URL, headers, command, and arguments from a local environment file. --- **`--env-var `** Sets a variable for `{{variable}}` resolution. Repeat the option for more than one. Overrides `-e`. --- **`--json`** Prints one JSON document on standard output and nothing else. --- **`--debug`** Prints each runtime event, and the MCP client's debug messages, to standard error, without headers or bodies. --- ## Authenticate to an MCP server Pass a token you already have instead of signing in interactively. These commands don't support the MCP authorization flow of discovery, client registration, and browser sign-in, so a server that requires it fails with exit code `3`: ```bash postman mcp tools list --url https://example.com/mcp -H "Authorization: Bearer $TOKEN" ``` You can also save the token on a request, or on its collection or folder, and pass `--request`. The command reads `auth` of type `bearer` from `credentials.token`, or type `oauth2` from `credentials.accessToken`. Either can be a `{{variable}}` that you resolve with `-e` or `--env-var`. A saved OAuth 2.0 token is sent as saved and never refreshed, so replace it when it expires. ## `postman mcp inspect` Reports what the MCP server returns at `initialize`, including its server information, the negotiated protocol version and era, its capabilities, and its instructions. It also reports how many tools, resources, resource templates, and prompts the server lists, from one discovery that follows every page. A field the server didn't send is `null`, and a count is `null` for a capability the server doesn't advertise. Accepts any [target options](#target-options) and [common options](#common-options). ### Usage ```bash postman mcp inspect --url ``` ### Examples ```bash postman mcp inspect --url http://127.0.0.1:3000/mcp postman mcp inspect --allow-stdio -- node ./server/index.js --transport stdio ``` ## `postman mcp tools list` Lists the tools the MCP server offers, following every page of results. Accepts any [target options](#target-options) and [common options](#common-options). ### Usage ```bash postman mcp tools list --url ``` ### Examples ```bash postman mcp tools list --url http://127.0.0.1:3000/mcp postman mcp tools list --request "postman/collections/My Server/add.request.yaml" ``` ## `postman mcp tools call` Calls one of the MCP server's tools and prints the result. Before it sends anything, the command checks the arguments against the tool's `inputSchema`. Every `required` property is present, each value is in its property's `enum` or matches its `const`, and no value is `null` where the property's types leave `null` out. Only top-level properties are checked, and the server judges the rest. A call that fails a check is a usage error that exits with code `2`, naming every problem, and nothing is sent. With a `--request` target and no `--args` or `--arg`, the command sends the saved message's `params`, including `arguments` and `_meta`, when it calls the same tool. A saved message is sent as written, without the argument checks, so a request can keep a deliberately invalid call. ### Usage ```bash postman mcp tools call --url ``` **``** — required The name of the tool to call. --- ### Options Accepts any [target options](#target-options) and [common options](#common-options), in addition to the options below. **`--args `** The tool's arguments as a JSON object, given inline, as `@path` to a JSON file, or as `-` to read from standard input. Can't be combined with `--arg`. --- **`--arg `** Sets one argument. Repeat the option for more than one, where a repeated key keeps the last value. Each value takes the type the tool's `inputSchema` declares for that property, so `id=007` stays the string `"007"` for a string property. A value that doesn't fit the declared type is a usage error. Can't be combined with `--args`. --- ### Examples ```bash postman mcp tools call add --url http://127.0.0.1:3000/mcp postman mcp tools call add --arg a=2 --arg b=3 --url http://127.0.0.1:3000/mcp --json ``` ## `postman mcp resources list` Lists the resources the MCP server offers. To list its resource templates instead, run `postman mcp resources templates list`. Accepts any [target options](#target-options) and [common options](#common-options). ### Usage ```bash postman mcp resources list --url ``` ### Examples ```bash postman mcp resources list --url http://127.0.0.1:3000/mcp postman mcp resources templates list --url http://127.0.0.1:3000/mcp ``` ## `postman mcp resources read` Reads one of the MCP server's resources by URI. Text contents print verbatim, and binary contents are summarized. With `--json`, binary contents keep their base64 `blob`. Accepts any [target options](#target-options) and [common options](#common-options). ### Usage ```bash postman mcp resources read --url ``` **``** — required The URI of the resource to read. --- ### Example ```bash postman mcp resources read file:///readme.md --url http://127.0.0.1:3000/mcp ``` ## `postman mcp prompts list` Lists the prompts the MCP server offers. Accepts any [target options](#target-options) and [common options](#common-options). ### Usage ```bash postman mcp prompts list --url ``` ### Example ```bash postman mcp prompts list --url http://127.0.0.1:3000/mcp ``` ## `postman mcp prompts get` Gets one of the MCP server's prompts by name. Prompt arguments are strings, so any other value in `--args` is a usage error, and `--arg` values are always sent as strings. A call that's missing an argument the prompt marks `required` is a usage error that exits with code `2`, and nothing is sent. ### Usage ```bash postman mcp prompts get --url ``` **``** — required The name of the prompt to get. --- ### Options Accepts any [target options](#target-options) and [common options](#common-options), in addition to the options below. **`--args `** The prompt's arguments as a JSON object, given inline, as `@path` to a JSON file, or as `-` to read from standard input. Can't be combined with `--arg`. --- **`--arg `** Sets one argument. Repeat the option for more than one. Can't be combined with `--args`. --- ### Example ```bash postman mcp prompts get summarize --url http://127.0.0.1:3000/mcp ``` ## Scripts on a saved MCP request A `--request` target's [scripts](/docs/postman-cli/postman-cli-collections/#postman-collection-request-update), and its collection's and folders' MCP scripts such as `mcp:beforeConnect`, run the way they do in [a collection run](/docs/postman-cli/postman-cli-run-collection/): * `beforeConnect` runs before the session opens. * `afterConnect` runs on the session's first discovery, which is straight after connecting when the request has one. * `afterResponse` runs after `tools call`, `prompts get`, and `resources read`. * `afterDisconnect` runs once the session closes. Their `pm.test` results print under a Tests section, and `--json` adds them as a `tests` array. A failed test or a script error exits with code `1`. A `beforeConnect` script that calls `pm.execution.skipRequest()` skips the request: nothing is sent to the server, the tests that ran still print, and a notice goes to standard error. The command then exits with code `0`, or `1` if a test failed. ## Exit codes | Code | Meaning | | ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `0` | Success. | | `1` | Failure. The server couldn't be reached, an operation timed out, the server returned an error, `tools call` returned a result with `isError: true`, or a saved request's script failed a test. The result is still printed. | | `2` | Usage error, such as an unknown subcommand, no target or two targets, a bad option value, `--args` that isn't a JSON object, an `--arg` value that doesn't fit the tool's schema, or an unknown `--request`. | | `3` | The server rejected or requires credentials, returning HTTP 401 or 403. | | `4` | Partial result. `inspect` couldn't list a capability the server advertises, or a list came back incomplete. The output is still printed. | | `5` | Canceled with **Ctrl+C**. | | `8` | Refused, and nothing was started. This is a STDIO target without `--allow-stdio`. | ## See also * [Postman CLI collection commands](/docs/postman-cli/postman-cli-collections/) * [Set up the Postman MCP Server](/docs/developer/postman-api/postman-mcp-server/set-up-postman-mcp-server/)