legacy2mcp

legacy2mcp

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

---

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

[!NOTE]

legacy2mcp introspects your legacy system live — every WSDL operation, every database table, every REST spec it can find — and builds a real JSON Schema for each tool from it. Every MCP tool call is schema-validated before it reaches your backend, write operations are excluded by default, and every call is audit-logged. No hand-written adapter code, no hand-maintained schemas, no arbitrary SQL from the LLM.

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](https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.bvenkata/legacy2mcp) as io.github.bvenkata/legacy2mcp, so registry-aware MCP clients can discover it directly.

How it works

flowchart LR

WSDL["WSDL / XSD"] --> GEN["legacy2mcp schema generation"] DB["DB schema (allowlisted tables)"] --> GEN GEN --> TOOLS["Typed MCP tools one per operation / table / query"] AGENT["AI agent / MCP client"] -->|tool call| VAL{"schema validation"} TOOLS -. defines .-> VAL VAL -->|invalid args| REJ["rejected, never reaches SOAP/DB"] VAL -->|valid and allowed| BACKEND["SOAP endpoint or database"] BACKEND --> RESP["plain JSON 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 _ .
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_ / insert_ per allowlisted table-and-operation, plus query_ 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 _ .
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 are excluded unless allow_write_operations: true. legacy2mcp init sets that flag by default on non-GET endpoints and on endpoints whose names look like writes; in a hand-written config, the HTTP method alone does not hide an endpoint.

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: "./legacy2mcp-audit.log"

export SERVICE_PASSWORD=...

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