diff --git a/mcp-server/README.md b/mcp-server/README.md
new file mode 100644
index 0000000..012fafa
--- /dev/null
+++ b/mcp-server/README.md
@@ -0,0 +1,85 @@
+# sap-arch-mcp
+
+MCP server that exposes the **sap-architecture** skill pipeline as tools, so an
+LLM agent can generate SAP Architecture Center-style `.drawio` diagrams using
+the full deterministic pipeline (template scaffolding, icon extraction,
+autofix, validation, corpus scoring) instead of fetching raw files per request.
+
+## Tools exposed
+
+| Tool | Purpose |
+|---|---|
+| `list_templates` | Browse/filter the 71 bundled official SAP templates |
+| `scaffold` | Rank templates against a request, copy best match, return XML + design recipe (mandatory first step) |
+| `extract_icon` | Official BTP service icon → ready-to-paste mxCell (32×32, grid-snapped) |
+| `extract_asset` | Any starter-kit asset: connectors, area shapes, numbers, brand names |
+| `autofix` | Mechanical fixes: grid, hex case, absoluteArcSize, strokeWidth, fonts |
+| `validate` | Full SAP-style validator (bent arrows, palette, overlap, pill verbs...) |
+| `score` | Corpus similarity / SAP-likeness gate (PASS ≥ 90) |
+| `compare` | Fingerprint diff against one named template |
+| `render_png` | Headless PNG export (optional, needs drawio + xvfb) |
+| `get_reference_doc` | Read skill reference docs (gotchas, palette, layout...) |
+
+## Quick start (Docker, recommended)
+
+```yaml
+# docker-compose.yml
+services:
+  sap-arch-mcp:
+    image: python:3.12-slim
+    container_name: sap-arch-mcp
+    restart: unless-stopped
+    ports:
+      - "8600:8600"
+    volumes:
+      - ./sap-architecture:/opt/sap-architecture:ro
+      - sap-arch-work:/work
+    environment:
+      SKILL_DIR: /opt/sap-architecture
+      WORK_DIR: /work
+    command: >
+      sh -c "pip install --quiet 'mcp[cli]' mcpo &&
+             mcpo --host 0.0.0.0 --port 8600 --
+             python3 /opt/sap-architecture/mcp-server/server.py"
+volumes:
+  sap-arch-work:
+```
+
+```bash
+git clone https://git.alexzaw.dev/alexz/sap-architecture.git
+docker compose up -d
+```
+
+Put the container on the same Docker network as OpenWebUI if you want to
+reference it by service name.
+
+## Wire into OpenWebUI
+
+**Admin Settings → Tools → Add Connection** → `http://sap-arch-mcp:8600`
+(or `http://<host>:8600`). The tools appear automatically; mcpo serves
+OpenAPI docs at `/docs`.
+
+## Optional: PNG rendering
+
+Inside the container (or bake into an image):
+
+```bash
+apt-get update && apt-get install -y wget xvfb libgbm1 libasound2 libnss3 libgtk-3-0
+wget -O /tmp/drawio.deb https://github.com/jgraph/drawio-desktop/releases/download/v28.0.6/drawio-amd64-28.0.6.deb
+apt-get install -y /tmp/drawio.deb
+printf '#!/bin/bash\nexec xvfb-run -a /usr/bin/drawio "$@" --no-sandbox --disable-gpu\n' > /usr/local/bin/drawio-headless
+chmod +x /usr/local/bin/drawio-headless
+export DRAWIO_CLI=/usr/local/bin/drawio-headless
+```
+
+Without it, everything except `render_png` works — the validator and scorer
+are the real quality gates.
+
+## Agent workflow (what the LLM should do)
+
+1. `scaffold(request)` → pristine SAP template XML + design recipe
+2. Surgical relabel of the XML (never draw from scratch)
+3. `extract_icon` / `extract_asset` for any new cards
+4. `autofix(xml)` → `validate(xml)` → fix errors → repeat
+5. `score(xml)` → PASS ≥ 90, else `compare` against the source template and restore drift
+6. Deliver `.drawio` (+ `render_png` if requested), narrate the flow below the diagram