Openapi Mcp Server

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

[](https://github.com/openapi/mcp-server/actions/workflows/build.yml) [](https://pypi.org/project/openapi-mcp-sdk/) [](https://www.python.org/) [](LICENSE) [](https://modelcontextprotocol.io/)

[](https://www.linuxfoundation.org/about/members)

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

| Variable | Default | Description | |---|---|------------------------------------------------------------------------------------------| | MCP_PORT | 8080 | HTTP port the server listens on | | MCP_ENV | production | Runtime environment: dev \| staging \| production | | MCP_BASE_URL | http://localhost:8080 | Public URL of this server (used to build callback and file download URLs) | | MCP_CALLBACK_URL | $MCP_BASE_URL/callbacks | Explicit callback URL sent to async APIs | | MCP_OPENAPI_ENV | (empty) | Openapi environment: dev, test, sandbox (alias of test), or empty for production |

Storage

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

| Variable | Default | Description | |-----------------------|---|---| | MCP_STORAGE_BACKEND | local | local \| gcs \| s3 | | MCP_STORAGE_PATH | ./openapi_storage | Local path for local backend | | MCP_STORAGE_BUCKET | (required for cloud) | Bucket name for gcs or s3 | | MCP_STORAGE_REGION | (required for s3) | AWS region for the S3 bucket |

Cache

Used to share async callback results across multiple server instances.

| Variable | Default | Description | |---------------------|---|---| | MCP_CACHE_BACKEND | none | none (in-process dict) \| memcached \| redis | | MCP_CACHE_URL | (none) | Redis connection URL (MCP_CACHE_BACKEND=redis), e.g. redis://host:6379 | | MCP_CACHE_HOST | (none) | Memcached host (MCP_CACHE_BACKEND=memcached) | | MCP_CACHE_PORT | 11211 | Memcached port |

See [docs/env/](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/](src/openapimcpsdk/apis/).
• MCP-compatible: Designed according to MCP protocol best practices.
• Modular: All API call logic and tool registration is centralized in [mcp_core.py](src/openapimcpsdk/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 

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](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

| File | Role | |---|---| | [docker/dev/Dockerfile](docker/dev/Dockerfile) | Debug image — adds debugpy, exposes port 5678 | | [compose.yml](compose.yml) | Compose config — dev image, debug ports, bind mount | | [.vscode/tasks.json](.vscode/tasks.json) | VS Code tasks — starts/stops the container automatically | | [.vscode/launch.json](.vscode/launch.json) | Launch config — ties everything together under F5 |

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

| | Host | Container | |---|---|---| | Source code | ./src | /app/src | | MCP server | localhost:8080 | 0.0.0.0:8080 | | debugpy listener | localhost:5678 | 0.0.0.0:5678 |

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): ``json { "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): ``json { "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

| MCP_STORAGE_BACKEND | Additional variables | Notes | |---|---|---| | local | MCP_STORAGE_PATH (default ./openapi_storage) | Default — local disk or mounted volume | | gcs | MCP_STORAGE_BUCKET | Google Cloud Storage | | s3 | MCP_STORAGE_BUCKET, MCP_STORAGE_REGION | AWS S3 or any S3-compatible service |

See [docs/env/](docs/env/) for full per-environment configuration guides.

Deployment environments

| Environment | Guide | |---|---| | Local machine (default) | [docs/env/local.md](docs/env/local.md) | | Docker / Docker Compose | [docs/env/docker.md](docs/env/docker.md) | | Google Cloud Platform | [docs/env/gcp.md](docs/env/gcp.md) | | Amazon Web Services | [docs/env/aws.md](docs/env/aws.md) | | Kubernetes | [docs/env/kubernetes.md](docs/env/kubernetes.md) |

Project Structure

• [src/openapi_mcp_sdk/main.py](src/openapimcpsdk/main.py): FastAPI + MCP server entry point.
• [src/openapi_mcp_sdk/mcp_core.py](src/openapimcpsdk/mcp_core.py): MCP initialization, API call helpers, error handling.
• [src/openapi_mcp_sdk/apis/](src/openapimcpsdk/apis/): Python modules defining MCP tools (one per API/scope).
• [requirements.txt](requirements.txt): Python dependencies.
• [compose.yml](compose.yml): Docker Compose (production image by default; see comments to switch to debug).
• [docker/latest/Dockerfile](docker/latest/Dockerfile): Production Docker image.
• [docker/dev/Dockerfile](docker/dev/Dockerfile): Development image with debugpy for VS Code remote debugging.
• [.vscode/launch.json](.vscode/launch.json): VS Code debug configuration (attach to debugpy).
• [docs/](docs/): Documentation and example configurations.

Adding New Tools/APIs

1. Create or modify a file in [/apis/](apis/), following this pattern:

```python from fastmcp import Context from typing import Any from mcpcore import makeapi_call, mcp

@mcp.tool async def toolname(parameters..., ctx: Context) -> Any: # ...logic... return makeapi_call(ctx, "GET", url, params=params) ```

1. 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](docs/contributing.md) for detailed instructions on how to get started. Please make sure to follow this project's [docs/code-of-conduct.md](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](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.

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: openapi
• Source: openapi/mcp-server
• License: MIT
• Homepage: https://console.openapi.com

Install and usage instructions live in the source repository linked above.