> 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](/latest-v-12/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`](/latest-v-12/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. The `login` and `logout` commands, and a command that signs you in after the server answers `401` or `403`, write only your MCP sign-ins, in the Postman home directory. Because each command runs once and exits, a server that asks the client for sampling or elicitation mid-operation gets no answer and the request is declined.

To save an MCP request in a collection, use [`postman collection request add --type mcp`](/latest-v-12/docs/postman-cli/postman-cli-collections#postman-collection-request-add).

## Options

The `postman mcp inspect`, `tools`, `resources`, and `prompts` commands each need [a target MCP server to connect to](#target-options), and accept any of the [options that apply to those commands](#common-options), plus any options specific to the command. The `postman mcp login`, `logout`, and `credentials` commands take their own target and options, covered in their own sections.

### Target options

The `postman mcp inspect`, `tools`, `resources`, and `prompts` commands each target one MCP server, chosen from the following options. Passing two targets is a usage error that exits with code `2`.

**`--request <path-or-id>`**

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 <url>`**

Connects to a remote server over HTTP, using streamable HTTP and falling back to server-sent events (SSE).

---

**`--command <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.

---

**`-- <command> [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 the `postman mcp inspect`, `tools`, `resources`, and `prompts` commands, alongside the target you choose in [Target options](#target-options) and any options specific to the command.

**`-H, --header <key:value>`**

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.

---

**`--login`**

When an HTTP server that offers OAuth answers `401` or `403` and the command sent no credentials, signs in without asking, then retries the command once. Exits with code `8` where no browser can open, such as in CI, over SSH, or in a container. Can't be used with `--no-login` or with a STDIO target. To learn more, see [Authenticate to an MCP server](#authenticate-to-an-mcp-server).

---

**`--no-login`**

Never asks to sign in. When an HTTP server needs a sign-in, the command exits with code `3` and prints how to sign in. Can't be used with `--login` or with a STDIO target.

---

**`--command-env <key=value>`**

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 <transport>`** `'http' | 'stdio'`

Checks that the target uses this transport.

---

**`-k, --insecure`**

Skips TLS certificate verification. Verification is on by default.

---

**`--timeout-request <ms>`** — 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 <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 <path>`**

Resolves `{{variables}}` in the URL, headers, command, and arguments from a local environment file.

---

**`--env-var <key=value>`**

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

For a server that uses OAuth, sign in once with [`postman mcp login`](#postman-mcp-login). Then every `postman mcp` command that connects to that server sends the stored sign-in:

```bash
postman mcp login --url https://example.com/mcp
postman mcp tools list --url https://example.com/mcp
```

A command sends the first of these credentials that applies:

1. An `Authorization` header that you pass with `-H`.
2. The saved request's own authentication, when you pass `--request`.
3. Authentication that the request inherits from its folder, then its collection.
4. The sign-in that `postman mcp login` stored for the server.
5. None.

The command sends credentials from the first three levels as given. It never refreshes them and never starts a sign-in because of them. To use your own token, pass it with `-H "Authorization: Bearer $TOKEN"`, or save it 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 stored sign-in goes only to the server it was stored for. If a request connects to a different URL, for example because a Before connect script changed it, the command exits with code `8` and sends nothing. The command refreshes a stored sign-in that has a refresh token before connecting when it expires within a minute, and once more if the server rejects it with `401`. A stored sign-in without a refresh token is used until it expires.

### When the server answers `401` or `403`

When the command sent no credentials, it checks, without credentials, whether the server offers OAuth. If it does, a command that runs in a terminal asks whether to sign in:

```text
! https://example.com/mcp requires sign-in (OAuth, issuer auth.example.com).
? Sign in in your browser now? › (Y/n)
```

If you answer yes, the command runs the same sign-in as `postman mcp login`, then retries once. With `--json`, only the result of that retry goes to standard output. If you answer no, or the command can't ask, it exits with code `3` and prints how to sign in. If you press **Ctrl+C**, it exits with code `5`. The command asks only when standard input and standard error are terminals, outside CI, and `--silent` isn't set. It asks at most once.

Use `--login` to sign in without asking, or `--no-login` to never sign in. To set the default for every command, set the `POSTMAN_MCP_LOGIN` environment variable to `prompt` (the default), `always`, or `never`. Any other value exits with code `2`.

A server that doesn't offer OAuth, such as one that uses an API key, gets only the lines about passing a token or using saved authentication.

## `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 <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 <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 <tool> --url <url>
```

**`<tool>`** — 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 <json>`**

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 <key=value>`**

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 <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 templates list`

Lists the resource templates the MCP server offers. A resource template is a URI pattern that describes resources the server can generate. To list the server's fixed resources instead, run `postman mcp resources list`.

Accepts any [target options](#target-options) and [common options](#common-options).

### Usage

```bash
postman mcp resources templates list --url <url>
```

### Example

```bash
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 <uri> --url <url>
```

**`<uri>`** — 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 <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 <name> --url <url>
```

**`<name>`** — 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 <json>`**

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 <key=value>`**

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
```

## `postman mcp login`

Signs in to an MCP server that uses OAuth and stores the sign-in for the other `postman mcp` commands. The command opens your browser to sign in and waits up to 5 minutes. Signing in again replaces the stored sign-in for that server.

The sign-in uses PKCE with `S256`. If the server has no registration endpoint, pass `--client-id` with a client registered at its authorization server.

Without `--no-browser`, the command exits with code `8` before sending anything when output isn't a terminal, or when a browser on this machine can't reach the callback. This covers CI, SSH, a container, or Linux without a display. It also exits with code `8` if the server neither asks for credentials nor publishes OAuth metadata. It exits with code `3` if the authorization server doesn't support PKCE with `S256`, an endpoint isn't HTTPS (HTTP is allowed only for `localhost` and `127.0.0.1`), or the sign-in is denied.

### Usage

```bash
postman mcp login (--url <url> | --request <path-or-id>) [options]
```

### Options

**`--url <url>`**

The MCP server's URL.

---

**`--request <path-or-id>`**

A saved local-mode HTTP MCP request, as a `.request.yaml` path or the ID of an MCP request under `postman/collections/`. Use `-e` and `--env-var` to resolve its `{{variables}}`.

---

**`--scope <scopes>`**

The space-separated scopes to request. By default, the command requests the scope that the server's challenge names, or every scope in its metadata.

---

**`--client-id <id>`**

Uses a client registered at the authorization server instead of registering one. Required when the server has no registration endpoint. If you sign in again without it, the command reuses the stored client and its callback port.

---

**`--client-secret <secret>`**

The secret of the `--client-id` client, if it has one. Requires the `--client-id` option. Passing `--client-secret` without `--client-id` is a usage error that exits with code `2`.

---

**`--callback-port <port>`**

Listens for the sign-in on this port of `127.0.0.1`, to match a registered redirect URI of `http://127.0.0.1:<port>/callback`. By default, the command uses a free port. A value outside 1-65535 is a usage error that exits with code `2`.

---

**`--no-browser`**

Prints the sign-in link to standard error instead of opening a browser. In a terminal, you can also paste the URL that the browser ended on, so you can sign in on another machine. The pasted URL isn't shown, and it must carry this sign-in's `state` and a code. Whichever arrives first, the pasted URL or the browser reaching this machine, finishes the sign-in.

---

**`-H, --header <key:value>`**

Adds an HTTP header to the sign-in's first request to the server. Repeat the option for more than one. The header is never sent with an `Authorization` header, and metadata, registration, and token requests don't get it.

---

**`-k, --insecure`**

Skips TLS certificate verification for every sign-in request.

---

**`--timeout-request <ms>`** — default: 60000

Sets the time limit for each request. Use `0` for no limit.

---

**`-e, --environment <path>`**

Resolves `{{variables}}` from a local environment file.

---

**`--env-var <key=value>`**

Sets a variable for `{{variable}}` resolution. Repeat the option for more than one.

---

**`--json`**

Prints what the command stored as JSON, without tokens.

---

**`--debug`**

Prints each OAuth request's method, URL without its query, and status to standard error.

---

### Examples

```bash
postman mcp login --url https://example.com/mcp

postman mcp login --url https://example.com/mcp --no-browser

postman mcp login --url https://example.com/mcp --client-id my-client --callback-port 8765
```

### Credential storage

The command stores sign-ins in `mcp-credentials.json` in the Postman home directory (`~/.postman`), one entry for each server. The file holds the access and refresh tokens, the client registration, and any `--client-secret` in plaintext. On macOS and Linux, the file is readable only by you. On Windows, it inherits the access permissions of your user profile. Any process that runs as you can read it. The CLI never prints, logs, or sends tokens, secrets, or codes in telemetry.

To change where sign-ins are kept, set the `POSTMAN_MCP_CREDENTIALS_STORE` environment variable:

* `file` stores sign-ins in `~/.postman/mcp-credentials.json`. This is the default.
* `none` keeps them in memory only, so `login` only checks that you can sign in, and the token is lost when the command ends.

Any other value exits with code `2`. A STDIO target has no sign-in, so it ignores the variable.

## `postman mcp logout`

Removes the stored sign-in for an MCP server from this machine, then revokes its refresh token and its access token at the authorization server. A failed revocation prints a warning to standard error and doesn't change the exit code. The command exits with code `0` when nothing was stored.

### Usage

```bash
postman mcp logout (--url <url> | --request <path-or-id> | --all) [options]
```

### Options

**`--url <url>`**

The MCP server's URL.

---

**`--request <path-or-id>`**

A saved local-mode MCP request, as a `.request.yaml` path or the ID of an MCP request under `postman/collections/`. Use `-e` and `--env-var` to resolve its `{{variables}}`.

---

**`--all`**

Removes every stored sign-in. In a terminal, the command asks first. If you answer no or press **Ctrl+C**, it exits with code `5`. Can't be combined with `--url` or `--request`. Passing both is a usage error that exits with code `2`.

---

**`-y, --yes`**

Skips the confirmation for `--all`. Required when there's no terminal, or the command exits with code `8`. Passing it without `--all` is a usage error that exits with code `2`.

---

**`--no-revoke`**

Removes the sign-in from this machine without revoking it.

---

**`-k, --insecure`**

Skips TLS certificate verification for the revocation.

---

**`--timeout-request <ms>`** — default: 60000

Sets the time limit for each revocation request. Use `0` for no limit.

---

**`-e, --environment <path>`**

Resolves `{{variables}}` from a local environment file.

---

**`--env-var <key=value>`**

Sets a variable for `{{variable}}` resolution. Repeat the option for more than one.

---

**`--json`**

Prints the result as JSON.

---

**`--debug`**

Prints each revocation request's method, URL without its query, and status to standard error.

---

With `POSTMAN_MCP_CREDENTIALS_STORE=none`, the command still removes and revokes a sign-in that an earlier run stored. It never adds to the file.

### Examples

```bash
postman mcp logout --url https://example.com/mcp

postman mcp logout --all --yes
```

## `postman mcp credentials`

Lists the sign-ins that `postman mcp login` stored. For each server, it shows the issuer, whether the client was registered dynamically or ahead of time, the scopes, when the access token expires, and whether it refreshes. It reads only the credentials file, sends nothing, and never shows a token or secret.

### Usage

```bash
postman mcp credentials [options]
```

### Options

**`--json`**

Prints the sign-ins as JSON.

---

With `POSTMAN_MCP_CREDENTIALS_STORE=none`, the command doesn't read the file, and its output says storage is off.

### Example

```bash
postman mcp credentials
```

## Scripts on a saved MCP request

A `--request` target's [scripts](/latest-v-12/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](/latest-v-12/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, or a bad option value. This also covers `--login` with `--no-login` or a STDIO target, an invalid `POSTMAN_MCP_LOGIN` or `POSTMAN_MCP_CREDENTIALS_STORE` 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. Also returned when a stored sign-in expired and can't be refreshed, you answer no to the sign-in question, or `login` can't sign in.                                                                                                                                             |
| `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**, including at the sign-in question.                                                                                                                                                                                                                                                                                             |
| `8`  | Refused, and nothing was started. This is a STDIO target without `--allow-stdio`, or a `login` or `--login` that can't open a browser here. It's also a `login` to a server that doesn't ask for credentials, a stored sign-in the request would send to a different server, or `logout --all` without a terminal or `--yes`.                            |

## See also

* [Postman CLI collection commands](/latest-v-12/docs/postman-cli/postman-cli-collections)
* [Set up the Postman MCP Server](/docs/developer/postman-api/postman-mcp-server/set-up-postman-mcp-server/)