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
• Discover a legacy interface before generating a server
• Teach your AI coding agent about legacy2mcp
• 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.

Discover a legacy interface before generating a server

init covers a live WSDL, a live REST URL, and a repo it can scan. For everything else -- a Postman collection someone already built, an OpenAPI spec file sitting in a repo with no server running yet, a database's stored-procedure catalog, a HAR capture of real traffic, queues you already know about, or a plain webpage with no API docs at all -- there's an explicit step first:

legacy2mcp discover --postman-file my-collection.json --out contract.yaml
legacy2mcp discover --openapi-file spec.yaml --out contract.yaml
legacy2mcp discover --har-file traffic.har --out contract.yaml
legacy2mcp discover --stored-procs --db-dialect postgres --db-dsn-env LEGACY_DB_DSN --out contract.yaml
legacy2mcp discover --queue-config queues.yaml --out contract.yaml
legacy2mcp discover --webpage-url "https://your-legacy-app.example.com/some-page" --out contract.yaml

Each writes a Legacy Interface Contract (contract.yaml): every operation's inputs, outputs, enums, error codes, whether it reads or writes, and a confidence level -- high for a live schema/catalog, medium for a curated artifact like a Postman collection, low for anything inferred from sampled traffic -- plus needs_review flags and notes on anything uncertain. Review it like you'd review config.yaml's # TODOs, then turn it into a runnable server:

legacy2mcp init --from-contract contract.yaml --out config.yaml

Or skip straight to trying it, no config.yaml step needed:

legacy2mcp demo --from-contract contract.yaml

That starts the same no-API-key test-chat server init can auto-launch, and saves a standalone chat.html pointing at it -- opened automatically unless you pass --no-open. The command has to keep running (Ctrl+C to stop) for that page to work; it's a thin client page with no backend of its own, so the real HTTP calls still have to be made by something, same reason the browser can't just open a config file and call a REST API directly.

A few things worth knowing:

• No raw secret is ever written into a contract. A Postman collection's saved bearer token, a HAR capture's Authorization/Cookie header values -- none of it gets persisted; only a note that auth was present, for you to configure yourself. The one controlled exception is a small, non-sensitive-looking enum (e.g. a status field that only ever took a handful of values across enough samples to mean something) -- see docs/security.md.
• For --har-file, legacy2mcp never drives a capture proxy itself -- point it at a HAR produced by anything: your browser devtools' "Export HAR", Postman's own traffic capture, or mitmproxy's built-in exporter (mitmdump --set hardump=out.har, or "Export as HAR" in the GUI). This is the lowest-confidence source (inferred from whatever was sampled, not a declared contract) -- every operation comes back flagged for review.
• --webpage-url is for the legacy web app -- or the plain content site -- that has no OpenAPI spec, no Postman collection, and nobody around who remembers capturing a HAR, just a URL in a browser. It crawls same-site pages starting there (following <a href> links, bounded by --max-pages/--max-depth, default 25 pages / depth 2) and turns every <form> it finds into an operation (method/action become the REST method/path, each <input>/<select>/<textarea> a typed field -- a <select>'s options, or a group of radio/checkbox inputs sharing a name, become an enum), plus one read-only "get this page" tool per page that has no form but does have real text content -- calling that tool returns the page's extracted text, not a structured API response. No JavaScript is executed, no link off the starting site's host is ever followed, and no form is ever submitted -- every page is a single GET plus HTML parsing. Same lowest-confidence posture as --har-file, with one extra caveat on form operations: HTML forms normally POST as application/x-www-form-urlencoded, but the REST adapter always sends a JSON body, so every non-GET form gets a note to double-check that the backend actually accepts JSON before you rely on it. Unlike every other discover source, legacy2mcp already knows the real base_url here (it's the host it just fetched) -- so init --from-contract on a webpage-sourced contract fills that in automatically instead of leaving REPLACE_ME_BASE_URL, and the no-API-key test-chat page (see Quick start) opens right away with real example questions for whatever your site turned into tools.
• Stored procedures and queue descriptions are documented, not runnable yet. --stored-procs and --queue-config still produce real contract entries -- there's no adapter to actually call either today (see docs/roadmap.md), so init --from-contract skips them with a clear TODO rather than pretending they work.
• Every generated server also gets a describe_capabilities tool for free -- a connected agent can call it to ask "what can this system do?" (every tool's description, side effect, confidence, required fields, known error codes) before calling anything for real.
• --out contract.html writes a human-readable report instead of the plain YAML -- the same operations, as a table, in your browser. It's still a valid --from-contract/demo --from-contract input: the full contract is embedded in the page (in a <script type="application/json"> tag), not just summarized for reading.

Teach your AI coding agent about legacy2mcp

The sections above are about the MCP servers legacy2mcp produces. This one is different: it's for when an AI coding agent (Claude Code, Cursor, Codex CLI, Gemini CLI, GitHub Copilot, ...) is helping you build the integration in the first place, and you want it to already know how.

legacy2mcp install-skill

This writes short, command-first legacy2mcp instructions directly into the current repo's own agent context files — a Claude Code slash command (.claude/commands/legacy2mcp.md), a Cursor rule (.cursor/rules/legacy2mcp.mdc), and a ## legacy2mcp section appended (or updated in place) in AGENTS.md, GEMINI.md, and .github/copilot-instructions.md. The agent then already knows the core workflow — which init flag fits which source, review the # TODOs before trusting a generated config, check inspect before running anything live — without you re-explaining it every session. It's idempotent: re-running it replaces its own section rather than duplicating it, so it's safe to run again after an upgrade. Review what it writes and commit it so your whole team gets the same instructions (this repo does exactly that — see AGENTS.md).

There's also a standalone SKILL.md in this repo, written to the open Agent Skills standard — the same know-how in a form marketplaces like Agensi can list independently of any particular repo, for agents that discover skills that way instead.

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
# (see "Teach your AI coding agent about legacy2mcp" above)
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.
• legacy2mcp discover reads local files, except --stored-procs. Postman/OpenAPI/HAR/queue sources never touch the network — they read a file you gave it. --stored-procs connects to the DSN in the env var you named, the same way the db adapter does, only to read the procedure/function catalog. No raw secret or sampled value is ever written into the resulting contract.yaml — see docs/security.md.
• 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