Openapi®

---

🔐 Openapi® MCP The official Python MCP SDK and ready-to-run MCP server for Openapi®

Overview

Welcome to `openapi-mcp-sdk`, this is the official openapi.com MCP SDK. It ships as a Python package on PyPI and can be used in two ways:

• Ready-to-use server — run the MCP gateway directly from the package with a single command, no cloning or setup required.
• Python library — import openapi_mcp_sdk in your own project to build a custom MCP server that wraps openapi.com APIs with your own logic, tools, or auth layer on top.

Environment variables

All configuration is done through environment variables. None are required to start the server — defaults are suitable for local use.

Core

Storage

The server needs to store files for APIs that return binary documents (e.g. company official documents). The storage backend is configurable:

Cache

Used to share async callback results across multiple server instances.

See docs/env/ for per-environment configuration guides (local, Docker, AWS, GCP, Kubernetes).

Features

• Secure proxy: Pass-through of the Bearer Token provided by the client, without direct handling of sensitive credentials.
• Extensible: Easily add new tools/APIs by creating modules in /apis/.
• MCP-compatible: Designed according to MCP protocol best practices.
• Modular: All API call logic and tool registration is centralized in mcp_core.py.

Quick Start — run from PyPI (recommended)

No cloning, no virtual environment. Start the server in one command:

uvx openapi-mcp-sdk server

The server starts immediately at http://localhost:8080.

Other runtimes

# pipx (ephemeral run, no install needed — similar to uvx)

pipx run openapi-mcp-sdk server

pip (installs the package, then run the command)

pip install openapi-mcp-sdk && openapi-mcp-sdk server

pip3 on systems where python3 is the default

pip3 install openapi-mcp-sdk && openapi-mcp-sdk server

CLI reference

openapi-mcp-sdk <command>

Commands: server Start the MCP server (HTTP/SSE, default port 8080) ping Ping the openapi.com APIs and report latency [coming soon] token Generate or inspect an openapi.com Bearer token [coming soon]

Running with Docker

The project ships a single compose.yml with the mcp service.

# Build and start (production-like image)

docker compose up --build

Run in background

docker compose up --build -d

Follow logs

docker compose logs -f mcp

The server will be accessible at http://localhost:8080.

Debug and Development

Local development (without Docker)

The fastest iteration loop runs the server directly with uvicorn:

make start

This sets PYTHONPATH=src and starts uvicorn with auto-reload disabled. The server listens on http://0.0.0.0:8080.

To test endpoints manually:

curl -H "Authorization: Bearer YOUR_TOKEN" http://localhost:8080

The server prints request headers and parameters to stdout — no extra configuration needed.

Remote debugging with VS Code and Docker (one click)

The repository is pre-configured for a single-click debug experience. No manual steps, no editing compose files, no terminal commands.

How it works

Workflow

1. Set your breakpoints anywhere in src/.
2. Open Run and Debug (Ctrl+Shift+D / ⌘+Shift+D).
3. Select `MCP: Debug (Docker)` from the dropdown.
4. Press F5.

VS Code will:

• Build the debug image (docker/dev/Dockerfile) if needed.
• Start the container via compose.yml (debug image + bind mount).
• Wait automatically until debugpy is accepting connections on port 5678.
• Attach debugpy — your breakpoints are now live.

When you press ⇧F5 (Stop), VS Code detaches and tears down the container.

Keep the container alive after detaching?

Remove the "postDebugTask" line from .vscode/launch.json. You can then

re-attach at any time by pressing F5 again without rebuilding.

Live code reload

compose.yml bind-mounts ./src into /app/src inside the container. Edits to files under src/ are reflected immediately — no image rebuild required. Just send a new request and the updated code runs.

Path mapping reference

Authentication

The server accepts the Bearer token in two ways:

Option A — Authorization header (recommended)

Pass the token as a standard HTTP header:

Authorization: Bearer YOUR_TOKEN

Option B — ?token= query parameter

Some MCP clients or environments do not support custom HTTP headers. In that case the token can be embedded directly in the server URL as a query parameter:

http://YOUR_SERVER_IP:8080/?token=YOUR_TOKEN

The server automatically promotes it to an Authorization: Bearer header before the request reaches the MCP layer, so the behaviour is identical.

When to use `?token=`: Claude Desktop (as of mid-2025), some browser-based

MCP playgrounds, and any client whose configuration only accepts a plain URL

without a headers field.

MCP Client Configuration (VS Code)

1. Generate a Bearer Token From the portal https://console.openapi.com/oauth, create a token with the required scopes.

1. Create the `.vscode/mcp.json` file

With header (recommended):

   {

"servers": { "openapi.com": { "type": "http", "url": "http://YOUR_SERVER_IP:8080/", "headers": { "Authorization": "Bearer YOUR_TOKEN" } } } }

With `?token=` query parameter (for clients that do not support custom headers):

   {

"servers": { "openapi.com": { "type": "http", "url": "http://YOUR_SERVER_IP:8080/?token=YOUR_TOKEN" } } }

1. Test the integration

• Reload VS Code.
• Open the Copilot chat and type @workspace.
• Use the tools exposed by the MCP server.

File storage

Some openapi.com APIs (e.g. visure camerali — Italian official company documents) return large binary files (ZIP archives, PDFs) that cannot be embedded inline in the MCP stream. The server downloads these files, stores them, and serves them via a separate HTTP endpoint (GET /status/{id}/files/{filename}).

Default: local filesystem

By default (MCP_STORAGE_BACKEND=local) files are written to ./openapi_storage relative to the directory from which the server is started:

./openapi_storage/

└── / ├── document.pdf └── attachments.zip

Override the path with the MCP_STORAGE_PATH environment variable:

export MCP_STORAGE_PATH=/var/data/openapi_storage

uvx openapi-mcp-sdk server

The directory is created automatically on first use. For the download links to

work correctly, MCP_BASE_URL must point to the public address of the server

(default: http://localhost:8080).

Cloud storage backends

See docs/env/ for full per-environment configuration guides.

Deployment environments

Project Structure

• src/openapi_mcp_sdk/main.py: FastAPI + MCP server entry point.
• src/openapi_mcp_sdk/mcp_core.py: MCP initialization, API call helpers, error handling.
• [src/openapi_mcp_sdk/apis/](src/openapi_mcp_s