Balchandar · Balchandar · Feb 13, 2026 · Feb 13, 2026
diff --git a/README.md b/README.md
@@ -106,6 +106,80 @@ intentusnet retrieve <execution-id>
 
 ---
 
+## Deterministic MCP Gateway
+
+Wrap **any** MCP server with the IntentusNet Gateway — zero changes to the server or client.
+
+```
+MCP Client  →  IntentusNet Gateway  →  Existing MCP Server
+                      ↓
+              WAL + Index + Data
+```
+
+### Why
+
+MCP servers process tool calls but don't record them. When something goes wrong, there's no audit trail, no replay, and no way to prove what happened. The gateway adds these capabilities transparently.
+
+### 5-Minute Example
+
+**1. Start an MCP server** (included example):
+
+```bash
+python examples/basic-mcp-server/server.py
+```
+
+**2. Start the gateway:**
+
+```bash
+intentusnet gateway --http http://localhost:5123
+```
+
+**3. Send a request through the gateway:**
+
+```bash
+curl -s http://localhost:8765 -X POST \
+  -H "Content-Type: application/json" \
+  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"add","arguments":{"a":17,"b":25}}}' \
+  | python -m json.tool
+```
+
+**4. List recorded executions:**
+
+```bash
+intentusnet executions
+```
+
+**5. Replay an execution** (WAL playback, no re-execution):
+
+```bash
+intentusnet replay <execution-id>
+```
+
+### Gateway CLI
+
+| Command | Description |
+|---------|-------------|
+| `intentusnet gateway --wrap <cmd>` | Wrap a stdio MCP server |
+| `intentusnet gateway --http <url>` | Proxy to an HTTP MCP server |
+| `intentusnet replay <id>` | Fast replay from WAL |
+| `intentusnet executions` | List all recorded executions |
+| `intentusnet status` | Gateway status + WAL integrity |
+
+### What Gets Recorded
+
+Each tool call is persisted with: execution ID, deterministic seed, request/response hashes, WAL entries (execution start + end), timing metadata, and tool name.
+
+### Current Limitations
+
+- Streaming: simple pass-through (not recorded at stream level)
+- No deterministic re-execution yet (replay returns stored response only)
+- No undo or rollback
+- No dashboard UI
+
+Full documentation: [examples/basic-mcp-server/README.md](examples/basic-mcp-server/README.md)
+
+---
+
 ## Why IntentusNet
 
 Modern LLM systems are observable, but **not debuggable**.

