Lesson 3.8
Integrating with Legacy and Data Systems
Patterns for connecting Claude to databases, mainframes, file drops and ageing APIs, with the reliability engineering that keeps a probabilistic component from destabilising deterministic systems.
Enterprise value usually lives in systems that predate the model by decades: relational databases, ERP platforms, batch file exchanges, SOAP services and screens with no API at all. Integrating Claude with them is less about the model and more about disciplined systems engineering. The exam looks for architects who protect the legacy estate from the model and the model from the legacy estate.
The anti-corruption layer
Never let the model talk to a legacy system directly. Put a thin adapter in between that exposes a small number of clean, well-described operations and translates to whatever the legacy system needs. This is the classic anti-corruption layer, and in Claude architectures it takes the form of custom tools or an MCP server.
model <-> tool: get_customer(account_id) <-> adapter <-> SOAP CustomerLookupV3 (12 fields of 140)
The adapter owns authentication, retries, field mapping, pagination and error translation. The model sees a tool with three parameters and a bounded result.
Integration patterns
| Pattern | Use when | Claude-specific note |
|---|---|---|
| Synchronous tool call | Low-latency lookups during a conversation | Cap result size; tool latency becomes user latency |
| Asynchronous job | Operations that take minutes | Tool returns a job ID; the model polls or you continue the conversation later |
| Event-driven | Systems emit events the model should process | Queue consumer calls the model; batch where volume is high |
| Batch extract and load | Nightly transformation of records | Message Batches API; results reconciled by custom_id |
| File drop | Legacy exports to shared storage | Parse with documents or code; validate before model sees it |
| Screen automation | No API exists | Computer use as last resort, with strict sandboxing |
Databases
Giving a model free SQL over a production database is a design failure waiting for an incident. Options in order of preference:
- Fixed tools.
get_orders_for_customer,top_products_by_region. Parameterised queries written by engineers; the model supplies arguments. - Constrained query generation. The model writes SQL against a read-only replica, through a validator that allows only approved tables and clauses, with row and time limits.
- Free-form SQL. Only for analyst-facing tools on sandboxed data, with a human reviewing before any result is acted on.
Provide the schema as context, but curated: table and column descriptions, example values, join hints. A raw schema dump of three hundred tables is noise.
Messy and unstructured inputs
Legacy data is dirty. PDFs scanned sideways, CSVs with shifted columns, free-text fields holding structured data. Claude is good at this, which tempts teams to skip validation. Do not. Use document blocks for PDFs and images, structured outputs for extraction, and a confidence or ambiguity field in the schema so low-confidence records route to a human or a stronger model. Validate extracted values against business rules in code (dates in range, totals that reconcile) before loading.
Reliability engineering
A model in the request path changes the failure profile: latency is variable, errors include rate limits and overloads, and outputs are probabilistic. Protect the deterministic systems around it.
- Timeouts at every hop, consistent with SDK defaults, with streaming for long generations.
- Retries with backoff for rate-limit and server errors, respecting any retry-after guidance; no retries for validation errors.
- Circuit breakers so that a model outage degrades gracefully (queue, fallback response, manual process) rather than cascading into the legacy system.
- Idempotency keys on every write the model can trigger, so retries and duplicate tool calls do not double-post.
- Dead-letter queues for items that fail repeatedly, with human review.
- Rate limiting toward legacy systems, which were never sized for an agent making twenty calls in a second.
Data contracts
Define the schema of what the model produces and what the legacy system accepts as an explicit contract, versioned and tested. Structured outputs enforce the model side; validation code enforces the system side. When the legacy schema changes, the contract test fails before production does.
Reference data and caching
Legacy systems often hold slow-changing reference data: product catalogues, policy tables, code lists. Load it into the prompt's cached prefix or a retrieval index on a schedule, rather than fetching it per request through a fragile tool. Refresh on change events where possible.
Human handoff
Some legacy processes end with a person: an approver, a claims handler, a finance clerk. Design the handoff as a first-class step with a work queue, the model's reasoning summarised for the human, and the ability to send the item back. This is also where you collect labelled data for evaluation.
Exam focus
- Always place an adapter (tools or an MCP server) between the model and legacy systems; the model sees few, bounded operations.
- Prefer fixed, parameterised database tools over model-generated SQL; constrain and sandbox when generation is unavoidable.
- Use structured outputs with confidence fields and code-side validation for messy inputs; route low confidence to humans.
- Timeouts, backoff retries, circuit breakers, idempotency keys and dead-letter queues are mandatory around a probabilistic component.
- Versioned data contracts catch schema drift on both sides before production.
- Reference data belongs in cached context or an index refreshed on schedule, not in per-request tool calls.
Check yourself
5 questions
1.A utility company's billing runs on a mainframe exposed only through a SOAP interface with several hundred operations and cryptic field names. They want Claude agents to look up accounts and raise service orders. Which integration approach is MOST appropriate?
2.An agent creates purchase orders in a legacy ERP through a tool. After a network timeout, the agent retried the call and two identical orders were created. Which design change MOST robustly prevents duplicates?
3.A bank must extract key terms from decades of scanned loan agreements, many with tables, stamps and handwritten annotations. The current pipeline runs an OCR engine and passes the plain text to Claude, which misreads tables and misses annotations. Which change is MOST likely to improve results?
4.An analytics assistant answers business questions by querying a 20-terabyte production data warehouse. The prototype gives the model a tool that executes arbitrary SQL. Risks identified include runaway queries, exposure of sensitive columns, and incorrect joins producing plausible but wrong figures. Which design BEST mitigates these risks while keeping the assistant useful?
5.A Claude-based pipeline enriches customer records and writes them to a legacy CRM via a nightly file import that rejects the whole file if any record violates the fixed schema. The team is struggling with occasional malformed records. Which design MOST reliably meets the legacy system's contract?