November 10, 2026
The email from Postman Secret Scanner arrives in the evening. A bearer token for patients-service sits in plain text in a saved request, inside a team workspace. You’re not at your desk, there’s no terminal in reach, and the token can read patient records.
I staged this incident on the Postman DevRel team, in a dedicated test workspace with a fake token, so I could run the whole response end to end. My coding agent, with the Postman plugin installed, handled every step, from finding the leak to leaving an audit trail, and I never opened the Postman app. What interested me most was which door the agent used at each step: the Postman CLI or the Postman MCP server. The answer changes several times in one incident, and the reason it changes is what this post is about.
How the Postman plugin picks a door
The Postman plugin gives coding agents a set of skills for mocking, testing, monitoring, and documenting APIs. It also ships two ways to reach Postman. The docs describe the routing in two sentences. The plugin “sends your agent’s requests to the Postman CLI whenever the Postman CLI can complete them.” It “falls back to the Postman MCP Server only for tasks the Postman CLI doesn’t support.”
In practice, that fallback covers two situations:
- The Postman CLI can’t run. The plugin’s setup skill only routes to the MCP server after an attempt to install the Postman CLI actually fails, for example in a hosted session that can’t install binaries.
- The Postman CLI can run, but it doesn’t have the command yet. Secret Scanner, audit logs, and collection roles all fall in this bucket in the versions I tested.
Install the plugin into every coding agent it detects on your machine:
The install docs list the supported agents and their minimum versions.
The plugin configures the hosted MCP server for you. Here’s the configuration it registers in Claude Code:
The /mcp path selects the server’s Full tool set, which includes the enterprise tools this incident needs. You authorize it once with OAuth: in Claude Code, run the /mcp slash command and select the Postman server. If you’d rather connect the server by hand, the MCP server setup guide covers the remote, local, and Docker options.
The alert, from my phone
When the alert came in, I was out with only my phone. No laptop, no terminal, only the Claude app. That rules out the Postman CLI, so the first round goes through the MCP server. I’d added the same remote server (https://mcp.postman.com/mcp) as a custom connector in Claude, so it was already there in the mobile app. I asked:
Prompt
Secret Scanner flagged a token in the devrel-blog-mcp-test workspace. Where does it appear, and who put it there?
The agent chained three MCP tools: detectedSecretsQueries to list the active findings in the workspace, getDetectedSecretsLocations to turn each finding into a place, and getTeamUser to turn the leakedBy user ID into a name. Here’s the answer it gave me:
Agent
Two active findings in devrel-blog-mcp-test, both from the same leak.
Where: the Authorization header of the Get patient request, in the Patients Service collection. It’s the only occurrence of each finding, and the request still exists.
Who: Anthony Viard saved the request with the token in it.
Why two findings: the scanner matched the same header twice, once on the Bearer prefix and once on the token’s JSON Web Token format. Both need to be resolved after the rotation, or the alert stays open.
I only have the obfuscated previews and SHA-256 hashes, not the token itself, so I can’t tell which service issued it. The request calls /api/patients/{{patient_id}}, so the patients-service credential is the one to rotate.
Every fact in that answer comes from the tool results. The scanner matched the JSON Web Token shape and the Bearer prefix separately, and the detection landed 39 seconds after I saved the collection. Neither finding carries the secret in full, only an obfuscated preview and a hash, which matters when the conversation runs through a model provider you don’t control. The name came back as mine, the expected result for a staged leak and the one I’d want to know first in a real one.
Under the hood, each location result is a short record. This is the one that answers “where” and “who”:
Nothing about this round needed a shell.
The blast radius, from the terminal
A leaked token can’t wait until morning, so I moved to my laptop as soon as I could. The chat had told me what leaked and where. Fixing it meant updating an environment and running tests, which is work the Postman CLI handles well. I opened Claude Code in the project folder linked to the workspace (postman workspace create records that link in .postman/resources.yaml), where the plugin finds the Postman CLI and uses it.
Before rotating anything, I wanted to know who else depends on this service:
Prompt
Before we rotate the patients-service token, what depends on patients-service and how does each consumer authenticate to it?
The agent reached for Postman Context Graph through the Postman CLI:
The answer came back in 29 seconds. Trimmed:
A count of 32 consumers is what makes a rotation scary. The graph also narrowed it down: the leaked token carries the patients.read scope, and erp-bridge-service is the consumer that authenticates with that exact scope. That’s the service whose configuration has to change in the same window as the rotation.
patients-service comes from healthcare-org-app, a simulated healthcare platform the DevRel team maintains and ingests into its Context Graph. The Context Graph CLI reference covers ask, status, and ingest. Each ask counts against your team’s Context Graph quota, so one precise question beats five vague ones.
The rotation, with one prompt
I issued a new token for patients-service on the service side. I didn’t paste it into the chat, a file, or an environment variable. Everything else, I handed to the agent in one prompt:
Prompt
I’ve issued a new patients-service token. Remove the hard-coded header from the Patients Service collection, store the new token as a vault secret for the Patients Service – shared environment (I’ll enter the value myself), prove the request works, and make the collection read-only for the team while we clean up. Don’t close the Secret Scanner findings until I confirm the old token is revoked.
The plugin’s skills turned that into six steps and picked a door for each one. One step needed me: the agent ran postman secret create, which opened a one-time form in my browser with a match code (fuzzy-orchid-42) so I could check it came from this command. I pasted the token there. Here’s the summary the agent gave me afterward:
Agent
Rotation done. Findings still open, waiting on you.
I read the collection’s roles before changing them and sent your Editor role along with the team’s Viewer role. That call replaces the whole role set, so leaving you out would have removed your access.
The “How” column is the plugin’s routing rule in action. The Postman CLI edits requests in local collection files, but this collection only lives in the cloud workspace, so the header change went through the MCP server. The secret, the variable link, and the run went through the Postman CLI because it has those commands and a shell was available. Collection roles have no Postman CLI command, so that step went back to the MCP server. I never told the agent which tool to use.
The vault step is the part I’d copy into any rotation. The token went from my clipboard into Postman Shared Vault without passing through the agent’s context, the chat transcript, my shell history, or a plain-text environment value. That last one matters more than it looks: Secret Scanner checks the shared values of variables, so storing the new token as a plain value would have risked a fresh alert. With the vault reference, the scanner found nothing new. The agent did every step except handling the secret itself.
The run’s assertions live in the collection, so the agent didn’t write them either. In my test workspace, Postman Echo stands in for patients-service and echoes back the headers it receives, so the test checks exactly what went out:
Against the real service, the check that matters most is that the old token gets a 401 Unauthorized and the new one gets a 200.
Close the alert
Once the old token was revoked on the service side, I told the agent:
Prompt
The old token is revoked. Close the findings.
The agent answered:
Agent
Both findings are marked Revoked.
- Bearer Token: Revoked
- JSON Web Token: Revoked
One of the two calls timed out on my side, so I read the findings back before retrying. Both already showed Revoked, so I didn’t send the change again.
That last paragraph is the behavior I want from an agent on any write. The MCP server’s updateDetectedSecretResolutions tool also tells agents never to mark a finding Revoked unless the key has actually been rotated, which is why I kept that step behind my own confirmation. Resolved findings drop out of Secret Scanner’s default results, so the agent checked them with a query that includes resolved findings.
The paper trail
Audit logs don’t record collection or environment edits. They record team administration events: API keys, members, roles, single sign-on (SSO), and the lifecycle of Secret Scanner findings. That makes them the right place to close an incident:
Prompt
Show me the audit trail for this incident.
The agent queried the audit logs and summarized them:
Agent
Secret Scanner events in devrel-blog-mcp-test, Oct 21 (UTC)
The two revoke entries carry the user agent postman-claude-code-plugin/2.0.1/postman-api-mcp-server/1.8.0 (toolset: full).
That user agent is my favorite detail in the whole incident. The audit trail records that the change came through the Postman plugin, through the MCP server, with the Full tool set. When someone asks in six weeks who closed this alert and how, the answer is in the log: me, through my agent.
Heads up: audit logs need an Admin or Super Admin role. Before I had admin access, the same request came back with “You do not have permissions to view team Audit logs.” The agent can only see what your account can see.
Try it yourself
You need a Postman Enterprise plan for Secret Scanner and audit logs. Scanning internal workspaces also needs the Advanced Security Administration add-on. Context Graph needs a team with ingested sources.
- Install the plugin with npx @postman/postman-plugin install.
- Create a team workspace for the test. Keep it team-visible, not public: in public workspaces, Secret Scanner replaces detected secrets automatically, which spoils the exercise.
- Tell your team admins first. A detection emails Team Admins and Workspace Admins.
- Paste a sample token into a saved request header, wait for the alert, then hand the incident to your agent and watch which door it picks at each step.
Then ask for something the Postman CLI doesn’t cover yet, such as reading your API Catalog or your audit logs, and see whether your agent switches to the MCP server on its own or needs a nudge.
What I like about this setup is that the routing rule is boring in the best way. The Postman CLI comes first because it’s cheaper and easier to script. The MCP server picks up what the Postman CLI can’t run or doesn’t have yet. During an incident, that means fewer decisions for me, and the agent picks the right tool without being asked.
Resources
- Postman plugin overview
- Install the Postman plugin
- Postman MCP server overview
- Set up the Postman MCP server
- Postman Secret Scanner overview
- About Postman Context Graph
- Context Graph commands in the Postman CLI
- Roles and permissions
- Workspace activity feed
- Audit logs
- postman-mcp-server on GitHub
- healthcare-org-app on GitHub
- Model Context Protocol
