legacy2mcp

legacy2mcp turns a legacy SOAP/WSDL service, database, or REST API into a working MCP server in 60 seconds. Read-only by default, with every call audit-logged.

Contents

• Install
• Quick start
• How it works
• Why not just write an adapter by hand?
• Point it at your own WSDL
• Point it at your own database
• Point it at your own REST API
• Generate a config automatically
• Common commands
• Client support
• What's handled
• Safety model
• Data flow and privacy
• Use cases
• Real-world usage
• Configuration reference
• Documentation
• Roadmap
• Development · Contributing · License

Install

# Full install (recommended)
pip install "legacy2mcp[ai]"

# Or the identical, scan-only-ready core -- AI-assisted `legacy2mcp init`
# needs no extra package either way, just an API key at runtime; `[ai]`
# above installs nothing extra today, it's just a stable, familiar name
pip install legacy2mcp
# or:  uv tool install legacy2mcp   ·   pipx install legacy2mcp

Also published to the MCP Registry as io.github.bvenkata/legacy2mcp, so registry-aware MCP clients can discover it directly.

Quick start

No API key, no cloning — against a public demo API:

pip install legacy2mcp
legacy2mcp init --rest-url "https://petstore3.swagger.io/api/v3"

Run that from a real terminal and it opens a local test-chat page in your browser automatically — click one of the example questions and see a real response come back from the live API. No AI key needed for this part; it's local keyword matching against the tools it just discovered, just enough to sanity-check that the generated server actually works. (Prefer the raw tool list instead? legacy2mcp inspect --config config.yaml.)

Next, connect it to your AI client for real — see Client support.

Have your own WSDL, REST API, or codebase instead? legacy2mcp init (no flags) walks you through it — see Generate a config automatically. More demos (a local SOAP service, Docker, a WSDL served by raw URL) are listed in examples/.

How it works

flowchart LR
  WSDL["WSDL / XSD"] --> GEN["legacy2mcp<br/>schema generation"]
  DB["DB schema<br/>(allowlisted tables)"] --> GEN
  GEN --> TOOLS["Typed MCP tools<br/>one per operation / table / query"]
  AGENT["AI agent /<br/>MCP client"] -->|tool call| VAL{"schema<br/>validation"}
  TOOLS -. defines .-> VAL
  VAL -->|invalid args| REJ["rejected, never<br/>reaches SOAP/DB"]
  VAL -->|valid and allowed| BACKEND["SOAP endpoint<br/>or database"]
  BACKEND --> RESP["plain JSON<br/>back to the agent"]
  VAL --> LOG[("audit log")]

SOAP:

1. Loads the WSDL with zeep, a mature, widely-used Python SOAP client.
2. For every operation on every port/binding, converts the XSD input type into a JSON Schema (schema/xsd_to_jsonschema.py) — simple types, nested complex types, enums and arrays, recursively, depth-limited for pathological WSDLs.
3. Registers one MCP tool per operation, named <adapter_id>_<OperationName>.
4. On a tool call: validates arguments with jsonschema (schemas use additionalProperties: false), calls the operation via zeep, serializes the response to plain JSON, and writes an audit entry.

DB:

1. Connects with the dialect's driver (psycopg / pyodbc / oracledb, imported lazily) and introspects the live column types for each allowlisted table (adapters/db_dialects.py) into JSON Schema (schema/sql_to_jsonschema.py).
2. Registers select_<table> / insert_<table> per allowlisted table-and-operation, plus query_<name> per named query in config.
3. On a tool call: validates arguments, builds SQL from the allowlisted table/columns (or runs the config-supplied named query) using one dialect-neutral :param placeholder convention, executes it, and writes an audit entry. The LLM never sees or writes SQL text.
4. Operations whose names look like writes are excluded unless allow_write_operations: true.

REST:

1. There's no live schema to introspect a plain REST API from the way there is a WSDL or a DB catalog, so the endpoint list (method, path, typed params) comes from config -- hand-written, or generated by legacy2mcp init's OpenAPI/Swagger discovery or source-code scan.
2. Registers one MCP tool per allowlisted endpoint, named <adapter_id>_<name>.
3. On a tool call: validates arguments, splits them into path/query/body by each param's declared location, substitutes {param} placeholders into the URL, and calls it with requests -- auth applied per the adapter's auth config (basic/bearer/none).
4. Endpoints marked write: true (non-GET by default) are excluded unless allow_write_operations: true.

