{"slug": "postmcp-turn-any-openapi-spec-into-a-context-optimized-mcp-server", "title": "PostMCP – Turn any OpenAPI spec into a context-optimized MCP server", "summary": "PostMCP, a tool from developer BraveRam, converts any OpenAPI or Swagger specification into a Model Context Protocol (MCP) server for AI coding assistants such as OpenCode, Cursor, Claude Desktop, and Windsurf. PostMCP claims its token-diet feature cuts token consumption by 70% to 95% by stripping boilerplate and converting large JSON arrays into Markdown tables, while adaptive JIT routing keeps tool definitions under 1,500 active tokens for large specs like Stripe and GitHub. The tool installs via a one-line shell script or npm package @postmcp/cli, and its dry-run protection intercepts POST, PUT, and DELETE mutations before they reach production systems.", "body_md": "Turn any OpenAPI or Swagger specification into a fast, context-optimized, safe Model Context Protocol (MCP) server for your AI coding agents.\n\nAI coding assistants (OpenCode, Cursor, Claude Desktop, Windsurf) are great at writing code, but giving them direct access to external APIs usually means writing hundreds of lines of custom MCP server boilerplate by hand.\n\nEven if you auto-convert an OpenAPI spec naively, you hit immediate problems:\n\n- **Context Bloat** : A 200-endpoint API injects tens of thousands of tokens into every turn, exhausting context limits and causing hallucinations.\n- **Token Drowning** : Raw API responses return massive JSON payloads full of nulls, URLs, and internal metadata your LLM does not need.\n- **Auth Confusion** : Every API has different credential headers, query formats, and auth schemes.\n\nPostMCP solves this out of the box:\n\n1. **Inspect any API in seconds** : Point to any OpenAPI URL, file, or preset to instantly see its endpoints, risk levels, and exact authentication requirements.\n2. **Zero-Code Execution** : Run an in-memory MCP server over standard stdio or Streamable HTTP.\n3. **Token Diet** : Automatically strips boilerplate and turns large JSON arrays into concise Markdown tables, cutting token consumption by 70% to 95%.\n4. **Adaptive JIT Routing** : Scales to massive specs (e.g. Stripe, GitHub) by keeping tool definitions under 1,500 active tokens and loading endpoints on demand.\n5. **Dry-Run Protection** : Intercepts destructive mutations (POST, PUT, DELETE) before they touch production systems.\n\nInstall PostMCP in one command:\n\n```\n# macOS & Linux\ncurl -fsSL https://raw.githubusercontent.com/BraveRam/postmcp/main/install.sh | bash\n\n# Windows (PowerShell)\nirm https://raw.githubusercontent.com/BraveRam/postmcp/main/install.ps1 | iex\n```\n\nOr via your favorite package manager:\n\n```\nnpm install -g @postmcp/cli\n# or: pnpm add -g @postmcp/cli\n# or: bun add -g @postmcp/cli\n```\n\nAdd any API directly to your coding assistant without installing anything locally:\n\n```\n{\n  \"$schema\": \"https://opencode.ai/config.json\",\n  \"mcp\": {\n    \"firecrawl\": {\n      \"type\": \"local\",\n      \"enabled\": true,\n      \"command\": [\n        \"bunx\",\n        \"@postmcp/cli\",\n        \"run\",\n        \"https://raw.githubusercontent.com/firecrawl/firecrawl/refs/heads/main/apps/api/openapi.json\"\n      ],\n      \"environment\": {\n        \"BEARER_TOKEN\": \"YOUR_FIRECRAWL_API_KEY\"\n      }\n    }\n  }\n}\n```\n\nRun directly in terminal:\n\n```\nclaude mcp add firecrawl -s project -e BEARER_TOKEN=YOUR_FIRECRAWL_API_KEY -- bunx @postmcp/cli run https://raw.githubusercontent.com/firecrawl/firecrawl/refs/heads/main/apps/api/openapi.json\n```\n\nOr add to `.mcp.json` in your project root:\n\n```\n{\n  \"mcpServers\": {\n    \"firecrawl\": {\n      \"command\": \"bunx\",\n      \"args\": [\n        \"@postmcp/cli\",\n        \"run\",\n        \"https://raw.githubusercontent.com/firecrawl/firecrawl/refs/heads/main/apps/api/openapi.json\"\n      ],\n      \"env\": {\n        \"BEARER_TOKEN\": \"YOUR_FIRECRAWL_API_KEY\"\n      }\n    }\n  }\n}\n```\n\nOpenAI Codex caches tools on initial startup and does not support mid-session dynamic tool reloading (`list_changed`). Always pass `--no-jit` to expose tools statically.\n\nRun directly in terminal:\n\n```\ncodex mcp add firecrawl --env BEARER_TOKEN=YOUR_FIRECRAWL_API_KEY -- bunx @postmcp/cli run https://raw.githubusercontent.com/firecrawl/firecrawl/refs/heads/main/apps/api/openapi.json --no-jit\n```\n\nOr add to `.codex/config.toml` (or `~/.codex/config.toml`):\n\n```\n[mcp_servers.firecrawl]\ncommand = \"bunx\"\nargs = [\n  \"@postmcp/cli\",\n  \"run\",\n  \"https://raw.githubusercontent.com/firecrawl/firecrawl/refs/heads/main/apps/api/openapi.json\",\n  \"--no-jit\"\n]\nenv = { BEARER_TOKEN = \"YOUR_FIRECRAWL_API_KEY\" }\n{\n  \"mcpServers\": {\n    \"firecrawl\": {\n      \"command\": \"bunx\",\n      \"args\": [\n        \"@postmcp/cli\",\n        \"run\",\n        \"https://raw.githubusercontent.com/firecrawl/firecrawl/refs/heads/main/apps/api/openapi.json\"\n      ],\n      \"env\": {\n        \"BEARER_TOKEN\": \"YOUR_FIRECRAWL_API_KEY\"\n      }\n    }\n  }\n}\n```\n\n*(Note: Replace `\"bunx\"` with `\"npx\", \"-y\"` if running on Node.js instead of Bun).*\n\nLaunch the local interactive workbench to explore APIs, test endpoints in the AI sandbox, and curate Token Diet rules:\n\n```\npostmcp studio\n```\n\nOpens `http://localhost:3000` in your default browser. From here, you can load any of the 60+ bundled presets, import custom OpenAPI specs, and access the built-in documentation at `http://localhost:3000/docs`.\n\nBefore connecting an API to your agent, inspect it to verify its endpoints and authentication requirements:\n\n```\npostmcp inspect https://raw.githubusercontent.com/firecrawl/firecrawl/refs/heads/main/apps/api/openapi.json\n```\n\nOr inspect one of the 60+ built-in presets:\n\n```\nnpx @postmcp/cli inspect @stripe\n```\n\nThe output gives you an immediate summary:\n\n- Total operations and HTTP methods.\n- Base API URL.\n- Security schemes and exact credential requirements.\n- Estimated token savings with Token Diet.\n\nEvery API authenticates differently. PostMCP makes it easy to know what to pass. When you run `postmcp inspect`, check the **Security Schemes** and **Authentication Guide** in the output.\n\nThere are three common authentication patterns:\n\nCommon services: Firecrawl, Stripe, GitHub, OpenAI, Supabase, Neon.\n\n- **What it means** : The API expects an HTTP`Authorization: Bearer <token>` header.\n- **How to pass via CLI** :\n\n```\nnpx @postmcp/cli run <spec-url> --bearer $MY_API_KEY\n```\n\n- **How to pass via Environment Variables** :\nPostMCP automatically checks for`BEARER_TOKEN` or`API_KEY` in your environment.\n\n```\nexport BEARER_TOKEN=\"your-token-here\"\nnpx @postmcp/cli run <spec-url>\n```\n\nCommon services: Weather APIs, older enterprise gateways, custom services.\n\n- **What it means** : The key is sent in a custom header (e.g.`X-API-Key: <token>` ) or query parameter (e.g.`?api_key=<token>` ).\n- **Finding the exact parameter name** :\nRun`npx @postmcp/cli inspect <spec-url> --json` and look at the`securitySchemes` block.\n- **How to pass via CLI** :\n  - For headers:\nor\n\n```\nnpx @postmcp/cli run <spec-url> -H \"X-API-Key: your-token-here\"\nnpx @postmcp/cli run <spec-url> --api-key \"X-API-Key=your-token-here\"\n```\n\n  - For query parameters:\n\n```\nnpx @postmcp/cli run <spec-url> --api-key \"query:api_key=your-token-here\"\n```\n\n- For headers:\n\nIf you are using a preset (like `@neon`, `@supabase`, `@github`, or `@stripe`), PostMCP already knows the exact token names:\n\n| Preset | Built-in Env Variable | Description | \n|---|---|---|\n| `@neon` | `NEON_API_KEY` | Serverless Postgres management | \n| `@supabase` | `SUPABASE_ACCESS_TOKEN` | Supabase Cloud management | \n| `@stripe` | `STRIPE_SECRET_KEY` | Stripe Payments & Billing | \n| `@github` | `GITHUB_TOKEN` | GitHub REST API | \n| `@sentry` | `SENTRY_AUTH_TOKEN` | Sentry Error & Performance Monitoring | \n| `@slack` | `SLACK_BOT_TOKEN` | Slack Web API | \n\nCommon services: Jira, Bitbucket, traditional internal microservices.\n\n- **What it means** : The API expects HTTP Basic credentials sent via`Authorization: Basic <base64>` .\n- **How to pass via CLI** :\n\n```\nnpx @postmcp/cli run <spec-url> --basic-auth \"username:password\"\n```\n\n- **How to pass via Environment Variables** :\nPostMCP automatically checks for`BASIC_AUTH` in your environment (username:password or pre-encoded base64):\n\n```\nexport BASIC_AUTH=\"username:password\"\nnpx @postmcp/cli run <spec-url>\n```\n\nConfigure PostMCP in your editor's MCP settings.\n\n```\n{\n  \"mcp\": {\n    \"firecrawl\": {\n      \"type\": \"local\",\n      \"enabled\": true,\n      \"command\": [\n        \"npx\",\n        \"-y\",\n        \"@postmcp/cli@latest\",\n        \"run\",\n        \"https://raw.githubusercontent.com/firecrawl/firecrawl/refs/heads/main/apps/api/openapi.json\",\n        \"--token-diet\"\n      ],\n      \"environment\": {\n        \"BEARER_TOKEN\": \"{env:FIRECRAWL_API_KEY}\"\n      }\n    },\n    \"neon\": {\n      \"type\": \"local\",\n      \"enabled\": true,\n      \"command\": [\n        \"npx\",\n        \"-y\",\n        \"@postmcp/cli@latest\",\n        \"run\",\n        \"@neon\",\n        \"--token-diet\"\n      ],\n      \"environment\": {\n        \"NEON_API_KEY\": \"{env:NEON_API_KEY}\"\n      }\n    }\n  }\n}\n```\n\nRegister directly with the Claude Code CLI:\n\n```\nclaude mcp add stripe -s project -e STRIPE_SECRET_KEY=$STRIPE_SECRET_KEY -- npx -y @postmcp/cli@latest run @stripe --token-diet --jit\n```\n\nOr add to `.mcp.json` in your repository root:\n\n```\n{\n  \"mcpServers\": {\n    \"stripe\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"-y\",\n        \"@postmcp/cli@latest\",\n        \"run\",\n        \"@stripe\",\n        \"--token-diet\",\n        \"--jit\"\n      ],\n      \"env\": {\n        \"STRIPE_SECRET_KEY\": \"${env:STRIPE_SECRET_KEY}\"\n      }\n    }\n  }\n}\n```\n\nOpenAI Codex caches tools on startup and ignores dynamic tool updates mid-session. Always specify `--no-jit` to expose tools statically.\n\nRegister directly with the Codex CLI:\n\n```\ncodex mcp add stripe --env STRIPE_SECRET_KEY=$STRIPE_SECRET_KEY -- npx -y @postmcp/cli@latest run @stripe --token-diet --no-jit\n```\n\nOr add to `.codex/config.toml`:\n\n```\n[mcp_servers.stripe]\ncommand = \"npx\"\nargs = [\n  \"-y\",\n  \"@postmcp/cli@latest\",\n  \"run\",\n  \"@stripe\",\n  \"--token-diet\",\n  \"--no-jit\"\n]\nenv = { STRIPE_SECRET_KEY = \"${STRIPE_SECRET_KEY}\" }\n{\n  \"mcpServers\": {\n    \"stripe\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"-y\",\n        \"@postmcp/cli@latest\",\n        \"run\",\n        \"@stripe\",\n        \"--token-diet\",\n        \"--jit\"\n      ],\n      \"env\": {\n        \"STRIPE_SECRET_KEY\": \"${env:STRIPE_SECRET_KEY}\"\n      }\n    }\n  }\n}\n{\n  \"mcpServers\": {\n    \"supabase\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"-y\",\n        \"@postmcp/cli@latest\",\n        \"run\",\n        \"@supabase\",\n        \"--token-diet\"\n      ],\n      \"env\": {\n        \"SUPABASE_ACCESS_TOKEN\": \"your-access-token\"\n      }\n    }\n  }\n}\n```\n\nRaw API responses often return nested objects with dozens of unused properties, audit logs, and null values.\n\nWhen `--token-diet` is enabled:\n\n- Null and undefined values are automatically removed.\n- Redundant links, ETags, and metadata are pruned.\n- Arrays of records are converted into clean GitHub-flavored Markdown tables.\n- Output size is reduced by up to 90%, preventing context overflows and keeping responses legible for LLMs.\n\nWhen an API exposes more than 20 endpoints (or hundreds, like Stripe and GitHub), exposing all tools statically overwhelms the LLM.\n\nWhen `--jit` is enabled:\n\n- PostMCP pre-mounts root discovery operations and an intelligent `tool_search` meta-tool.\n- When the agent needs a specialized endpoint, it searches for it (e.g. `tool_search({ query: \"refund charge\" })` ).\n- Matched tools are mounted dynamically into memory and the MCP client is notified.\n- Active prompt context stays below 1,500 tokens regardless of API size.\n\nAllows your agent to test complex, multi-step workflows without making real changes:\n\n- Read-only operations (`GET` ,`HEAD` ) execute against live APIs.\n- Mutations (`POST` ,`PUT` ,`DELETE` ,`PATCH` ) are intercepted locally.\n- PostMCP returns realistic simulated success responses annotated with `[DRY RUN SAFEGUARD ACTIVE]` .\n\nPass any custom headers required by your proxy, API gateway, or company infrastructure:\n\n```\nnpx @postmcp/cli run ./my-spec.json \\\n  -H \"X-Organization-Id: org_123\" \\\n  -H \"X-Workspace: staging\"\n```\n\nPostMCP includes a local visual studio for inspecting APIs, testing endpoints, designing multi-step macros, and testing prompts in an interactive AI sandbox.\n\nLaunch the studio with:\n\n```\nnpx @postmcp/cli studio\n```\n\nOr open a specific spec directly:\n\n```\nnpx @postmcp/cli studio https://raw.githubusercontent.com/firecrawl/firecrawl/refs/heads/main/apps/api/openapi.json\n```\n\nNavigate to `http://localhost:3000` to:\n\n- Search and browse all operations with risk-tier classification.\n- Configure custom field masks and preview token savings in real time.\n- Build composite multi-step macros.\n- Test tool calls inside the live LLM sandbox.\n- Export ready-to-use configuration files for Cursor, Claude Desktop, and OpenCode with one click.\n\nIf you prefer to deploy an independent, self-contained MCP server instead of running PostMCP as a dynamic proxy, you can generate clean source code in TypeScript or Python:\n\n```\n# Generate a standalone TypeScript MCP server project\nnpx @postmcp/cli generate @stripe --lang ts -o ./stripe-mcp-ts\n\n# Generate a standalone Python FastMCP project\nnpx @postmcp/cli generate @stripe --lang py -o ./stripe-mcp-py\n```\n\nThe generated project includes:\n\n- Native MCP tool handlers.\n- Typed Pydantic models (Python) or Zod schemas (TypeScript).\n- Ready-to-run test suite and Dockerfile.\n\n```\nUsage: postmcp <command> [options]\n\nCommands:\n  run <spec>         Start an MCP server from an OpenAPI spec, URL, or @preset\n  studio [spec]      Launch the local visual web studio (Next.js + Turbopack)\n  inspect <spec>     Analyze an API spec, security schemes, and estimated token savings\n  generate <spec>    Generate standalone TypeScript or Python MCP server code\n  export <spec>      Export configurations for OpenCode, Claude Code, Codex, Cursor, Claude, Windsurf\n  presets [action]   List and browse the 60+ built-in API presets\n  docs               Open documentation in your default browser\n```\n\n| Flag | Description | \n|---|---|\n| `--token-diet` | Enable automatic response pruning and Markdown table conversion (default: enabled) | \n| `--no-token-diet` | Disable Token Diet payload pruning and markdown tables | \n| `--max-tokens <num>` | Token ceiling per tool response (default: 2500) | \n| `--jit` | Enable dynamic JIT tool discovery to save context tokens | \n| `--no-jit` | Disable dynamic JIT tool discovery and expose all tools statically | \n| `--hot-tool-keywords <kw>` | Prioritize specific keywords for turn-1 pre-mounted hot tools | \n| `--bearer <token>` | Pass an HTTP Bearer token or `$ENV_VAR` | \n| `--api-key <key>` | Pass an API key (e.g. `X-API-Key=value` or`query:key=value` ) | \n| `--basic-auth <creds>` | Pass HTTP Basic credentials ( `username:password` or`$ENV_VAR` ) | \n| `-H, --header <k:v>` | Forward custom HTTP header to upstream requests (can be repeated) | \n| `--dry-run` | Intercept and simulate destructive mutations | \n| `-t, --transport <type>` | Transport protocol: `stdio` (default) or`http` | \n| `-p, --port <port>` | Port for Streamable HTTP server (mounts at `/mcp` ) | \n| `--base-url <url>` | Override the default upstream API base URL | \n| `--env-file <path>` | Load environment variables from a custom `.env` file | \n| `-c, --config <path>` | Path to a custom `postmcp.config.json` file | \n\nPostMCP is organized as a modular TypeScript monorepo managed with `pnpm` and `turbo`:\n\n- `packages/core` : Spec parsing, token diet transformation, dynamic JIT tool routing, and runtime HTTP dispatching (`@postmcp/core` ).\n- `packages/cli` : The`postmcp` command-line tool (`@postmcp/cli` ).\n- `packages/presets` : Pre-tuned configurations and field masks for 60+ popular developer APIs (`@postmcp/presets` ).\n- `packages/studio` : Local visual workbench built on Next.js 16 and Turbopack (`@postmcp/studio` ).\n- `packages/types` : Shared TypeScript interfaces across all packages (`@postmcp/types` ).\n\n```\n# Clone the repository\ngit clone https://github.com/BraveRam/postmcp.git\ncd postmcp\n\n# Install dependencies\npnpm install\n\n# Build all packages\npnpm build\n\n# Run unit tests across all packages\npnpm test\n\n# Run type checking\npnpm run typecheck\n```\n\nMIT (c) [PostMCP Contributors](https://github.com/BraveRam/postmcp/blob/main/LICENSE)", "url": "https://wpnews.pro/news/postmcp-turn-any-openapi-spec-into-a-context-optimized-mcp-server", "canonical_source": "https://github.com/braveram/postmcp", "published_at": "2026-09-23 09:41:30+00:00", "updated_at": "2026-09-23 09:59:12.552954+00:00", "lang": "en", "topics": ["ai-agents", "agent-protocols", "ai-tools", "developer-tools", "ai-products"], "entities": ["PostMCP", "BraveRam", "OpenAPI", "Swagger", "Model Context Protocol", "OpenCode", "Cursor", "Claude Desktop"], "alternates": {"html": "https://wpnews.pro/news/postmcp-turn-any-openapi-spec-into-a-context-optimized-mcp-server", "markdown": "https://wpnews.pro/news/postmcp-turn-any-openapi-spec-into-a-context-optimized-mcp-server.md", "text": "https://wpnews.pro/news/postmcp-turn-any-openapi-spec-into-a-context-optimized-mcp-server.txt", "jsonld": "https://wpnews.pro/news/postmcp-turn-any-openapi-spec-into-a-context-optimized-mcp-server.jsonld"}}