@postman/postman-mcp-server 2.8.2 → 2.8.3-beta.2

package/README.md

@@ -283,7 +283,7 @@ This configuration uses the remote server (`https://mcp.postman.com`), which aut
 
 ### Install in Antigravity
 
-To install the MCP server in Antigravity, click **Manage MCP servers > View raw config**. Then, copy the following JSON config into the `.codeium/windsurf/mcp_config.json` file.
+To install the MCP server in Antigravity, click **Manage MCP servers > View raw config**. Then, copy the following JSON config into the `mcp_config.json` file.
 
 This configuration uses the remote server (`https://mcp.postman.com`), which authenticates automatically with OAuth.
 

package/dist/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@postman/postman-mcp-server",
-    "version": "2.8.2",
+    "version": "2.8.3-beta.2",
     "description": "A simple MCP server to operate on the Postman API",
     "mcpName": "com.postman/postman-mcp-server",
     "main": "dist/src/index.js",

package/dist/src/index.js

@@ -2,7 +2,7 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { ErrorCode, isInitializeRequest, McpError, } from '@modelcontextprotocol/sdk/types.js';
-import { readdir } from 'node:fs/promises';
+import { readdir, readFile } from 'node:fs/promises';
 import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import dotenv from 'dotenv';
@@ -131,7 +131,24 @@ async function run() {
     const minimalTools = allGeneratedTools.filter((t) => enabledResources.minimal.includes(t.method));
     const codeTools = allGeneratedTools.filter((t) => enabledResources.code.includes(t.method));
     const tools = useCode ? codeTools : useFull ? fullTools : minimalTools;
-    const server = new McpServer({ name: SERVER_NAME, version: APP_VERSION });
+    const __filename = fileURLToPath(import.meta.url);
+    const __dirname = dirname(__filename);
+    let instructionsContent;
+    try {
+        const resourcesDir = join(__dirname, './resources');
+        instructionsContent = await readFile(join(resourcesDir, 'Instructions.md'), 'utf-8');
+        log('info', 'Loaded Instructions.md resource');
+    }
+    catch (error) {
+        log('warn', 'Failed to load Instructions.md resource', {
+            error: String(error?.message || error),
+        });
+    }
+    const server = new McpServer({ name: SERVER_NAME, version: APP_VERSION }, instructionsContent
+        ? {
+            instructions: 'Read the instructions resource completely for detailed usage instructions before answering any API-related questions.',
+        }
+        : {});
     server.onerror = (error) => {
         const msg = String(error?.message || error);
         logBoth(server, 'error', `MCP server error: ${msg}`, { error: msg });
@@ -145,8 +162,6 @@ async function run() {
         serverType: useCode ? 'code' : useFull ? 'full' : 'minimal',
         availableTools: tools.map((t) => t.method),
     };
-    const __filename = fileURLToPath(import.meta.url);
-    const __dirname = dirname(__filename);
     const viewsDir = join(__dirname, './views');
     const renderTemplate = createTemplateRenderer(viewsDir);
     const errorsDir = join(__dirname, './views/errors');
@@ -218,6 +233,12 @@ async function run() {
             }
         });
     }