Why not just write an adapter by hand?

Because a hand-written adapter is a second copy of your system's schema that nobody remembers to update. The first time a WSDL operation's signature shifts or a column changes, your tool's JSON Schema silently drifts from reality — and an LLM calling it finds out by sending arguments that are wrong in a way nothing catches, or by getting a confusing runtime error from deep inside the SOAP/DB client. legacy2mcp builds the schema from the live system every time it starts, so a drifted call fails at validation, before it ever reaches your backend — not after.

Point it at your own WSDL

# config.yaml
server:
  name: my-legacy-mcp

adapters:
  - id: legacy
    type: soap
    config:
      wsdl_url: "https://service.example.com/LegacyService?wsdl"
      auth:
        type: basic
        username: "svc-account"
        password_env: "SERVICE_PASSWORD"   # value read from the environment, never the file
      allow_write_operations: false        # Create*/Update*/Delete*/… stay hidden
      include_operations: ["GetRecord", "GetRecordDetails", "SearchRecords"]

security:
  audit:
    enabled: true
    path: "./legacy-mcp-audit.log"

export SERVICE_PASSWORD=...
legacy2mcp inspect --config config.yaml   # review the generated tools
legacy2mcp run     --config config.yaml   # start the MCP server (stdio)

A production-shaped template with comments lives at examples/soap/config.template.yaml.

Point it at your own database

pip install "legacy2mcp[db-postgres]"   # or db-mssql / db-oracle

# config.yaml
adapters:
  - id: orders
    type: db
    config:
      dialect: postgres             # postgres | mssql | oracle
      dsn_env: "ORDERS_DB_DSN"      # connection string, read from the environment
      allow_write_operations: false # insert_<table> / write: true queries stay hidden
      tables:
        - name: orders
          operations: [select]
          columns: [id, status, total, created_at]   # column allowlist
          filterable_columns: [status]                # equality filters on select_orders
          max_rows: 200
      queries:
        - name: orders_by_status_since
          sql: "SELECT id, status, total FROM orders WHERE status = :status AND created_at >= :since"
          params:
            - { name: status, type: string, required: true }
            - { name: since, type: string, required: true }

export ORDERS_DB_DSN=...
legacy2mcp inspect --config config.yaml   # review the generated tools

Columns are introspected from the live schema at startup, the same way SOAP operation schemas come from the WSDL -- there's nothing to hand-maintain. There is no path from the LLM to arbitrary SQL, ever: it can only call select_<table> / insert_<table> for tables listed under tables:, or a query_<name> tool whose SQL you wrote under queries: -- the LLM supplies only the placeholder values a query's params declare, never SQL text. A production-shaped template lives at examples/db/config.template.yaml.

Point it at your own REST API

There's no WSDL or live database schema to introspect a plain REST/JSON API from, so the rest adapter's endpoint list is explicit config -- write it by hand, or generate a starting point with legacy2mcp init (next section).

# config.yaml
adapters:
  - id: orders
    type: rest
    config:
      base_url: "https://api.example.com"
      auth:
        type: bearer
        token_env: "ORDERS_API_TOKEN"
      allow_write_operations: false
      endpoints:
        - name: get_order
          method: GET
          path: "/orders/{order_id}"
          params:
            - { name: order_id, location: path, type: integer, required: true }
        - name: create_order
          method: POST
          path: "/orders"
          write: true   # stays hidden unless allow_write_operations: true
          params:
            - { name: total, location: body, type: number, required: true }

A production-shaped template lives at examples/rest/config.template.yaml.

Generate a config automatically

legacy2mcp init asks what to point it at, then writes a starting config.yaml for you:

legacy2mcp init

What do you want to point legacy2mcp at?
  1) WSDL URL (SOAP service)
  2) REST API URL (tries OpenAPI/Swagger discovery)
  3) GitHub repo URL or a local path to its source code
Choice [1-3]:

Each also works non-interactively via a flag -- --wsdl-url, --rest-url, --github-url, or --local-path -- for scripting or CI. Only the GitHub/ source-code path can use an LLM, and only to refine what static analysis already found (ambiguous parameter types, read-vs-write classification) -- never a dump of your repo. It needs no extra dependency, just an OpenAI-compatible API key via --llm-api-key-env, or an interactive hidden prompt if you omit that (never written to disk); pass --scan-only to skip it outright and run static-analysis-only, same as not entering a key.

