legacy2mcp

Convert anything to MCP in 60 seconds. Read-only by default, with every call audit-logged.

Related MCP server: SOAP MCP Server

Quick start

No API key, no cloning — pick whichever matches what you actually have, against live public demo targets:

pip install legacy2mcp

# REST API -- tries OpenAPI/Swagger discovery
legacy2mcp init --rest-url "https://petstore3.swagger.io/api/v3"

# WSDL / SOAP service -- zeep introspects it live, no scan needed
legacy2mcp init --wsdl-url "http://www.dneonline.com/calculator.asmx?WSDL"

# A website with no API docs at all -- crawls it for forms/content
legacy2mcp init --webpage-url "https://legacy2mcp.com/"

Run any one of those from a real terminal and that's the whole thing: it writes config.yaml, opens a local test-chat page with a clickable example question under every discovered tool — click one and see a real response come back from the live source, no AI key needed, just local keyword matching to sanity-check the server works — and prints a ready-to-paste connection snippet for Claude Desktop, Cursor, VS Code, and Claude Code. Wiring it into a real AI client is a copy-paste, not a separate step. (Prefer the raw tool list instead? legacy2mcp inspect --config config.yaml.)

legacy2mcp discover does the same for sources that benefit from a review step first (a Postman collection, a HAR capture, …): write a contract, open the same test chat, print the same connection snippet — one command either way.

Have your own WSDL, REST API, website, 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/.

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.

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) A website with no API docs at all (crawls it for forms/content)
  4) GitHub repo URL or a local path to its source code
Choice [1-4]:

Each also works non-interactively via a flag -- --wsdl-url, --rest-url, --webpage-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, a website (--webpage-url), and a repo it can scan -- all of those go straight to a config, no separate step needed. 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, or queues you already know about -- 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

A website can go through discover --webpage-url too (see below) if you want to review the contract before anything gets built -- init --webpage-url runs the identical crawl, it just doesn't pause there.

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.

Run that same command from a real terminal, though, and discover doesn't stop at the contract: if the contract has anything invocable in it (not every source does yet -- see below), it also writes a runnable config.yaml, opens the same no-API-key test-chat page init can auto-launch, and prints the same ready-to-paste MCP client JSON -- discover, try it, and get the connection snippet, in the one command you already ran. Pass --no-chat to skip that and just get the contract (the default in non-interactive/CI runs already), or --no-write-config to skip only the config.yaml write.

Prefer to review the contract first before anything gets built or run? Skip straight to either step yourself instead:

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

demo is the same "try it" step discover can auto-launch, just callable on its own (also works from an existing --config config.yaml, not only a contract) -- it saves a standalone chat.html pointing at the server it just started (opened automatically unless --no-open), and prints the client JSON once a config exists to point it at. 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 a legacy web app or content site with no API docs at all -- just a URL. It crawls same-site pages from there (--max-pages/--max-depth bound it, default 25 pages / depth 2, never leaving the starting host), turning every <form> into an operation (a <select>'s options, or a shared-name radio/checkbox group, become an enum) and every form-less page with real content into a read-only "get this page" tool. No JavaScript is executed and nothing is ever submitted; non-GET forms get a note to confirm the backend accepts a JSON body (the REST adapter always sends one, even though a real browser would POST application/x-www-form-urlencoded). Same lowest-confidence posture as --har-file -- but unlike every other discover source, base_url fills in automatically (it's the host just fetched), so the test-chat page opens right away. Full crawl mechanics: docs/security.md.

• 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. Same reason discover's auto-demo (above) has nothing to launch for a contract made up only of those -- it says so and just exits with the contract already written, rather than failing the whole command.

• 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

# Print the installed legacy2mcp version
legacy2mcp --version

# 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 from a website with no API docs at all -- crawls it
legacy2mcp init --webpage-url "https://your-legacy-app.example.com" --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 a source before generating anything -- a Postman collection, OpenAPI
# file, HAR capture, stored-procedure catalog, or queue description
legacy2mcp discover --postman-file my-collection.json --out contract.yaml

# Try a config or contract in a chat page right now, no separate init step
legacy2mcp demo --from-contract contract.yaml
legacy2mcp demo --config 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

# Show only one exact tool name
legacy2mcp inspect --config config.yaml --tool legacy_get_order

# 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.

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

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

If you installed with pip/pipx instead of uv, use "command": "legacy2mcp" and drop the first element of args.

Project-local (.cursor/mcp.json) or global (~/.cursor/mcp.json):

{
  "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

Add --scope project to write a shared .mcp.json for your team (keep secrets out of it); check with claude mcp list.

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

Opens a local web UI: connect to the server, confirm tools are listed, run one read-only tool, and check legacy2mcp-audit.log for the matching entry. That exact loop -- tool discovery, one real call, the audit log it produces -- is what the "Tested with MCP Inspector" badge above is actually backed by, driven headlessly through the Inspector's own --cli mode rather than just opened in a browser.

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