+    if (instructionsContent) {
+        server.registerResource('instructions', 'postman://instructions', { description: 'Instructions for using the Postman MCP server', mimeType: 'text/markdown' }, async (uri) => ({
+            contents: [{ uri: uri.href, mimeType: 'text/markdown', text: instructionsContent }],
+        }));
+        log('info', 'Registered resource: instructions');
+    }
     log('info', 'Starting stdio transport');
     const transport = new StdioServerTransport();
     transport.onmessage = (message) => {

package/dist/src/resources/Instructions.md

@@ -0,0 +1,114 @@
+# Postman MCP Server — Instructions
+
+## What is Postman?
+
+Postman is a comprehensive API platform used by developers and teams to design, build, test, document, and share APIs. It provides tools for making HTTP requests, organizing API endpoints into collections, managing environments and variables, creating mock servers, setting up monitors, and publishing API documentation.
+
+## What is this MCP server?
+
+This is a Model Context Protocol (MCP) server that exposes Postman's API as a set of tools you can invoke. It lets you interact with your Postman workspace programmatically — managing collections, environments, APIs, mocks, monitors, and more — all through structured tool calls.
+
+## Postman elements
+
+Postman organises API work around a set of core elements. Understanding these is key to using the MCP server effectively.
+
+- **Workspace** — A shared space that groups related collections, environments, APIs, mocks, and monitors. Every element belongs to a workspace. Workspaces can be personal, team, partner, or public.
+- **Collection** — An ordered set of API requests grouped into folders. Collections are the primary unit for organising, documenting, testing, and running API calls. Each collection can contain folders, requests, responses (saved examples), pre-request scripts, and tests.
+- **Folder** — A logical grouping of requests inside a collection. Folders can be nested to create a hierarchy (e.g. by resource or feature).
+- **Request** — A single API call definition inside a collection. It includes the HTTP method, URL, headers, query parameters, body, authorization settings, and optional pre-request/test scripts.
+- **Response (saved example)** — A snapshot of a request/response pair saved inside a request. Saved examples are used by mock servers to return realistic responses and serve as inline documentation.
+- **Environment** — A set of key-value variables scoped to a particular context (e.g. development, staging, production). Variables can be of type `default` or `secret`. Environments are applied to requests at runtime so you can switch contexts without editing URLs or headers.
+- **API (Spec)** — A versioned API definition (OpenAPI, GraphQL SDL, etc.) managed inside Postman. An API can be linked to collections, environments, mocks, monitors, and documentation.
+- **Mock server** — A simulated endpoint that returns responses based on the saved examples in a collection. Useful for front-end development and testing before the real API is ready.
+- **Monitor** — A scheduled runner that executes a collection on a set interval and reports results. Monitors are used for uptime checks, integration tests, and alerting.
+- **Tags** — Labels attached to collections or workspaces for categorisation and search. Tags make it easier to find related elements across the organisation.
+
+## Private API Network
+The Private API Network is an organisation-wide catalogue of approved APIs, collections, and workspaces. Teams publish elements to the Private API Network so others can discover and reuse them.
+
+## Public API Network (Postman API Network)
+The Public API Network is a collection of APIs and collections published by Postman and third-party developers. It's a public repository of APIs and collections that anyone can use.
+
+## Finding APIs
+
+These instructions apply any time the user wants to find, discover, or locate an API — whether internal or public.
+
+**Do NOT rely on your own knowledge of available tools or APIs to answer questions like "is there an API for X?" or "find me an API that does Y."**
+ Always search first using this workflow
+
+**Follow the search workflow whenever the user:**
+ - Asks to **find**, **discover**, **locate**, or **look up** an API
+ - Asks **"is there an API for..."** or **"can I do X via an API?"**
+ - Asks about capabilities that may or may not exist
+ - Is unsure what API to use for a task
+
+> **Anti-pattern to avoid:**
+> User asks "Is there a bulk API for workspaces?" → You scan the tool list, don't see one, and say "No such API exists."
+> Correct behavior: Follow the search workflow below, search the network, and only then draw conclusions.
+
+---
+
+### Decision Framework: Private vs Public Network
+
+**Default to the Private API Network** for most requests. Only use the Public API Network when the user explicitly signals public discovery intent.
+
+#### Use `searchPostmanElementsInPrivateNetwork` (Default) When:
+
+- The user asks to "find an API", "search for a service", or "look up an endpoint" without specifying public
+- The user mentions internal services (e.g., "find the notification service", "search for our payment API", "look up the auth microservice")
+- The user wants to integrate with a team or company API
+- The user says "find a trusted API for X" or "what APIs do we have for Y"
+- The user references internal infrastructure, microservices, or team-shared resources
+- The request is ambiguous — **always prefer Private Network first**
+
+#### Use `searchPostmanElementsInPublicNetwork` ONLY When:
+
+- The user explicitly mentions a well-known public API by name (e.g., "find the Stripe API", "search for the GitHub API", "look up Twilio")
+- The user explicitly says "public API", "public network", or "Postman public network"
+- The user wants to explore third-party or open-source APIs (e.g., "find an open source weather API")
+- The context makes it unambiguous that the user is looking for an external, publicly available API
+
+**When in doubt, search the Private API Network first.** If no relevant results are found, then try the Public API Network and let the user know you're expanding the search.
+
+---
+
+### Search Workflow
+
+#### Step 1: Determine Search Target
+
+Based on the user's request, decide which network to search using the decision framework above.
+
+#### Step 2: Execute the Search
+
+**For Private API Network (default):**
+
+`searchPostmanElementsInPrivateNetwork(q, entityType)`
+- Use `entityType: "collections"` to find API collections (recommended starting point)
+- Use `entityType: "requests"` to find specific API requests
+- Craft a concise, relevant search query from the user's intent (e.g., "notification", "payment", "authentication")
+
+**For Public API Network:**
+
+`searchPostmanElementsInPublicNetwork(q, entityType)`
+- Use `entityType: "collections"` to find API collections (recommended starting point)
+- Use `entityType: "requests"` to find specific API requests
+- Use the API name or domain as the query (e.g., "stripe", "github", "twilio")
+
+#### Step 3: Present Results
+
+- Summarize the search results clearly to the user
+- Highlight the most relevant matches based on the user's intent
+- If multiple results are found, briefly describe each and ask the user which one to explore
+- If no results are found in the Private Network, suggest searching the Public Network
+
+#### Step 4: Explore the Selected API
+
+Once the user selects a collection:
+
+1. `getCollection(collectionId)` — Fetch collection details with the recursive itemRefs index
+2. `getCollectionRequest(requestId, collectionId, uid: true, populate: false)` — Explore individual requests
+3. `getCollectionFolder(folderId, collectionId, uid: true, populate: false)` — Explore folders
+
+**IMPORTANT:** After establishing a collection, do NOT call `searchPostmanElementsInPublicNetwork` or `searchPostmanElementsInPrivateNetwork` again to find requests within it. Use `getCollectionRequest` and `getCollectionFolder` to navigate the collection's contents.
+
+- **Never conclude that an API doesn't exist based solely on the MCP tool list.** The tool list covers tools for *using* Postman, not the full universe of APIs your organization may have published. Always search before concluding.

package/dist/src/tools/createCollection.js

@@ -9,7 +9,7 @@ export const parameters = z.object({
         .object({
         info: z
             .object({
-            name: z.string().describe("The collection's name."),
+            name: z.string().min(1).describe("The collection's name. Must not be empty."),
             description: z.string().describe("The collection's description.").optional(),
             schema: z
                 .literal('https://schema.getpostman.com/json/collection/v2.1.0/collection.json')

package/dist/src/tools/createCollectionRequest.js

@@ -15,7 +15,7 @@ export const parameters = z.object({
         .optional(),
     description: z.string().nullable().describe("The request's description.").optional(),
     method: z
-        .enum([
+        .preprocess((v) => (typeof v === 'string' ? v.toUpperCase() : v), z.enum([
         'GET',
         'PUT',
         'POST',
@@ -31,7 +31,7 @@ export const parameters = z.object({
         'UNLOCK',
         'PROPFIND',
         'VIEW',
-    ])
+    ]))
         .describe("The request's HTTP method.")
         .optional(),
     url: z.string().nullable().describe("The request's URL.").optional(),

package/dist/src/tools/createCollectionResponse.js

@@ -13,7 +13,7 @@ export const parameters = z.object({
     description: z.string().nullable().describe("The response's description.").optional(),
     url: z.string().nullable().describe("The associated request's URL.").optional(),
     method: z
-        .enum([
+        .preprocess((v) => (typeof v === 'string' ? v.toUpperCase() : v), z.enum([
         'GET',
         'PUT',
         'POST',
@@ -29,7 +29,7 @@ export const parameters = z.object({
         'UNLOCK',
         'PROPFIND',
         'VIEW',
-    ])
+    ]))
         .describe("The request's HTTP method.")
         .optional(),
     headers: z

package/dist/src/tools/createSpec.js

@@ -7,7 +7,7 @@ export const parameters = z.object({
     workspaceId: z.string().describe("The workspace's ID."),
     name: z.string().describe("The specification's name."),
     type: z
-        .enum([
+        .preprocess((v) => (typeof v === 'string' ? v.toUpperCase() : v), z.enum([
         'OPENAPI:2.0',
         'OPENAPI:3.0',
         'OPENAPI:3.1',
@@ -15,7 +15,7 @@ export const parameters = z.object({
         'PROTOBUF:2',
         'PROTOBUF:3',
         'GRAPHQL',
-    ])
+    ]))
         .describe("The specification's type."),
     files: z
         .array(z.union([
@@ -25,7 +25,7 @@ export const parameters = z.object({
                 .describe("The file's path. Accepts .json, .yaml, .proto and .graphql file types."),
             content: z.string().describe("The file's stringified contents."),
             type: z
-                .enum(['DEFAULT', 'ROOT'])
+                .preprocess((v) => (typeof v === 'string' ? v.toUpperCase() : v), z.enum(['DEFAULT', 'ROOT']))
                 .describe('The type of file. This property is required when creating multi-file specifications:\n- `ROOT` — The file containing the full OpenAPI structure. This serves as the entry point for the API spec and references other (`DEFAULT`) spec files. Multi-file specs can only have one root file.\n- `DEFAULT` — A file referenced by the `ROOT` file.\n'),
         }),
         z.object({

package/dist/src/tools/generateCollection.js

@@ -19,8 +19,8 @@ export const parameters = z.object({
             .default('Space'),
         parametersResolution: z
             .string()
-            .describe('Generated collections use examples for parameter generation by default. Any existing collections generated using the schema parameter generation will continue to sync using their existing strategy.')
-            .default('Schema'),
+            .describe('Determines how parameter values are generated in the collection. Must be set to "Example" — the "Schema" value is no longer supported by the Postman API and will result in an error. Always use "Example" to generate parameters from example values in the spec.')
+            .default('Example'),
         folderStrategy: z
             .enum(['Paths', 'Tags'])
             .describe("Whether to create folders based on the specification's `paths` or `tags` properties.")
@@ -50,8 +50,7 @@ export const parameters = z.object({
             .describe("If true, creates subfolders in the generated collection based on the order of the endpoints' tags.")
             .default(false),
     })
-        .describe("The advanced creation options and their values. For more details, see Postman's [OpenAPI to Postman Collection Converter OPTIONS documentation](https://github.com/postmanlabs/openapi-to-postman/blob/develop/OPTIONS.md). These properties are case-sensitive.")
-        .default({ enableOptionalParameters: true, folderStrategy: 'Paths' }),
+        .describe("The advanced creation options and their values. For more details, see Postman's [OpenAPI to Postman Collection Converter OPTIONS documentation](https://github.com/postmanlabs/openapi-to-postman/blob/develop/OPTIONS.md). These properties are case-sensitive."),
 });
 export const annotations = {
     title: 'Creates a collection from the given API specification.',

package/dist/src/tools/generateSpecFromCollection.js

@@ -8,7 +8,9 @@ export const parameters = z.object({
     elementType: z.literal('spec').describe('The `spec` value.'),
     name: z.string().describe("The API specification's name."),
     type: z.literal('OPENAPI:3.0').describe("The specification's type."),
-    format: z.enum(['JSON', 'YAML']).describe('The format of the API specification.'),
+    format: z
+        .preprocess((v) => (typeof v === 'string' ? v.toUpperCase() : v), z.enum(['JSON', 'YAML']))
+        .describe('The format of the API specification.'),
 });
 export const annotations = {
     title: 'Generates an API specification for the given collection. The response contains a polling link to the task status.',

package/dist/src/tools/getTaggedEntities.js

@@ -1,7 +1,7 @@
 import { z } from 'zod';
 import { asMcpError, McpError } from './utils/toolHelpers.js';
 export const method = 'getTaggedEntities';
-export const description = 'Gets Postman elements (entities) by a given tag. Tags enable you to organize and search [workspaces](https://learning.postman.com/docs/collaborating-in-postman/using-workspaces/managing-workspaces/#tagging-a-workspace), [APIs](https://learning.postman.com/docs/designing-and-developing-your-api/managing-apis/#tagging-apis), and [collections](https://learning.postman.com/docs/collections/using-collections/#tagging-a-collection) that contain shared tags.\n\n**Note:**\n\nTagging is available on Postman [**Enterprise** plans](https://www.postman.com/pricing/).\n';
+export const description = '**Requires an Enterprise plan.** Tagging is only available on Postman Enterprise plans. This tool returns a 404 error on Free, Basic, and Professional accounts.\n\nGets Postman elements (entities) by a given tag. Tags enable you to organize and search workspaces, APIs, and collections that contain shared tags.\n';
 export const parameters = z.object({
     slug: z
         .string()
@@ -29,7 +29,7 @@ export const parameters = z.object({
         .optional(),
 });
 export const annotations = {
-    title: 'Gets Postman elements (entities) by a given tag. Tags enable you to organize and search [workspaces](https://learning.postman.com/docs/collaborating-in-postman/using-workspaces/managing-workspaces/#tagging-a-workspace), [APIs](https://learning.postman.com/docs/designing-and-developing-your-api/managing-apis/#tagging-apis), and [collections](https://learning.postman.com/docs/collections/using-collections/#tagging-a-collection) that contain shared tags.',
+    title: '**Requires an Enterprise plan.** Tagging is only available on Postman Enterprise plans. This tool returns a 404 error on Free, Basic, and Professional accounts.',
     readOnlyHint: true,
     destructiveHint: false,
     idempotentHint: true,

package/dist/src/tools/patchCollection.js

@@ -2,7 +2,7 @@ import { z } from 'zod';
 import { ContentType } from '../clients/postman.js';
 import { asMcpError, McpError } from './utils/toolHelpers.js';
 export const method = 'patchCollection';
-export const description = 'Updates specific collection information, such as its name, events, or its variables. For more information, see the [Postman Collection Format documentation](https://schema.postman.com/collection/json/v2.1.0/draft-07/docs/index.html).\n';
+export const description = 'Updates specific collection information, such as its name, events, or its variables. For more information, see the [Postman Collection Format documentation](https://schema.postman.com/collection/json/v2.1.0/draft-07/docs/index.html).\n\n**Important usage notes:**\n\n- **Sequential calls only.** Do NOT call \\`patchCollection\\` in parallel with other \\`patchCollection\\` calls for the same collection — concurrent PATCH requests conflict with each other and cause cancellation errors. Always wait for one call to complete before making another.\n- **Partial updates.** Only include the fields you want to change. Omit all other fields entirely; unspecified fields are left unchanged.\n- **Variables (\\`collection.variable\\`).** When updating variables, provide only the fields you intend to set on each variable object (\\`key\\`, \\`value\\`, \\`description\\`). Omit \\`id\\` and \\`disabled\\` unless you explicitly need to change them — including extra fields can cause validation errors.\n';
 export const parameters = z.object({
     collectionId: z
         .string()
@@ -32,7 +32,7 @@ export const parameters = z.object({
             disabled: z
                 .boolean()
                 .describe("If true, the variable is not enabled. Doesn't apply to path parameter variables.")
-                .default(false),
+                .optional(),
         })
             .describe('Information about the variable.'))
             .describe("A list of the collection's [variables](https://learning.postman.com/docs/sending-requests/variables/variables/). Make certain not to include sensitive information in variables.")

package/dist/src/tools/updateCollectionRequest.js

@@ -9,7 +9,7 @@ export const parameters = z.object({
     name: z.string().describe("The request's name.").optional(),
     description: z.string().nullable().describe("The request's description.").optional(),
     method: z
-        .enum([
+        .preprocess((v) => (typeof v === 'string' ? v.toUpperCase() : v), z.enum([
         'GET',
         'PUT',
         'POST',
@@ -25,7 +25,7 @@ export const parameters = z.object({
         'UNLOCK',
         'PROPFIND',
         'VIEW',
-    ])
+    ]))
         .describe("The request's HTTP method.")
         .optional(),
     url: z.string().nullable().describe("The request's URL.").optional(),

package/dist/src/tools/updateCollectionResponse.js

@@ -10,7 +10,7 @@ export const parameters = z.object({
     description: z.string().nullable().describe("The response's description.").optional(),
     url: z.string().nullable().describe("The associated request's URL.").optional(),
     method: z
-        .enum([
+        .preprocess((v) => (typeof v === 'string' ? v.toUpperCase() : v), z.enum([
         'GET',
         'PUT',
         'POST',
@@ -26,7 +26,7 @@ export const parameters = z.object({
         'UNLOCK',
         'PROPFIND',
         'VIEW',
-    ])
+    ]))
         .describe("The request's HTTP method.")
         .optional(),
     headers: z

package/dist/src/tools/updateSpecFile.js

@@ -8,7 +8,7 @@ export const parameters = z.object({
     filePath: z.string().describe('The path to the file.'),
     name: z.string().describe("The file's name.").optional(),
     type: z
-        .enum(['DEFAULT', 'ROOT'])
+        .preprocess((v) => (typeof v === 'string' ? v.toUpperCase() : v), z.enum(['DEFAULT', 'ROOT']))
         .describe('The type of file:\n- `ROOT` — The file containing the full OpenAPI structure. This serves as the entry point for the API spec and references other (`DEFAULT`) spec files. Multi-file specs can only have one root file.\n- `DEFAULT` — A file referenced by the `ROOT` file.\n')
         .optional(),
     content: z.string().describe("The specification's stringified contents.").optional(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@postman/postman-mcp-server",
-  "version": "2.8.2",
+  "version": "2.8.3-beta.2",
   "description": "A simple MCP server to operate on the Postman API",
   "mcpName": "com.postman/postman-mcp-server",
   "main": "dist/src/index.js",