Skip to navigation

Postman CLI MCP commands (postman mcp)

View as Markdown

This topic covers Model Context Protocol (MCP) commands for the Postman CLI. 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 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.

Options

The postman mcp inspect, tools, resources, and prompts commands each need a target MCP server to connect to, and accept any of the options that apply to those commands, 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:

postman mcp tools list --allow-stdio -- node ../server/index.js --transport stdio

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

--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>
Defaults to 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. Then every postman mcp command that connects to that server sends the stored sign-in:

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:

! 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 and common options.

Usage

postman mcp inspect --url <url>

Examples

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 and common options.

Usage

postman mcp tools list --url <url>

Examples

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

postman mcp tools call <tool> --url <url>
<tool>
Required

The name of the tool to call.

Options

Accepts any target options and 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

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 and common options.

Usage

postman mcp resources list --url <url>

Examples

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 and common options.

Usage

postman mcp resources templates list --url <url>

Example

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 and common options.

Usage

postman mcp resources read <uri> --url <url>
<uri>
Required

The URI of the resource to read.

Example

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 and common options.

Usage

postman mcp prompts list --url <url>

Example

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

postman mcp prompts get <name> --url <url>
<name>
Required

The name of the prompt to get.

Options

Accepts any target options and 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

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

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>
Defaults to 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

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

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>
Defaults to 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

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

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

postman mcp credentials

Scripts on a saved MCP request

A --request target’s scripts, and its collection’s and folders’ MCP scripts such as mcp:beforeConnect, run the way they do in a collection run:

  • 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

CodeMeaning
0Success.
1Failure. 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.
2Usage 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.
3The 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.
4Partial result. inspect couldn’t list a capability the server advertises, or a list came back incomplete. The output is still printed.
5Canceled with Ctrl+C, including at the sign-in question.
8Refused, 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

⌂ 换网址