Postman CLI MCP commands (postman mcp)
Postman CLI MCP commands (postman mcp)
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.
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.
Connects to a remote server over HTTP, using streamable HTTP and falling back to server-sent events (SSE).
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:
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.
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.
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.
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.
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.
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.
Allows the command to start a local process. Required for every STDIO target.
Checks that the target uses this transport.
Skips TLS certificate verification. Verification is on by default.
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.
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.
Resolves {{variables}} in the URL, headers, command, and arguments from a local environment file.
Sets a variable for {{variable}} resolution. Repeat the option for more than one. Overrides -e.
Prints one JSON document on standard output and nothing else.
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:
A command sends the first of these credentials that applies:
- An
Authorizationheader that you pass with-H. - The saved request’s own authentication, when you pass
--request. - Authentication that the request inherits from its folder, then its collection.
- The sign-in that
postman mcp loginstored for the server. - 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:
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
Examples
postman mcp tools list
Lists the tools the MCP server offers, following every page of results.
Accepts any target options and common options.
Usage
Examples
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
The name of the tool to call.
Options
Accepts any target options and common options, in addition to the options below.
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.
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 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
Examples
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
Example
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
The URI of the resource to read.
Example
postman mcp prompts list
Lists the prompts the MCP server offers.
Accepts any target options and common options.
Usage
Example
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
The name of the prompt to get.
Options
Accepts any target options and common options, in addition to the options below.
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.
Sets one argument. Repeat the option for more than one. Can’t be combined with --args.
Example
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
Options
The MCP server’s URL.
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}}.
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.
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.
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.
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.
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.
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.
Skips TLS certificate verification for every sign-in request.
Sets the time limit for each request. Use 0 for no limit.
Resolves {{variables}} from a local environment file.
Sets a variable for {{variable}} resolution. Repeat the option for more than one.
Prints what the command stored as JSON, without tokens.
Prints each OAuth request’s method, URL without its query, and status to standard error.
Examples
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:
filestores sign-ins in~/.postman/mcp-credentials.json. This is the default.nonekeeps them in memory only, sologinonly 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
Options
The MCP server’s URL.
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}}.
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.
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.
Removes the sign-in from this machine without revoking it.
Skips TLS certificate verification for the revocation.
Sets the time limit for each revocation request. Use 0 for no limit.
Resolves {{variables}} from a local environment file.
Sets a variable for {{variable}} resolution. Repeat the option for more than one.
Prints the result as JSON.
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 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
Options
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
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:
beforeConnectruns before the session opens.afterConnectruns on the session’s first discovery, which is straight after connecting when the request has one.afterResponseruns aftertools call,prompts get, andresources read.afterDisconnectruns 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.