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.

2. 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"
       }
     }
   }

3. 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/
└── <request_id>/
    ├── 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/: Python modules defining MCP tools (one per API/scope).

• requirements.txt: Python dependencies.

• compose.yml: Docker Compose (production image by default; see comments to switch to debug).

• docker/latest/Dockerfile: Production Docker image.

• docker/dev/Dockerfile: Development image with debugpy for VS Code remote debugging.

• .vscode/launch.json: VS Code debug configuration (attach to debugpy).

• docs/: Documentation and example configurations.

Adding New Tools/APIs

1. Create or modify a file in /apis/, following this pattern:

   from fastmcp import Context
   from typing import Any
   from mcp_core import make_api_call, mcp
   
   @mcp.tool
   async def tool_name(parameters..., ctx: Context) -> Any:
       # ...logic...
       return make_api_call(ctx, "GET", url, params=params)

2. Restart the server to apply the changes.

Security Notes

• Never hardcode credentials or tokens in the code.

• The server expects the Bearer Token to be provided by the client via HTTP headers.

• All API calls are proxied using the token provided by the client.

Useful Resources

• MCP Documentation

• fastmcp

• openapi.com

Contributing

Contributions are always welcome! Whether you want to report bugs, suggest new features, improve documentation, or contribute code, your help is appreciated.

See docs/contributing.md for detailed instructions on how to get started. Please make sure to follow this project's docs/code-of-conduct.md to help maintain a welcoming and collaborative environment.

Authors

Meet the project authors:

• Simone Desantis (@SimoneDesantis)

• Marco Prosperi (@MarcoProsperi)

• Francesco Bianco (@francescobianco)

• Openapi Team (@openapi-it)

Partners

Meet our partners using Openapi or contributing to this SDK:

• Blank

• Credit Safe

• Deliveroo

• Gruppo MOL

• Jakala

• Octotelematics

• OTOQI

• PWC

• QOMODO S.R.L.

• SOUNDREEF S.P.A.

License

This project is licensed under the MIT License.

The MIT License is a permissive open-source license that allows you to freely use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the software, provided that the original copyright notice and this permission notice are included in all copies or substantial portions of the software.

In short, you are free to use this SDK in your personal, academic, or commercial projects, with minimal restrictions. The project is provided "as-is", without any warranty of any kind, either expressed or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose, and non-infringement.

For more details, see the full license text at the MIT License page.