safe-oas2mcp

OpenAPI to MCP, safely.

safe-oas2mcp turns OpenAPI specs into MCP tools with secure defaults, risk inspection, confirmation gates, response limits, audit logging, and secret redaction.

It is not a plain OpenAPI-to-MCP converter. It is a Safe OpenAPI to MCP Gateway for Agent developers, SaaS APIs, and internal platform teams that need to expose real business APIs without handing unsafe operations to models by default.

Quick Start

Install from a local checkout:

python -m pip install -e ".[dev]"

Or run directly with uv from this checkout:

uvx --from . safe-oas2mcp --help

Inspect an OpenAPI file:

safe-oas2mcp inspect examples/todo/openapi.yaml
safe-oas2mcp inspect examples/todo/openapi.yaml --format json

Start the MCP stdio server:

safe-oas2mcp serve examples/todo/openapi.yaml

Why

Many systems already expose OpenAPI, but most converters expose too much too quickly. Agent tool calls can create, update, delete, export, transfer, or leak sensitive data if the gateway does not apply a conservative policy.

safe-oas2mcp keeps safety decisions visible:

• GET operations are enabled by default, unless risky keywords are detected.
• POST operations require confirmation by default.
• PUT and PATCH operations require confirmation by default.
• DELETE operations are disabled by default.
• Risk and status decisions include reasons.
• Tokens and API keys are injected server-side and are not shown to the model.
• Sensitive response fields are redacted.

Inspect Your API

safe-oas2mcp inspect ./openapi.yaml

Example output:

Tool         Method  Path              Risk      Status    Reasons
list_tasks   GET     /tasks            low       enabled   GET is enabled by default
create_task  POST    /tasks            medium    confirm   POST write operation requires confirmation by default
delete_task  DELETE  /tasks/{task_id}  critical  disabled  DELETE is disabled by default

Use JSON output for CI or review:

safe-oas2mcp inspect ./openapi.yaml --format json

Use a policy config during inspect:

safe-oas2mcp inspect ./openapi.yaml --config ./safe-oas2mcp.config.yaml

Serve as MCP Server

safe-oas2mcp serve ./openapi.yaml --config ./safe-oas2mcp.config.yaml

The server uses MCP stdio transport. It registers enabled and confirm tools, skips disabled tools, validates MCP input with the generated JSON Schema, builds an HTTP request, injects configured auth headers, and returns a redacted response.

Confirm tools return a request preview instead of executing the real HTTP request.

Security Defaults

Condition	Risk	Status
GET	low	enabled
POST	medium	confirm
PUT	high	confirm
PATCH	high	confirm
DELETE	critical	disabled
money, permission, destructive, export, bulk, token, secret keywords	high or critical	confirm or disabled

Default keyword groups include:

• money: payment, refund, transfer, payout, invoice, billing, charge
• identity: user, account, customer, password, token, secret, key, email, phone
• permission: admin, root, role, permission, policy, access, invite
• destructive: delete, remove, destroy, revoke, disable, suspend, terminate
• bulk_data: export, bulk, batch, dump, report, download

Configuration

Create safe-oas2mcp.config.yaml:

base_url: https://api.example.com

auth:
  type: bearer
  token_env: EXAMPLE_API_TOKEN

headers:
  X-Workspace-Id:
    env: WORKSPACE_ID

timeout_seconds: 30
max_response_bytes: 1000000

policy:
  include:
    - "GET /tasks"
  exclude:
    - "DELETE /*"
  overrides:
    "DELETE /tasks/{task_id}":
      status: confirm
      risk: high
      reason: "Allow task delete preview only"

audit:
  enabled: false
  path: safe-oas2mcp.audit.jsonl

Supported auth modes:

auth:
  type: bearer
  token_env: API_TOKEN

auth:
  type: api_key
  key_env: API_KEY
  header_name: X-API-Key

Examples

• Todo SaaS Demo
• Petstore Demo
• GitHub API readonly Demo

MCP Client Setup

• Claude Desktop
• Cursor
• Windsurf
• Troubleshooting

Docker

Build locally:

docker build -t safe-oas2mcp:local .

Inspect with Docker:

docker run --rm safe-oas2mcp:local inspect examples/todo/openapi.yaml

Serve with env-injected auth:

docker run --rm -i \
  -e GITHUB_TOKEN="$GITHUB_TOKEN" \
  safe-oas2mcp:local \
  serve examples/github-readonly/openapi.yaml --config examples/github-readonly/safe-oas2mcp.config.example.yaml

Do not bake API tokens into images.

Development

Run checks:

python -m pytest -q
python -m ruff check .
python -m mypy

Run inspect locally:

safe-oas2mcp inspect examples/todo/openapi.yaml

Run an MCP stdio server:

safe-oas2mcp serve examples/todo/openapi.yaml

Roadmap

• More OpenAPI schema coverage
• Safer confirmation flows
• CI diff command for OpenAPI changes
• Audit log export formats
• Docker image publishing
• PyPI release

Security

Read SECURITY.md before connecting production APIs. The short version: keep auth in environment variables, inspect before serving, start readonly, and use policy overrides sparingly.

License

License is not selected yet.