Tips and best practices for using the Postman MCP server

With the Postman MCP server, you empower AI agents to manage your Postman resources over structured tool calls. You can request complex workflows and API interactions, and let the AI take care of the heavy lifting. This document covers some useful tips for working with agents and prompts you can use to get started with the Postman MCP server.

For coding agents that work directly in a repository, the Postman CLI and its installed agent skills are the primary way to build, test, and maintain APIs with Postman. The tips on this page apply when you specifically want an agent to use the MCP server, such as in a chat-based or IDE context.

Tips and best practices

AI agents can make mistakes, so when using agents with the Postman MCP server, follow these best practices:

State when you want the MCP server used specifically. The Postman CLI is the primary way coding agents work with Postman, so an agent with both MCP and CLI access may default to the CLI. If you want the MCP server used for a given task instead — for example, in a chat-based or IDE context without CLI access — say so explicitly, with a prompt like “When interacting with Postman resources, use the Postman MCP server you have access to.”
Always review and confirm operations. When performing operations that make changes or are destructive, such as updating or deleting resources, always validate responses before you accept them from the agent.
Pass resource IDs to reduce API calls. For example, to operate with a specific workspace, get the workspace’s ID and be clear when you state it. Otherwise, the LLM has to fetch all the workspaces, then select the specific one you want to work with, which can result in multiple API requests.

Postman API server prompts

The following examples use VS Code’s GitHub Copilot.

The following provide examples of useful prompts you can use to work with and manage your Postman elements:

Managing environments

In this use case, the user wants to update an environment variable’s value.

Update an environment variable

Change the value of my Postman environment variable “baseUrl” in the “Local” environment to use [http://localhost:8001](http://localhost:8001).

Response: The agent gets your environments to find the ID of the “Local” environment, then gets that environment’s details and finds that baseUrl is set to http://localhost:8000. It updates the environment with the new value, then gets the environment again to verify the change. The agent confirms that baseUrl is set to http://localhost:8001.

Create an OpenAPI and sync the spec with Postman

In this example, the user is working on a back end Django REST Framework API and wants to keep it in sync with Postman.

Create and sync an OpenAPI spec

This repository contains a Django REST Framework API. We’ve implemented a CRUD API for a resource called “Customer”. We already have a Postman workspace called “Customers”. I want you to:

* Infer an OpenAPI definition for my API (Customers CRUD), based on the model fields.
* Retrieve my workspace “Customers” ID. Use the Postman MCP server tools.
* Create a Postman Spec in the existing “Customers” workspace.
* Create the collection from the spec.

Response: The agent reads the fields of the Django Customer model (first_name, last_name, email, and address) and creates an OpenAPI 3.0 specification in the “Customers” workspace. It then generates a collection from the spec. The agent confirms that the spec covers the five CRUD operations (GET /api/customers/, POST /api/customers/, GET /api/customers/{id}/, PUT /api/customers/{id}/, and DELETE /api/customers/{id}/), and that each endpoint has request and response schemas, field descriptions, validation rules, and status codes. It also notes that the collection is organized by tags and uses the baseUrl variable, so you can switch between local and production environments. The agent then asks whether you want it to add example requests or test scripts to the collection.

Update a collection’s documentation

In this example, the user updated their Postman Collection and wants to update its documentation to match the changes they’ve made.

Update a collection's description

Update my collection “Customer API Collection” information to: “CRUD operations on the customers table. These endpoints require authentication and permissions on the Customer table.”

Response: The agent gets all of your collections to find “Customer API Collection” by name, then gets that collection’s current information. It updates the collection’s description with the PATCH /collections/{collectionId} endpoint, then confirms the change and shows the new description.

Perform a back end change based on Postman Spec changes

This example assumes the user is working with a Django REST Framework app. They’re also an employee of an API design-first company, and want to make the changes in Postman’s Spec Hub. The back end developers will then use the specification to implement the changes.

Update code from spec changes

I’ve updated the Postman Spec called “Customer API” and I’ve added some new fields to the Customer resources. Analyze the changes in the spec (retrieve it from Postman using the Postman MCP server you have access to) and reflect them in the Django code (model and serializer).

Response: The agent gets your workspaces to find the workspace ID, then gets the specifications in that workspace and the details of the “Customer API” spec. After it compares the spec with the Django code, the agent updates the model and serializer to add the new fields. It then asks you to review the changed files and keep or undo the changes.