·

Postman MCP With Cursor

Set up Postman MCP in Cursor so your AI agent can run and manage API collections and test suites right from your editor.

Cursor's Agent mode is well suited to keeping API tests honest against the implementation, because the agent has your controller, route, and DTO files open in the same context window where it's editing the Postman collection. This topic covers connecting Postman MCP to Cursor, the workflow for keeping collections synced with backend code as it changes, debugging a failing test against the real implementation, and the rough edges specific to running Postman MCP inside Cursor.

Connecting Postman MCP to Cursor Agent Mode

Cursor reads MCP configuration from .cursor/mcp.json (project-scoped, the one worth checking in with a secret-input pattern) or ~/.cursor/mcp.json (global, for a Postman workspace you use across every project):

{
  "mcpServers": {
    "postman": {
      "command": "npx",
      "args": ["-y", "@postman/postman-mcp-server", "--full"],
      "env": {
        "POSTMAN_API_KEY": "${env:POSTMAN_API_KEY}"
      }
    }
  }
}

Open Cursor Settings → MCP to confirm the server shows as connected with a green status and a nonzero tool count. From there, enable Agent mode (not Ask mode — Ask mode won't execute MCP tool calls) and give it a low-stakes first task in the same spirit as the other clients: "list the collections in my default Postman workspace" before anything that writes.

Cursor's .cursor/rules/ project rules are worth using here specifically to keep the agent from touching the wrong Postman workspace when a repo's contributors share a Cursor global config across multiple client projects:

---
description: Postman MCP workspace scope for this repo
alwaysApply: true
---

This repo's Postman workspace ID is 8b4e6a10-2c3d-4f5e-9a1b-7c8d9e0f1a2b.
Always pass this workspace ID explicitly on Postman MCP tool calls that
accept one. Never call workspace-list or attempt to operate against a
different workspace without explicit confirmation.

Tips
- Confirm Agent mode is active, not Ask mode — a surprising number of "Postman MCP isn't doing anything" reports trace back to running the prompt in Ask mode, which reads tool definitions but won't execute them.
- Use a .cursor/rules/*.mdc file to pin the Postman workspace ID per repo — this matters more in Cursor than single-project CLIs, since a global ~/.cursor/mcp.json often serves several unrelated client codebases.
- ${env:POSTMAN_API_KEY} keeps the literal key out of .cursor/mcp.json; export it in your shell profile so every new Cursor window inherits it without a fresh prompt.

Keeping Collections in Sync with Controller and Route Code

The single most useful Cursor-specific pattern is asking the agent to reconcile a collection against the actual route/controller files in the same prompt, rather than treating "update the Postman collection" and "look at the API code" as separate steps:

Open src/routes/orders.routes.ts and src/controllers/orders.controller.ts.
Compare the routes and their request/response shapes against the
"Orders API — v2" Postman collection. Report any of:
- Routes that exist in code but have no corresponding Postman request
- Postman requests for routes that no longer exist in code
- Request/response field mismatches between the DTO types and the
  collection's example bodies or test assertions

Don't change anything yet — just report the diff.

That "don't change anything yet" instruction matters. A drift report you review before applying is far more useful than an agent silently rewriting assertions to match code that might itself have introduced a bug — the whole point of the exercise is catching cases where the code changed in a way the tests should have caught, not rubber-stamping whatever the code currently does.

Drift report — Orders API v2:

1. Route exists, no Postman request: PATCH /orders/:id/cancel
   (added in commit a3f21c, no test coverage yet)

2. Collection/DTO mismatch: "Create order" request's example body
   uses "customerId" (camelCase); OrderCreateDto now expects
   "customer_id" (snake_case) as of commit 9b41e2 — collection was
   not updated when the DTO changed.

3. Postman request for a route that no longer exists:
   "Legacy: Get order status" (GET /orders/:id/status) — route
   removed in commit 5f8a90, appears to have been consolidated into
   GET /orders/:id.

Once you've reviewed the report, apply the fixes in a follow-up turn, one category at a time — updating case-mismatched fields, adding the missing PATCH /orders/:id/cancel request, and removing the dead one — rather than one giant "fix everything" prompt that makes the resulting diff harder to review.

// Updated to match the snake_case DTO change from commit 9b41e2
pm.test("Order created with valid id", function () {
    pm.response.to.have.status(201);
    const body = pm.response.json();
    pm.expect(body.id).to.be.a("string");
});

// request body updated: { "customer_id": "{{customerId}}", ... }

Tips
- Run drift checks as "report only" first, always — reviewing a diff before it's applied catches the case where the code change was itself the bug, not the test.
- Point the agent at the specific route and controller files by path rather than "check if the API changed" — a targeted file list produces a more complete diff than an open-ended search of the codebase.
- Apply fixes in reviewable batches by category (renamed fields, new routes, dead routes) rather than one sweeping edit — it keeps the resulting collection diff legible in code review.

Debugging Failing API Tests Against the Implementation in Cursor

Cursor's advantage over a terminal-only client shows up clearest here: when a pm.test assertion fails, the agent can read the controller, the service layer, and the database model in the same turn where it reads the failing assertion, and reason about which layer actually introduced the bug.

The "Order total matches sum of line items" test is failing:
expected 4000, actual 4200 (see attached newman output). Trace this
through src/controllers/orders.controller.ts and
src/services/orders.service.ts and tell me where the total is
computed incorrectly, or whether the test's expectation is wrong.

newman output:
  ✗  Order total matches sum of line items
     AssertionError: expected 4200 to deeply equal 4000
     Request body: { items: [{ sku: "SKU-1001", qty: 2, unitPriceCents: 2000 }] }

A realistic trace back from the agent, having read both files:

orders.service.ts:47 — calculateTotal() sums item.qty * item.unitPriceCents,
then applies a flat 200-cent shipping fee unconditionally:

    const subtotal = items.reduce((s, i) => s + i.qty * i.unitPriceCents, 0);
    return subtotal + SHIPPING_FEE_CENTS; // 200

This is correct behavior — shipping fee is documented in the pricing
spec. The test's expectation (4000) doesn't account for it; actual
(4200) is right. The test assertion needs updating to include the
shipping fee, not the implementation.

That's the useful outcome of debugging with implementation access in the loop: the agent doesn't just report a mismatch, it identifies which side — test or code — is actually wrong, with a citation to the specific line and the documented rule backing its conclusion. Without controller access, the same session would only be able to report "these two numbers disagree" and leave the judgment call to you.

// Corrected to account for documented flat shipping fee (orders.service.ts:47)
pm.test("Order total matches sum of line items plus shipping", function () {
    const req = JSON.parse(pm.request.body.raw);
    const body = pm.response.json();
    const SHIPPING_FEE_CENTS = 200;
    const expectedTotal = req.items.reduce(
        (sum, item) => sum + item.qty * item.unitPriceCents, 0
    ) + SHIPPING_FEE_CENTS;
    pm.expect(body.totalCents).to.eql(expectedTotal);
});

Tips
- Always ask the agent to state a conclusion — "the test is wrong" or "the code is wrong" — with a citation to the specific line and rule, not just "these don't match." A bare mismatch report pushes the judgment call back onto you with no more information than the newman output already gave you.
- Paste the actual newman failure output into the debugging prompt rather than paraphrasing it — the exact actual/expected values and request body are what let the agent trace the real computation instead of guessing.
- When a test assertion turns out to be wrong (as in the shipping fee example), fix the assertion's comment to cite the rule and its source line — the next person hitting this test six months from now shouldn't have to re-derive the reasoning.

Known Limitations and Workarounds for Postman MCP in Cursor

Large collections slow down Agent mode's context loading. A collection with 150+ requests, fetched in full via get-collection, consumes a large chunk of context before the agent has done anything — noticeably worse than the same collection in a client with a leaner default tool response. Workaround: ask the agent to fetch only the specific folder or request it needs (most tool sets support scoping by folder), rather than the whole collection, for any task that doesn't genuinely need the full tree.

Don't fetch the full "Orders API — v2" collection. Just get the
"Orders" folder's requests — that's all this task needs.

Agent mode occasionally re-fetches state it already has. In longer sessions, Cursor's agent sometimes re-calls get-collection or get-environment mid-task even when nothing has changed since the last fetch, burning both tool-call budget and context. This is a general agent-loop behavior, not Postman-MCP-specific, but it's more noticeable with a data-heavy tool like a large collection fetch than with a small one. Explicitly telling it "you already have the current state from earlier in this session, don't re-fetch unless you've made a change" measurably reduces it.

No first-class diff view for MCP-driven collection edits. Unlike a code file edit, which Cursor shows as an inline diff you approve or reject, a Postman MCP tool call that updates a collection just... happens, with only the tool call's JSON args as your record of what changed. For anything you want reviewable the way code changes are, keep the collection exported to a JSON file under version control (File 6 covers this) and rely on git diff for the real review, treating the live Postman workspace as the runtime target rather than the source of truth.

Auth token refresh isn't automatic. If your API uses short-lived bearer tokens, the authToken environment variable Cursor's agent reads may be stale by the time it runs a test, producing a 401 that looks like a real bug but is a test-setup problem. Worth a standing check before deep debugging: "confirm the environment's authToken hasn't expired before investigating further."

Tips
- Scope collection fetches to the specific folder or request a task needs; avoid pulling a 150-request collection into context for a one-request task.
- Explicitly tell long-running agent sessions not to re-fetch state they already have — a small prompt addition that noticeably reduces redundant tool calls.
- Keep the collection's JSON export under version control as the reviewable record of change; treat the live Postman workspace as the execution target, not the audit trail.
- Rule out a stale auth token first when a previously-passing test suddenly 401s — it's a common false-positive that looks like a regression but isn't.

Next Real World Workflow API Regression Suite From Spec To CI