legacy2mcp init --github-url https://github.com/you/your-api --scan-only --out config.yaml

Whichever path you take, review the generated file before running it -- it's marked up with # TODO comments for anything that couldn't be confidently inferred (an unresolved base_url, an unverified param type, which endpoints got classified write: true), and nothing in it is verified against the real backend until you do:

legacy2mcp inspect --config config.yaml   # review the generated tools
legacy2mcp run     --config config.yaml   # start the MCP server

legacy2mcp init also writes a plain-English HTML report next to the config (e.g. config.yaml -> config.html) -- open it in a browser to see, in sentences rather than YAML, what tools the server will expose (every REST endpoint / DB table / SOAP target it found, which ones can change data and are gated behind allow_write_operations, and the review items above). Pass --html-out to change where it's written, or --no-html-report to skip it.

Run init from a real terminal against a config that's already usable (a live --wsdl-url/--rest-url, or a scan that found something concrete) and it also opens a local test-chat page in your browser, with a clickable example question under every discovered tool (generated from that tool's own name and schema, e.g. getPetById -> "get pet by id 4") so you don't have to guess what to type. Click one, or type your own, and it matches it to a discovered tool, calls the real adapter, and shows you the real response. No AI/API key needed for this -- it's local keyword matching against the tool names/descriptions, not an LLM, just enough to sanity-check that the server actually works before you wire up a real MCP client. It's skipped automatically when the config still has TODOs to fill in (nothing to connect to yet), and never opens at all in non-interactive/scripted runs. Pass --no-chat to opt out.

See docs/security.md for exactly what this heuristic does and doesn't guarantee before pointing it at anything real.

Common commands

# Generate a config from a live REST API (tries OpenAPI/Swagger discovery)
legacy2mcp init --rest-url "https://api.example.com" --out config.yaml

# Generate a config from a WSDL URL directly -- no scan needed
legacy2mcp init --wsdl-url "https://service.example.com/Legacy?wsdl" --out config.yaml

# Generate a config by statically scanning a GitHub repo (no AI, no API key)
legacy2mcp init --github-url https://github.com/you/your-api --scan-only --out config.yaml

# Same, with AI-assisted refinement of ambiguous parameter types / read-vs-write
legacy2mcp init --github-url https://github.com/you/your-api --llm-api-key-env OPENAI_API_KEY --out config.yaml

# Review the tools a config generates -- no server started
legacy2mcp inspect --config config.yaml

# Print the tool list as JSON, for scripting or a CI diff check
legacy2mcp inspect --config config.yaml > tools.json

# Start the MCP server (stdio)
legacy2mcp run --config config.yaml

# Teach the AI coding agent working in *this* repo how to drive legacy2mcp --
# writes/updates CLAUDE.md-style context files (Claude Code, Cursor, AGENTS.md,
# GEMINI.md, GitHub Copilot). Safe to re-run; review and commit what it writes.
legacy2mcp install-skill

Client support

"Verified" here means a specific, narrow thing: the exact command + config shape shown below was actually spawned and completed a real MCP initialize handshake over stdio -- not just "MCP should be compatible." For MCP Inspector, the loop was driven further: a real tools/list, a real tools/call, and the resulting audit log entry, all headlessly via the Inspector's own --cli mode. The last badge is what keeps that claim honest over time rather than a one-time snapshot: a CI job (mcp-compatibility.yml) re-runs that same tools/list / tools/call / audit-log loop on every push and fails the build if the server can't start or exposes the wrong tools. Every client below talks to legacy2mcp over stdio only -- there's no HTTP/SSE transport yet (it's on the roadmap, not shipped), so an http://localhost:... MCP URL won't work here.

This repo also ships the checked-in configs themselves -- .mcp.json, .cursor/mcp.json, and .vscode/mcp.json -- pointed at the bundled Petstore demo, so opening this repo in one of these tools gets you a working server with no setup. Copy whichever matches your tool into your own project and point --config at your own config.yaml.