diff --git a/docs-site/docs/architecture/overview.mdx b/docs-site/docs/architecture/overview.mdx
@@ -252,6 +252,75 @@ class AgentResponse:
 └─────────────────────────────────────────┘
 ```
 
+## MCP Gateway Architecture
+
+The Deterministic MCP Gateway operates as a transparent proxy layer between MCP clients and servers:
+
+```mermaid
+flowchart TB
+    subgraph Client["MCP Client"]
+        CL[Client Application]
+    end
+
+    subgraph Gateway["IntentusNet Gateway"]
+        direction TB
+        PX[MCP Proxy]
+        INT[Execution Interceptor]
+        WAL[Gateway WAL]
+        IDX[Execution Index]
+        DS[Data Store]
+    end
+
+    subgraph Server["MCP Server"]
+        SRV[Tool Server]
+    end
+
+    CL -->|MCP JSON-RPC| PX
+    PX --> INT
+    INT --> WAL
+    INT --> IDX
+    INT --> DS
+    PX -->|Forward unchanged| SRV
+    SRV -->|Response| PX
+    PX -->|Response unchanged| CL
+```
+
+### Gateway Data Flow
+
+1. MCP client sends JSON-RPC request to the gateway
+2. Gateway intercepts tool-related methods (`tools/call`, `tools/list`, etc.)
+3. Execution interceptor writes `execution_start` to WAL (durability boundary)
+4. Request is forwarded to the MCP server unmodified
+5. Response is received from the MCP server
+6. Execution interceptor writes `execution_end` to WAL
+7. Full execution data is persisted to the data store
+8. Execution index is updated
+9. Response is returned to the client unmodified
+
+The gateway adds no protocol changes. Clients and servers are unaware of its presence.
+
+### Gateway Components
+
+| Component | Purpose |
+|-----------|---------|
+| **MCP Proxy** | Transparent stdio/HTTP relay |
+| **Execution Interceptor** | Records tool calls with WAL entries |
+| **Gateway WAL** | Append-only, hash-chained, fsync-safe log |
+| **Execution Index** | Fast O(1) lookup by execution ID |
+| **Data Store** | Full execution data (request, response, seed) |
+
+### Fast Replay
+
+Replay reads from the WAL and data store — no MCP server is contacted:
+
+```mermaid
+flowchart LR
+    CLI[intentusnet replay] --> IDX[Execution Index]
+    IDX --> DS[Data Store]
+    DS --> WAL[WAL Entries]
+    WAL --> RES[Replay Result]
+```
+
 ## Extension Points
 
 IntentusNet is extensible at multiple points:

diff --git a/docs-site/docs/cli/overview.mdx b/docs-site/docs/cli/overview.mdx
@@ -33,6 +33,16 @@ intentusnet --version
 | [`intentusnet estimate`](./estimate) | Estimate execution cost/resources |
 | [`intentusnet validate`](./validate) | Validate envelope or policy       |
 
+### MCP Gateway Commands
+
+| Command | Description |
+| ------- | ----------- |
+| `intentusnet gateway --wrap <cmd>` | Start stdio gateway wrapping an MCP server |
+| `intentusnet gateway --http <url>` | Start HTTP gateway proxying to an MCP server |
+| `intentusnet executions` | List all gateway-recorded executions |
+| `intentusnet replay <execution-id>` | Fast replay from WAL (no re-execution) |
+| `intentusnet status` | Show gateway status and WAL integrity |
+
 ## Global Options
 
 All commands support these global options:

diff --git a/docs-site/docs/cli/replay.mdx b/docs-site/docs/cli/replay.mdx
@@ -239,7 +239,64 @@ done
 | 10 | Record not found |
 | 11 | Not replayable / hash mismatch |
 
+## MCP Gateway Replay (WAL Playback)
+
+When used with the MCP Gateway, `intentusnet replay` reads from the gateway's WAL and returns the stored MCP response with full execution metadata.
+
+```bash
+intentusnet replay <execution-id>
+```
+
+Output includes:
+
+- Original request and response (with hashes)
+- Deterministic seed (sequence, timestamp, random seed)
+- WAL entry count
+- Timing metadata
+- Tool name and MCP method
+
+This is a **WAL playback** operation. No MCP server is contacted and no tool is re-executed. The response is exactly what was recorded at execution time.
+
+### JSON Output
+
+```bash
+intentusnet replay <execution-id> --output json
+```
+
+```json
+{
+  "execution_id": "a1b2c3d4-...",
+  "status": "completed",
+  "method": "tools/call",
+  "tool_name": "add",
+  "request_hash": "7f83b165...",
+  "response_hash": "3a7bd3e2...",
+  "deterministic_seed": {
+    "sequence_number": 1,
+    "timestamp_iso": "2024-01-15T10:30:00Z",
+    "random_seed": "a3f7c2b1...",
+    "process_id": 12345
+  },
+  "response": {"jsonrpc": "2.0", "id": 1, "result": {...}},
+  "wal_entries": [...],
+  "warning": "This is the RECORDED response. No MCP tool was re-executed."
+}
+```
+
+### Gateway Replay vs Runtime Replay
+
+| Aspect | Gateway Replay | Runtime Replay |
+|--------|---------------|----------------|
+| Source | Gateway WAL + data store | Execution records |
+| Scope | MCP tool calls | IntentusNet intent executions |
+| Data | Full MCP request/response | IntentEnvelope + AgentResponse |
+| Seed | Deterministic seed captured | Execution fingerprint |
+| Command | `intentusnet replay <id>` | `intentusnet retrieve <id>` |
+
+Both are lookup operations. Neither re-executes code.
+
 ## See Also
 
 - [`intentusnet inspect`](./inspect) — View execution details
 - [Replayability Guarantees](../guarantees/replayability) — Replay semantics
+- [MCP Gateway](../mcp/gateway) — Deterministic MCP Gateway details
diff --git a/docs-site/docs/getting-started/quickstart.mdx b/docs-site/docs/getting-started/quickstart.mdx
@@ -232,8 +232,107 @@ if is_ok:
 | Recording | Automatic capture of execution |
 | Replay | Return recorded output |
 
+---
+
+## MCP Gateway Quickstart
+
+Already have an MCP server? Wrap it with the IntentusNet Gateway in 5 minutes — no server changes required.
+
+### Step 1: Start an MCP Server
+
+Use the included example server (or any existing MCP server):
+
+```bash
+python examples/basic-mcp-server/server.py
+```
+
+```
+Basic MCP server running on http://localhost:5123
+Tools available: add(a, b)
+```
+
+### Step 2: Start the Gateway
+
+In a second terminal:
+
+```bash
+intentusnet gateway --http http://localhost:5123
+```
+
+The gateway wraps the server transparently. No protocol changes.
+
+### Step 3: Send a Request Through the Gateway
+
+```bash
+curl -s http://localhost:8765 -X POST \
+  -H "Content-Type: application/json" \
+  -d '{
+    "jsonrpc": "2.0",
+    "id": 1,
+    "method": "tools/call",
+    "params": {
+      "name": "add",
+      "arguments": {"a": 17, "b": 25}
+    }
+  }' | python -m json.tool
+```
+
+Response (identical to calling the server directly):
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "result": {
+    "content": [{"type": "text", "text": "17 + 25 = 42"}]
+  }
+}
+```
+
+### Step 4: See Recorded Executions
+
+```bash
+intentusnet executions
+```
+
+```
+EXECUTION ID                             STATUS       METHOD          TOOL        DURATION
+--------------------------------------------------------------------------------------------
+a1b2c3d4-e5f6-7890-abcd-ef1234567890     completed    tools/call      add         12ms
+```
+
+### Step 5: Replay the Execution
+
+```bash
+intentusnet replay <execution-id>
+```
+
+Returns the stored response from WAL — no MCP server contacted, no tool re-executed.
+
+### What You Should See
+
+After completing all steps:
+
+- **Gateway active** — Requests pass through transparently
+- **Execution recorded** — Every tool call captured with hashes and timing
+- **Replay works** — Stored response returned from WAL without re-execution
+- **Deterministic seed captured** — Prepares for future deterministic replay
+
+### How It Works
+
+```
+MCP Client (curl)  →  IntentusNet Gateway (8765)  →  MCP Server (5123)
+                              ↓
+                    WAL + Index + Data Store
+```
+
+The gateway intercepts tool calls, records them to an append-only WAL with hash chaining, captures deterministic seeds, and indexes executions for fast lookup and replay. The MCP server and client are completely unmodified.
+
+---
+
 ## Next Steps
 
 - [Walkthrough](./walkthrough) — Complete example with policy filtering and crash recovery
+- [MCP Gateway](../mcp/gateway) — Deterministic MCP Gateway details
 - [CLI Reference](../cli/overview) — Command-line tools for inspection and replay
 - [Guarantees](../guarantees/overview) — Understand what IntentusNet guarantees