You run a lightweight MCP server that ingests Swagger/OpenAPI specs and Postman collections and exposes them as four strategic tools for AI agents. This approach lets you discover and interact with APIs efficiently, without exposing you to hundreds of endpoint-specific tools.

How to use

Connect to the MCP server with a client that supports the stdio transport. You’ll have four strategic tools to work with either OpenAPI/Swagger definitions or Postman collections. Use these tools to list endpoints, get detailed information, search by keyword, and execute API calls. The server handles authentication, parameter mapping, and response handling so your AI agent can focus on building requests and interpreting results.

How to install

Prerequisites you need before installing include Node.js v18 or higher, Yarn, and TypeScript. Install steps are shown as commands you can copy-paste.

# Clone the repository
git clone <repository-url>
cd swag-mcp

# Install dependencies
npm install
# or
yarn install

# Build the project
npm run build
# or
yarn build

# Make the start script executable (Linux/macOS)
chmod +x start-mcp.sh

Configuration

Configure the MCP server using a config.json that specifies either an OpenAPI/Swagger source or a Postman collection. The following examples show the supported configuration shapes.

{
  "api": {
    "type": "openapi",
    "openapi": {
      "url": "https://petstore.swagger.io/v2/swagger.json",
      "apiBaseUrl": "https://petstore.swagger.io/v2",
      "defaultAuth": {
        "type": "apiKey",
        "apiKey": "special-key",
        "apiKeyName": "api_key",
        "apiKeyIn": "header"
      }
    }
  },
  "log": {
    "level": "info"
  }
}

{
  "api": {
    "type": "postman",
    "postman": {
      "collectionUrl": "https://www.postman.com/collections/your-collection-id",
      "collectionFile": "./examples/postman-collection.json",
      "environmentUrl": "https://www.postman.com/environments/your-environment-id",
      "environmentFile": "./examples/postman-environment.json",
      "defaultAuth": {
        "type": "bearer",
        "token": "your-api-token-here"
      }
    }
  },
  "log": {
    "level": "info"
  }
}

• API configuration supports type as either openapi or postman.
• Authentication can be defined globally via defaultAuth and overridden per request.

## Security

This server is intended for private use. Do not expose it to the public internet. If the underlying API requires authentication, ensure the MCP server remains on a trusted network.

## Development and troubleshooting

If you need to adjust the startup flow for local development or debugging, you can rely on the standard development commands and build steps.

Install dependencies

npm install

Run in development mode with auto-reload

npm run dev:simple

or

yarn dev:simple

## Available tools

### list\_endpoints

List all available API endpoints and their methods from the loaded OpenAPI/Swagger specification or Postman collection.

### get\_endpoint\_details

Provide detailed information about a specific endpoint, including parameters, request body, and responses.

### search\_endpoints

Search endpoints by keyword across path, summary, or description.

### make\_api\_call

Execute an API call to a specified endpoint with method, path, params, headers, and body.

### list\_requests

List all requests defined in the loaded Postman collection.

### get\_request\_details

Show detailed information about a specific request within the Postman collection.

### search\_requests

Search requests in the collection by keyword.

### make\_request

Execute a specific request from the Postman collection with optional variables.