{
  "mcpServers": {
    "legacy2mcp": {
      "command": "uvx",
      "args": ["legacy2mcp", "run", "--config", "/absolute/path/to/config.yaml"]
    }
  }
}

{
  "mcpServers": {
    "legacy2mcp": {
      "command": "uvx",
      "args": ["legacy2mcp", "run", "--config", "/absolute/path/to/config.yaml"]
    }
  }
}

{
  "servers": {
    "legacy2mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": ["legacy2mcp", "run", "--config", "/absolute/path/to/config.yaml"]
    }
  }
}

claude mcp add legacy2mcp -- uvx legacy2mcp run --config /absolute/path/to/config.yaml

npx @modelcontextprotocol/inspector uvx legacy2mcp run --config /absolute/path/to/config.yaml

Passing secrets and troubleshooting: docs/clients.md.

What's handled

See docs/security.md for the full, honest security model — what's covered today and what isn't yet.

Safety model

Data flow and privacy

• No telemetry. legacy2mcp collects no usage data and phones home to nothing. Every network call it makes is one you configured it to make — verified by checking every outbound HTTP call site in the source before writing this sentence.
• Adapter calls go exactly where you pointed them, nowhere else. SOAP calls go to your wsdl_url, DB calls go to your dsn_env connection, REST calls go to your base_url.
• legacy2mcp init's discovery calls are scoped to what you gave it. The WSDL and REST(OpenAPI) paths only ever contact the URL you passed. The GitHub/source-code path clones the repo you specify and parses it locally with ast — nothing from it is ever executed.
• The optional LLM-assist step sends only already-detected, ambiguous fragments — never your repo. It only runs on the GitHub/source-code path of legacy2mcp init, only if you provide an API key, and only sends the specific route names/paths/params the static scan already flagged as ambiguous, not a dump of your source. Skip it entirely with --scan-only.
• Secrets never live in config.yaml. Passwords, DSNs, and API tokens are all referenced by environment-variable name (password_env, dsn_env, token_env) and read at runtime — the YAML stays safe to commit.
• The audit log stays local and is not encrypted at rest. Every tool call is appended as one JSON line to security.audit.path. Arguments are logged as-is — there's no PII redaction; see docs/security.md for the full list of what the audit log does and doesn't do.

Use cases

Real-world usage

In CI/CD — catch WSDL drift before it reaches production

legacy2mcp inspect loads the config, contacts the WSDL, builds every schema, and exits non-zero if anything fails:

- name: Check the WSDL still generates valid MCP tools
  env:
    SERVICE_PASSWORD: ${{ secrets.SERVICE_PASSWORD }}
  run: |
    pip install legacy2mcp
    legacy2mcp inspect --config config/legacy.yaml > tools.json
    git diff --exit-code --no-index tools/legacy.snapshot.json tools.json  # optional: pin the contract

Exit codes:

As a sidecar / long-running MCP server

legacy2mcp run speaks MCP over stdio. Package it with your config using the provided Dockerfile and let your MCP client launch it.

In a data pipeline

Call the same generated, validated tools from your own code via any MCP client library to pull records on a schedule — the audit log records exactly what was fetched.

Configuration reference

SOAP adapter config:

DB adapter config:

REST adapter config:

Security config:

Documentation

Roadmap

Full detail in docs/roadmap.md. The BaseAdapter interface (discover_tools() + invoke()) is the extension point — the server core handles validation, dispatch and audit for any adapter.

Development

pip install -e ".[dev]"
pytest tests/ -v

Tests run against an in-process mock SOAP service and an in-process SQLite-backed stand-in for the DB adapter — no network, no real Postgres/SQL Server/Oracle required. The DB adapter's Postgres/SQL Server/Oracle dialects (db_dialects.py) have their SQL-translation logic covered by driver-free unit tests; connecting to a real instance of each is not part of the default suite.

CI runs the suite on Python 3.10–3.12 (ci.yml). Releases to PyPI and the MCP Registry are tag-triggered — see docs/releasing.md. The demo GIF is regenerated with vhs demo/demo.tape (demo/).

Contributing

Adapters for new legacy systems are the highest-value contribution — implement BaseAdapter and the core handles the rest. See CONTRIBUTING.md for dev setup, how adapters are structured, and PR expectations. This project follows the Code of Conduct. Issues and PRs welcome.

License

Apache 2.0