diff --git a/AGENTS.md b/AGENTS.md
index 05e5dc1..91048aa 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,13 +1,19 @@
 # Phantom — Agent Instructions
 
-Phantom is a Rust-based API observability tool that captures HTTP/HTTPS traffic via a MITM proxy (or LD_PRELOAD agent on Linux) and presents it in a terminal UI or streams it as JSON Lines. It is organized as a Cargo workspace of five library crates plus one binary.
+Phantom is a Rust-based API observability tool that captures HTTP/HTTPS traffic via a MITM proxy (or LD_PRELOAD agent on Linux) and presents it in a terminal UI, streams it as JSON Lines, serves it to AI coding agents over MCP (`phantom mcp`), or answers offline queries (`phantom list/get/search`). It is organized as a Cargo workspace of five library crates plus one binary.
 
 ---
 
 ## Project Layout
 
 ```
-src/main.rs                  # Binary entry point: CLI parsing, component wiring, child-process spawning
+src/main.rs                  # Binary entry point: subcommand dispatch, exit-code mapping, store opening
+src/cli.rs                   # clap derive: Cli, Commands (run/list/get/search/stats/clear/mcp), arg structs
+src/runner.rs                # Child-process spawning: proxy env vars, Node/PHP/Java injection, TempScript
+src/commands/run.rs          # `phantom run`: proxy/ldpreload capture, TUI/JSONL output loops
+src/commands/query.rs        # `phantom list/get/search/stats/clear`: offline store queries
+src/mcp/server.rs            # `phantom mcp`: rmcp stdio server, 7 MCP tools
+src/mcp/session.rs           # MCP capture sessions: CaptureManager, child lifecycle, trace pump
 crates/
   phantom-core/              # Domain types, traits, error types — no I/O
   phantom-storage/           # Fjall LSM-tree TraceStore implementation
@@ -18,6 +24,8 @@ tests/
   proxy_node_integration.rs           # Integration tests: Node.js proxy capture (HTTP + HTTPS)
   proxy_php_integration.rs            # Integration test: PHP curl via proxy backend (HTTP + HTTPS)
   proxy_php_ldpreload_integration.rs  # Integration test: PHP curl via ldpreload backend (Linux only)
+  cli_query_integration.rs            # Integration tests: exit-code propagation, JSONL purity, list/get/clear, store lock UX
+  mcp_stdio_integration.rs            # Integration test: MCP server via raw JSON-RPC over stdio
   apps/node-app/             # Test Node.js app (client.js, client-alts.js, proxy-preload.js)
   apps/php-app/              # Test PHP app (client.php, curl extension, PHP 5.3-compatible)
   integration/               # Shell-based integration tests
@@ -43,11 +51,14 @@ phantom-agent          (standalone dylib, no workspace deps)
 cargo build                          # Debug build
 cargo build --workspace --all-targets --all-features  # Full build (matches CI)
 cargo build --release                # Release build
-cargo run                            # Run proxy on default port 8080
-cargo run -- --port 9090             # Run with custom port
-cargo run -- -- node app.js          # Trace a Node.js app (proxy-preload.js auto-injected)
-cargo run -- --output jsonl -- node app.js  # Stream JSONL and exit when child exits
-cargo run -- --backend ldpreload --agent-lib ./target/debug/libphantom_agent.so -- curl http://example.com
+cargo run -- run                     # Run proxy on default port 8080 (TUI)
+cargo run -- run --port 9090         # Run with custom port
+cargo run -- run -- node app.js      # Trace a Node.js app (proxy-preload.js auto-injected)
+cargo run -- run --output jsonl -- node app.js  # Stream JSONL; exits with the child's exit code
+cargo run -- run --backend ldpreload --agent-lib ./target/debug/libphantom_agent.so -- curl http://example.com
+cargo run -- list --status 5xx --since 10m      # Query stored traces (offline)
+cargo run -- get <SPAN_ID>           # One trace, pretty JSON
+cargo run -- mcp                     # MCP server over stdio (for AI coding agents)
 cargo check                          # Fast type/borrow check (no codegen)
 cargo clippy --workspace --all-targets --all-features -- -D warnings  # Lint (CI-exact)
 cargo fmt --all                      # Format all code
@@ -65,18 +76,40 @@ make test     # cargo test --workspace --all-targets --all-features
 make check    # fmt + clippy + build + test (full CI locally)
 ```
 
-### CLI Options
+### CLI Structure
+
+`phantom <SUBCOMMAND>` with two global flags: `-d, --data-dir <DIR>` (default `~/.local/share/phantom/data`) and `-q, --quiet` (suppress stderr status lines).
+
+| Subcommand | Purpose |
+|---|---|
+| `run` | Capture traffic; optionally spawn and trace a command (`-- <CMD>`) |
+| `list` | Query stored traces (newest first) with filters |
+| `get <SPAN_ID>` | One trace as pretty JSON; exit 1 when not found |
+| `search <PATTERN>` | Shorthand for `list --url <PATTERN>` |
+| `stats` | `{"total_traces": N, "data_dir": "..."}` |
+| `clear --yes` | Delete all traces (refuses without `--yes`) |
+| `mcp` | MCP server over stdio (see MCP Server section) |
+
+**`phantom run` flags:**
 
 | Flag | Default | Description |
 |---|---|---|
 | `-b, --backend <BACKEND>` | `proxy` | `proxy` (MITM, cross-platform) or `ldpreload` (Linux only, HTTP + HTTPS) |
-| `-o, --output <OUTPUT>` | `tui` | `tui` (interactive) or `jsonl` (stdout stream, auto-exits with child) |
+| `-o, --output <OUTPUT>` | `tui` | `tui` (interactive) or `jsonl` (stdout stream; exits with the child's exit code) |
 | `-p, --port <PORT>` | `8080` | Proxy capture port |
 | `--insecure` | off | Disable TLS verification for backend servers (self-signed certs) |
-| `-d, --data-dir <DIR>` | `~/.local/share/phantom/data` | Storage directory |
 | `--agent-lib <PATH>` | — | Path to `libphantom_agent.so` (ldpreload backend) |
+| `--fault <SPEC>` | — | Fault injection rules (repeatable) |
+| `--max-body <N>` | `0` (unlimited) | Truncate bodies in JSONL output to N bytes |
+| `--headers-only` | off | Omit bodies from JSONL output (sizes still reported) |
 | `-- <CMD>` | — | Command to spawn and trace automatically |
 
+**Query flags (`list`/`search`):** `--method <M>` (repeatable), `--status <404|4xx|400-499>`, `--url <SUBSTR>` (list only), `--since/--until <RFC3339 | relative like "10m">`, `--trace-id <HEX32>`, `--limit` (50), `--offset`, `--format <jsonl|json|table>`, `--max-body` (1024, 0 = unlimited), `--headers-only`, `--redact-header <NAME>` (repeatable).
+
+**Exit codes:** `phantom run -o jsonl -- <CMD>` exits with the child's exit code (Unix signal deaths map to 128+signal). In jsonl mode a machine-readable summary line goes to stderr on exit: `{"event":"exit","child_exit_code":N,"traces_captured":N}`. All diagnostics go to stderr; stdout is pure JSONL/JSON.
+
+**Store lock:** `FjallTraceStore::open` takes an advisory `flock` on `<data-dir>/phantom.lock` (fjall itself does not lock across processes). Only one phantom process can use a data dir at a time; query subcommands print a hint when the store is locked by a running `phantom run`/`mcp` — query through the MCP server in that case.
+
 For any spawned command other than Node.js, phantom sets `HTTP_PROXY`/`HTTPS_PROXY` (and lowercase variants) and clears `NO_PROXY`/`no_proxy`, so libcurl-based clients (curl, PHP's curl extension, etc.) are proxied for both schemes without an inherited `no_proxy` exclusion list defeating capture. Node.js is excluded from this because its injected `proxy-preload.js` already handles HTTPS itself — setting `HTTPS_PROXY` there would make libraries like axios configure a second, conflicting proxy agent from the env var.
 
 ---
@@ -144,11 +177,41 @@ When `--output jsonl` is used, one JSON object is written per line to stdout. Al
 | `protocol_version` | string | HTTP version string, e.g. `"HTTP/1.1"` |
 | `request_headers` | object | Lower-cased header names → values |
 | `response_headers` | object | Lower-cased header names → values |
-| `request_body` | string? | UTF-8 decoded body; omitted when empty |
-| `response_body` | string? | UTF-8 decoded body; omitted when empty |
+| `request_body` | string? | UTF-8 decoded body; omitted when empty or `--headers-only` |
+| `response_body` | string? | UTF-8 decoded body; omitted when empty or `--headers-only` |
+| `request_body_bytes` | number? | Original request body size in bytes; present when a body existed |
+| `response_body_bytes` | number? | Original response body size in bytes; present when a body existed |
+| `request_body_truncated` | bool? | Present (`true`) when `--max-body` truncated the request body |
+| `response_body_truncated` | bool? | Present (`true`) when `--max-body` truncated the response body |
 | `source_addr` | string? | Client socket address, e.g. `"127.0.0.1:54321"` |
 | `dest_addr` | string? | Server socket address, e.g. `"93.184.216.34:443"` |
 
+The same schema (`phantom_core::view::TraceView`, rendered via `RenderOptions`) is used by `phantom run --output jsonl`, the query subcommands, and MCP tool results.
+
+---
+
+## MCP Server (`phantom mcp`)
+
+`phantom mcp` serves the Model Context Protocol over stdio using the official `rmcp` SDK, so AI coding agents can drive captures and query traces as tools. One process hosts both capture and queries, so the store lock is never contended. Register with Claude Code:
+
+```sh
+claude mcp add phantom -- phantom mcp
+# or with a custom data dir:
+claude mcp add phantom -- phantom --data-dir ./traces mcp
+```
+
+| Tool | Purpose |
+|---|---|
+| `start_capture` | Spawn a command through the MITM proxy (Node/PHP/Java HTTPS injection included) or start a proxy-only session; auto-assigns a free port when none given. Returns `session_id`, `port`, `proxy_url`, `pid` |
+| `capture_status` | Child state (`running`/`exited` + `exit_code`), live `trace_count`; one session or all. Poll this after `start_capture` |
+| `stop_capture` | Kill a still-running child, stop the proxy, return the final status |
+| `list_traces` | Filters: `method`, `status` (`"404"`/`"4xx"`/`"400-499"`), `url_contains`, `since_ms`/`until_ms`, `trace_id`, `limit` (20)/`offset`; bodies default to 256 bytes (`max_body`, 0 = unlimited), `headers_only` |
+| `get_trace` | Full detail by `span_id`; bodies default to 4096 bytes |
+| `get_stats` | Approximate total trace count, data dir, active session count |
+| `clear_traces` | Deletes all traces; requires `confirm: true` |
+
+Sensitive headers (`authorization`, `proxy-authorization`, `cookie`, `set-cookie`) are redacted in tool output by default (`redact_sensitive_headers: false` to disable). Sessions keep capturing after their child exits, until `stop_capture`; all sessions are torn down when the MCP client disconnects (a SIGKILL of the server can orphan traced children).
+
 ---
 
 ## Testing
@@ -185,6 +248,12 @@ cargo test --test proxy_php_integration -- --nocapture
 # PHP curl ldpreload integration test (Linux only; builds phantom-agent on demand)
 cargo build -p phantom-agent
 cargo test --test proxy_php_ldpreload_integration -- --nocapture
+
+# CLI query / exit-code / lock UX integration tests (requires curl for the capture parts)
+cargo test --test cli_query_integration -- --nocapture
+
+# MCP server smoke test (raw JSON-RPC over stdio; requires curl for the capture round-trip)
+cargo test --test mcp_stdio_integration -- --nocapture
 ```
 
 ### Node.js Integration Tests (`tests/proxy_node_integration.rs`)
@@ -197,7 +266,7 @@ cargo test --test proxy_php_ldpreload_integration -- --nocapture
 Both tests:
 - Auto-skip if `node` or `npm` is not in `PATH`.
 - Start in-process Rust mock backends (HTTP + HTTPS with self-signed cert).
-- Run `phantom --output jsonl --insecure -- node <script>.js`.
+- Run `phantom run --output jsonl --insecure -- node <script>.js`.
 - Parse JSONL output and assert method, path, status code per trace.
 - Identify traces by `x-phantom-client` custom header in `request_headers`.
 
@@ -210,6 +279,15 @@ Both tests:
 
 Both auto-skip if `php` (or its curl extension) is not available. `client.php` (shared by both tests, `tests/apps/php-app/client.php`) is written in PHP 5.3-compatible syntax and takes an optional `PHANTOM_TEST_INSECURE` env var to disable curl peer verification for the ldpreload test, where there is no phantom CA to trust against the mock backend's self-signed cert.
 
+### CLI and MCP Integration Tests
+
+| Test | Description |
+|------|-------------|
+| `tests/cli_query_integration.rs` | `run` propagates the child's exit code; stdout is pure JSONL; `list`/`get`/`search`/`stats`/`clear` filters, `--max-body` truncation flags, store-lock hint |
+| `tests/mcp_stdio_integration.rs` | Speaks raw newline-delimited JSON-RPC to `phantom mcp`: handshake, `tools/list`, a traced curl capture via `start_capture`, `capture_status` polling, `list_traces`/`get_trace`, clean shutdown on stdin EOF |
+
+Both auto-skip their capture parts if `curl` is not in `PATH`.
+
 ### Run a Single Unit Test Function
 
 ```sh
@@ -346,8 +424,16 @@ pub enum StorageError {
 
 | File | Purpose |
 |---|---|
-| `src/main.rs` | CLI parsing (`clap` derive), backend/output mode selection, child-process spawning, JSONL output loop |
+| `src/main.rs` | Subcommand dispatch, exit-code mapping, store opening (with lock hint for query commands) |
+| `src/cli.rs` | `clap` derive: `Cli`, `Commands`, per-subcommand arg structs, `GlobalOpts` |
+| `src/runner.rs` | Child-process spawning: proxy env vars, Node/PHP/Java injection assets, `TempScript`, `wait_for_proxy` |
+| `src/commands/run.rs` | `phantom run`: proxy/ldpreload capture wiring, JSONL output loop with exit-status propagation |
+| `src/commands/query.rs` | `phantom list/get/search/stats/clear`, `--since/--until` parsing, table/json/jsonl output |
+| `src/mcp/server.rs` | `PhantomMcp`: rmcp `#[tool_router]` with the 7 MCP tools, `run_mcp` stdio entry |
+| `src/mcp/session.rs` | `CaptureManager`/`CaptureSession`: per-session proxy + child lifecycle + trace pump |
 | `tests/proxy_node_integration.rs` | Integration tests: Node.js proxy capture, alternative HTTP client tracing |
+| `tests/cli_query_integration.rs` | Integration tests: exit codes, JSONL purity, query subcommands, store lock UX |
+| `tests/mcp_stdio_integration.rs` | Integration test: MCP server driven with raw JSON-RPC over stdio |
 | `tests/apps/node-app/proxy-preload.js` | Node.js `--require` preload: patches `http`, `https`, `undici`, `fetch` to go through proxy |
 | `tests/apps/node-app/client.js` | Test client: `http`/`https` module usage (basic integration test) |
 | `tests/apps/node-app/client-alts.js` | Test client: `axios`, `undici`, `globalThis.fetch` (alternative HTTP clients test) |
@@ -355,8 +441,10 @@ pub enum StorageError {
 | `tests/proxy_php_integration.rs` | Integration test: PHP curl HTTP/HTTPS via `proxy` backend (`-d curl.cainfo=` injection) |
 | `tests/proxy_php_ldpreload_integration.rs` | Integration test: PHP curl HTTP/HTTPS via `ldpreload` backend (Linux only) |
 | `tests/apps/php-app/client.php` | Test client: curl extension, PHP 5.3-compatible syntax; shared by both PHP tests |
-| `crates/phantom-core/src/trace.rs` | `HttpTrace`, `TraceId`, `SpanId`, `HttpMethod` |
-| `crates/phantom-core/src/storage.rs` | `TraceStore` trait |
+| `crates/phantom-core/src/trace.rs` | `HttpTrace`, `TraceId`, `SpanId`, `HttpMethod` (incl. `FromStr`/`from_hex`) |
+| `crates/phantom-core/src/query.rs` | `TraceQuery` filter struct + `matches()` predicate, `StatusRange` parsing |
+| `crates/phantom-core/src/view.rs` | `TraceView` agent-facing JSON DTO + `RenderOptions` (truncation, headers-only, redaction) |
+| `crates/phantom-core/src/storage.rs` | `TraceStore` trait (incl. `query`/`clear`) |
 | `crates/phantom-core/src/capture.rs` | `CaptureBackend` trait |
 | `crates/phantom-core/src/error.rs` | `CaptureError`, `StorageError` |
 | `crates/phantom-storage/src/fjall_store.rs` | Storage implementation + all storage tests |
@@ -382,8 +470,14 @@ HTTP traffic
   → app.rs App::add_trace()                   # prepends to traces Vec, bumps count
   → ui.rs render()                            # pure read of App state, no mutation
 
+MCP flow (phantom mcp):
+  → mcp/server.rs PhantomMcp start_capture    # rmcp stdio tool call
+  → mcp/session.rs CaptureManager::start()    # proxy backend + spawn_proxy_child + trace pump task
+  → fjall_store.rs insert() (spawn_blocking)  # same store as CLI/TUI
+  → list_traces / get_trace tools             # TraceQuery → TraceView (bodies truncated by default)
+
 Node.js auto-injection (proxy mode, -- node app.js):
-  → main.rs spawn_proxy_child()               # writes proxy-preload.js to /tmp, prepends --require
+  → runner.rs spawn_proxy_child()             # writes proxy-preload.js to /tmp, prepends --require
   → proxy-preload.js loaded by Node at startup
   → patches http.request, https.request, undici dispatcher, globalThis.fetch
   → all outbound Node requests → phantom MITM proxy
diff --git a/Cargo.lock b/Cargo.lock
index 996bcca..d241a39 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -38,6 +38,15 @@ version = "0.2.21"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "683d7910e743518b0e34f1186f92494becacb047c7b6bf616c96772180fef923"
 
+[[package]]
+name = "android_system_properties"
+version = "0.1.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "819e7219dbd41043ac279b19830f2efc897156490d7fd6ea916720117ee66311"
+dependencies = [
+ "libc",
+]
+
 [[package]]
 name = "anstream"
 version = "0.6.21"
@@ -156,6 +165,17 @@ dependencies = [
  "pin-project-lite",
 ]
 
+[[package]]
+name = "async-trait"
+version = "0.1.89"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9035ad2d096bed7955a320ee7e2230574d28fd3c3a0f186cbea1ff3c7eed5dbb"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
 [[package]]
 name = "atomic-waker"
 version = "1.1.2"
@@ -284,6 +304,18 @@ version = "1.0.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "9330f8b2ff13f34540b44e946ef35111825727b38d33286ef986142615121801"
 
+[[package]]
+name = "chrono"
+version = "0.4.45"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1aa79e62e7697b8e29b513a68abacf485adcd1fe8284a4316c5ae868e6633327"
+dependencies = [
+ "iana-time-zone",
+ "num-traits",
+ "serde",
+ "windows-link",
+]
+
 [[package]]
 name = "clap"
 version = "4.5.60"
@@ -607,6 +639,12 @@ version = "0.1.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "c0d05e1c0dbad51b52c38bda7adceef61b9efc2baf04acfe8726a8c4630a6f57"
 
+[[package]]
+name = "dyn-clone"
+version = "1.0.20"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d0881ea181b1df73ff77ffaaf9c7544ecc11e82fba9b5f27b262a3c73a332555"
+
 [[package]]
 name = "either"
 version = "1.15.0"
@@ -982,6 +1020,12 @@ dependencies = [
  "tracing",
 ]
 
+[[package]]
+name = "humantime"
+version = "2.4.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "15cdd26707701c53297e2fa6afb323d55fbc1d0810c3aec078ae3ef0424c3c15"
+
 [[package]]
 name = "hyper"
 version = "1.8.1"
@@ -1059,6 +1103,30 @@ dependencies = [
  "tracing",
 ]
 
+[[package]]
+name = "iana-time-zone"
+version = "0.1.65"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e31bc9ad994ba00e440a8aa5c9ef0ec67d5cb5e5cb0cc7f8b744a35b389cc470"
+dependencies = [
+ "android_system_properties",
+ "core-foundation-sys",
+ "iana-time-zone-haiku",
+ "js-sys",
+ "log 0.4.29",
+ "wasm-bindgen",
+ "windows-core",
+]
+
+[[package]]
+name = "iana-time-zone-haiku"
+version = "0.1.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f31827a206f56af32e590ba56d5d2d085f558508192593743f16b2306495269f"
+dependencies = [
+ "cc",
+]
+
 [[package]]
 name = "icu_collections"
 version = "2.1.1"
@@ -1566,6 +1634,12 @@ version = "1.0.15"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "57c0d7b74b563b49d38dae00a0c37d4d6de9b432382b2892f0574ddcae73fd0a"
 
+[[package]]
+name = "pastey"
+version = "0.2.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2ee67f1008b1ba2321834326597b8e186293b049a023cdef258527550b9935b4"
+
 [[package]]
 name = "path-absolutize"
 version = "3.1.1"
@@ -1608,11 +1682,13 @@ dependencies = [
  "cargo-husky",
  "clap",
  "dirs",
+ "humantime",
  "phantom-capture",
  "phantom-core",
  "phantom-storage",
  "phantom-tui",
  "rcgen",
+ "rmcp",
  "rustls",
  "rustls-pki-types",
  "serde",
@@ -1875,6 +1951,26 @@ dependencies = [
  "thiserror 2.0.18",
 ]
 
+[[package]]
+name = "ref-cast"
+version = "1.0.25"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f354300ae66f76f1c85c5f84693f0ce81d747e2c3f21a45fef496d89c960bf7d"
+dependencies = [
+ "ref-cast-impl",
+]
+
+[[package]]
+name = "ref-cast-impl"
+version = "1.0.25"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b7186006dcb21920990093f30e3dea63b7d6e977bf1256be20c3563a5db070da"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
 [[package]]
 name = "regex-automata"
 version = "0.4.14"
@@ -1906,6 +2002,41 @@ dependencies = [
  "windows-sys 0.52.0",
 ]
 
+[[package]]
+name = "rmcp"
+version = "2.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "14db48ee17a9ba61810ab1a9c1beb7d06d8136ae39ac25a1137f10d357af01af"
+dependencies = [
+ "async-trait",
+ "base64",
+ "chrono",
+ "futures",
+ "pastey",
+ "pin-project-lite",
+ "rmcp-macros",
+ "schemars",
+ "serde",
+ "serde_json",
+ "thiserror 2.0.18",
+ "tokio",
+ "tokio-util",
+ "tracing",
+]
+
+[[package]]
+name = "rmcp-macros"
+version = "2.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "783d787bf21813b285f13019adc49e11af501c658890c1e519f31f937c68b7e3"
+dependencies = [
+ "darling",
+ "proc-macro2",
+ "quote",
+ "serde_json",
+ "syn",
+]
+
 [[package]]
 name = "rustc-hash"
 version = "2.1.1"
@@ -2024,6 +2155,32 @@ dependencies = [
  "windows-sys 0.61.2",
 ]
 
+[[package]]
+name = "schemars"
+version = "1.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a2b42f36aa1cd011945615b92222f6bf73c599a102a300334cd7f8dbeec726cc"
+dependencies = [
+ "chrono",
+ "dyn-clone",
+ "ref-cast",
+ "schemars_derive",
+ "serde",
+ "serde_json",
+]
+
+[[package]]
+name = "schemars_derive"
+version = "1.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7d115b50f4aaeea07e79c1912f645c7513d81715d0420f8bc77a18c6260b307f"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "serde_derive_internals",
+ "syn",
+]
+
 [[package]]
 name = "scoped-tls"
 version = "1.0.1"
@@ -2101,6 +2258,17 @@ dependencies = [
  "syn",
 ]
 
+[[package]]
+name = "serde_derive_internals"
+version = "0.29.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "18d26a20a969b9e3fdf2fc2d9f21eda6c40e2de84c9408bb5d3b05d499aae711"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
 [[package]]
 name = "serde_json"
 version = "1.0.149"
@@ -2839,6 +3007,41 @@ version = "0.4.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "712e227841d057c1ee1cd2fb22fa7e5a5461ae8e48fa2ca79ec42cfc1931183f"
 
+[[package]]
+name = "windows-core"
+version = "0.62.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b8e83a14d34d0623b51dce9581199302a221863196a1dde71a7663a4c2be9deb"
+dependencies = [
+ "windows-implement",
+ "windows-interface",
+ "windows-link",
+ "windows-result",
+ "windows-strings",
+]
+
+[[package]]
+name = "windows-implement"
+version = "0.60.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "053e2e040ab57b9dc951b72c264860db7eb3b0200ba345b4e4c3b14f67855ddf"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "windows-interface"
+version = "0.59.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3f316c4a2570ba26bbec722032c4099d8c8bc095efccdc15688708623367e358"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
 [[package]]
 name = "windows-link"
 version = "0.2.1"
@@ -2854,6 +3057,15 @@ dependencies = [
  "windows-link",
 ]
 
+[[package]]
+name = "windows-strings"
+version = "0.5.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7837d08f69c77cf6b07689544538e017c1bfcf57e34b4c0ff58e6c2cd3b37091"
+dependencies = [
+ "windows-link",
+]
+
 [[package]]
 name = "windows-sys"
 version = "0.52.0"
diff --git a/Cargo.toml b/Cargo.toml
index 72526db..9b844e3 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -43,10 +43,13 @@ tracing-subscriber = { version = "0.3", features = ["env-filter"] }
 clap = { version = "4", features = ["derive"] }
 dirs = "6"
 anyhow = "1"
+humantime = "2"
+rmcp = { version = "2.2", features = ["server", "transport-io", "macros"] }
 
 [dev-dependencies]
 serde_json = { workspace = true }
 serde = { workspace = true }
+phantom-storage = { workspace = true }
 tempfile = "3"
 rustls = "0.22"
 rcgen = "0.13"
diff --git a/GEMINI.md b/GEMINI.md
index 5d9a706..c05dd35 100644
--- a/GEMINI.md
+++ b/GEMINI.md
@@ -6,31 +6,37 @@ Phantom is a next-generation API observability and automatic workflow generation
 
 ### Building and Running
 - **Build the project:** `cargo build`
-- **Run with Proxy (default):** `phantom -- <COMMAND>` (e.g., `phantom -- node app.js`)
+- **Run with Proxy (default):** `phantom run -- <COMMAND>` (e.g., `phantom run -- node app.js`)
 - **Run with LD_PRELOAD (Linux only):**
-  `cargo run -- --backend ldpreload --agent-lib ./target/debug/libphantom_agent.so -- curl http://example.com`
-- **Run in JSONL mode:** `phantom --output jsonl -- <COMMAND>`
+  `cargo run -- run --backend ldpreload --agent-lib ./target/debug/libphantom_agent.so -- curl http://example.com`
+- **Run in JSONL mode:** `phantom run --output jsonl -- <COMMAND>` (exits with the child's exit code)
+- **Query stored traces:** `phantom list --status 5xx --since 10m`, `phantom get <SPAN_ID>`
+- **MCP server for AI agents:** `phantom mcp` (register: `claude mcp add phantom -- phantom mcp`)
 - **Run tests:** `cargo test`
 
 ### Common Examples
 - **Trace a Node.js app (HTTP + HTTPS captured automatically):**
-  `phantom -- node app.js`
+  `phantom run -- node app.js`
 - **Stream traces to jq for filtering:**
-  `phantom --output jsonl -- node app.js | jq 'select(.status_code >= 400)'`
+  `phantom run --output jsonl -- node app.js | jq 'select(.status_code >= 400)'`
 - **Capture plain HTTP for any command:**
-  `phantom -- curl http://api.example.com/v1/users`
+  `phantom run -- curl http://api.example.com/v1/users`
 
-## 🛠 CLI Options
+## 🛠 CLI Structure
+`phantom <SUBCOMMAND>` with global `-d, --data-dir <DIR>` and `-q, --quiet`.
+Subcommands: `run` (capture), `list`/`get`/`search`/`stats`/`clear` (offline queries), `mcp` (MCP server over stdio).
+
+`run` flags:
 - `-b, --backend <BACKEND>`: Capture backend to use (`proxy` or `ldpreload`). Default: `proxy`.
 - `-o, --output <MODE>`: Output mode (`tui` or `jsonl`). Default: `tui`.
 - `-p, --port <PORT>`: Port for the proxy backend. Default: `8080`.
 - `--insecure`: Disable TLS certificate verification for backend connections.
-- `-d, --data-dir <DIR>`: Directory for trace storage. Default: `~/.local/share/phantom/data`.
 - `--agent-lib <PATH>`: Path to `libphantom_agent.so` (required for `ldpreload`).
+- `--max-body <N>` / `--headers-only`: Limit body output in JSONL mode.
 - `-- <COMMAND>`: The command to run with interception injected.
 
 ### JSONL Output Schema
-When using `--output jsonl`, each line is a JSON object with:
+When using `run --output jsonl`, each line is a JSON object with:
 - `trace_id`: W3C-compatible 128-bit trace ID (hex).
 - `span_id`: 64-bit span ID (hex).
 - `timestamp_ms`: Unix epoch milliseconds.
@@ -41,6 +47,8 @@ When using `--output jsonl`, each line is a JSON object with:
 - `protocol_version`: e.g., "HTTP/1.1".
 - `request_headers` / `response_headers`: Header maps.
 - `request_body` / `response_body`: UTF-8 decoded bodies (optional).
+- `request_body_bytes` / `response_body_bytes`: Original body sizes (optional).
+- `request_body_truncated` / `response_body_truncated`: Present when `--max-body` truncated (optional).
 
 ## 🏗 Architecture & Tech Stack
 
@@ -80,7 +88,9 @@ The project is organized as a Rust workspace:
 - **GUI:** Cross-platform desktop interface using **Tauri**.
 
 ## 📂 Key Files
-- `src/main.rs`: CLI entry point and process spawning logic.
+- `src/main.rs`: CLI entry point (subcommand dispatch, exit-code mapping).
+- `src/cli.rs` / `src/runner.rs` / `src/commands/`: clap definitions, child spawning, run/query handlers.
+- `src/mcp/`: MCP server (`rmcp` stdio, capture sessions + trace query tools).
 - `crates/phantom-core/src/trace.rs`: `HttpTrace` definition.
 - `crates/phantom-storage/src/fjall_store.rs`: Primary storage implementation.
 - `crates/phantom-capture/src/proxy.rs`: Proxy-based interception logic.
diff --git a/crates/phantom-core/AGENTS.md b/crates/phantom-core/AGENTS.md
index bccd931..70299b5 100644
--- a/crates/phantom-core/AGENTS.md
+++ b/crates/phantom-core/AGENTS.md
@@ -8,9 +8,11 @@
 
 ```
 crates/phantom-core/src/
-├── lib.rs        # Re-exports: pub mod trace, capture, storage, error
-├── trace.rs      # HttpTrace, TraceId, SpanId, HttpMethod
-├── storage.rs    # TraceStore trait
+├── lib.rs        # Re-exports: pub mod trace, capture, storage, error, query, view
+├── trace.rs      # HttpTrace, TraceId, SpanId, HttpMethod (FromStr / from_hex parsers)
+├── storage.rs    # TraceStore trait (incl. query/clear)
+├── query.rs      # TraceQuery filter struct + matches() predicate, StatusRange
+├── view.rs       # TraceView agent-facing JSON DTO + RenderOptions
 ├── capture.rs    # CaptureBackend trait
 └── error.rs      # CaptureError, StorageError (thiserror)
 ```
@@ -23,6 +25,8 @@ crates/phantom-core/src/
 |------|------|-------|
 | Add/change HTTP trace fields | `trace.rs` | HttpTrace struct |
 | Add storage query method | `storage.rs` | TraceStore trait |
+| Add trace filter field | `query.rs` | TraceQuery + matches() |
+| Change agent-facing JSON shape | `view.rs` | TraceView::render (shared by JSONL/CLI/MCP) |
 | Add capture mode | `capture.rs` | CaptureBackend trait |
 | Add error variant | `error.rs` | Two enums: CaptureError, StorageError |
 
diff --git a/crates/phantom-core/src/lib.rs b/crates/phantom-core/src/lib.rs
index 07f75f0..98055dc 100644
--- a/crates/phantom-core/src/lib.rs
+++ b/crates/phantom-core/src/lib.rs
@@ -1,4 +1,6 @@
 pub mod capture;
 pub mod error;
+pub mod query;
 pub mod storage;
 pub mod trace;
+pub mod view;
diff --git a/crates/phantom-core/src/query.rs b/crates/phantom-core/src/query.rs
new file mode 100644
index 0000000..312b355
--- /dev/null
+++ b/crates/phantom-core/src/query.rs
@@ -0,0 +1,253 @@
+use std::str::FromStr;
+use std::time::SystemTime;
+
+use crate::trace::{HttpMethod, HttpTrace, TraceId};
+
+/// Error returned when parsing a status-range expression.
+#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
+#[error("invalid status range: {0:?} (expected e.g. \"404\", \"4xx\", or \"400-499\")")]
+pub struct ParseStatusRangeError(pub String);
+
+/// An inclusive range of HTTP status codes.
+///
+/// Parses from `"404"` (exact), `"4xx"` (class), or `"400-499"` (explicit range).
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct StatusRange {
+    pub min: u16,
+    pub max: u16,
+}
+
+impl StatusRange {
+    pub fn contains(&self, status: u16) -> bool {
+        (self.min..=self.max).contains(&status)
+    }
+}
+
+impl FromStr for StatusRange {
+    type Err = ParseStatusRangeError;
+
+    fn from_str(s: &str) -> Result<Self, Self::Err> {
+        let err = || ParseStatusRangeError(s.to_string());
+
+        // "4xx" / "4XX" — status class
+        if s.len() == 3 && s[1..].eq_ignore_ascii_case("xx") {
+            let class = s[..1].parse::<u16>().map_err(|_| err())?;
+            if !(1..=5).contains(&class) {
+                return Err(err());
+            }
+            return Ok(Self {
+                min: class * 100,
+                max: class * 100 + 99,
+            });
+        }
+
+        // "400-499" — explicit range
+        if let Some((lo, hi)) = s.split_once('-') {
+            let min = lo.parse::<u16>().map_err(|_| err())?;
+            let max = hi.parse::<u16>().map_err(|_| err())?;
+            if min > max {
+                return Err(err());
+            }
+            return Ok(Self { min, max });
+        }
+
+        // "404" — exact code
+        let code = s.parse::<u16>().map_err(|_| err())?;
+        Ok(Self {
+            min: code,
+            max: code,
+        })
+    }
+}
+
+/// A filter over stored traces. All set fields must match (logical AND);
+/// unset fields match everything.
+#[derive(Debug, Clone, Default)]
+pub struct TraceQuery {
+    /// Match any of these methods; empty = all methods.
+    pub methods: Vec<HttpMethod>,
+    /// Match status codes within this inclusive range.
+    pub status: Option<StatusRange>,
+    /// Match URLs containing this substring (case-insensitive).
+    pub url_contains: Option<String>,
+    /// Only traces with `timestamp >= since` (inclusive).
+    pub since: Option<SystemTime>,
+    /// Only traces with `timestamp <= until` (inclusive).
+    pub until: Option<SystemTime>,
+    /// Restrict to spans of this trace ID.
+    pub trace_id: Option<TraceId>,
+    /// Maximum number of traces to return; 0 means the caller's default.
+    pub limit: usize,
+    /// Number of matching traces to skip (applied after filtering).
+    pub offset: usize,
+}
+
+impl TraceQuery {
+    /// Returns true when `trace` matches every set filter field.
+    /// Pure predicate — storage layers scan and call this per trace.
+    pub fn matches(&self, trace: &HttpTrace) -> bool {
+        if !self.methods.is_empty() && !self.methods.contains(&trace.method) {
+            return false;
+        }
+        if let Some(range) = &self.status
+            && !range.contains(trace.status_code)
+        {
+            return false;
+        }
+        if let Some(pattern) = &self.url_contains
+            && !trace.url.to_lowercase().contains(&pattern.to_lowercase())
+        {
+            return false;
+        }
+        if let Some(since) = self.since
+            && trace.timestamp < since
+        {
+            return false;
+        }
+        if let Some(until) = self.until
+            && trace.timestamp > until
+        {
+            return false;
+        }
+        if let Some(trace_id) = &self.trace_id
+            && &trace.trace_id != trace_id
+        {
+            return false;
+        }
+        true
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use std::collections::HashMap;
+    use std::time::{Duration, UNIX_EPOCH};
+
+    use super::*;
+    use crate::trace::SpanId;
+
+    fn make_trace(method: HttpMethod, url: &str, status: u16, ts_secs: u64) -> HttpTrace {
+        HttpTrace {
+            span_id: SpanId([1; 8]),
+            trace_id: TraceId([2; 16]),
+            parent_span_id: None,
+            method,
+            url: url.to_string(),
+            request_headers: HashMap::new(),
+            request_body: None,
+            status_code: status,
+            response_headers: HashMap::new(),
+            response_body: None,
+            timestamp: UNIX_EPOCH + Duration::from_secs(ts_secs),
+            duration: Duration::from_millis(10),
+            source_addr: None,
+            dest_addr: None,
+            protocol_version: "HTTP/1.1".to_string(),
+        }
+    }
+
+    #[test]
+    fn test_status_range_parse_exact() {
+        let r: StatusRange = "404".parse().unwrap();
+        assert_eq!(r, StatusRange { min: 404, max: 404 });
+        assert!(r.contains(404));
+        assert!(!r.contains(403));
+    }
+
+    #[test]
+    fn test_status_range_parse_class() {
+        let r: StatusRange = "4xx".parse().unwrap();
+        assert_eq!(r, StatusRange { min: 400, max: 499 });
+        let r: StatusRange = "5XX".parse().unwrap();
+        assert_eq!(r, StatusRange { min: 500, max: 599 });
+        assert!("0xx".parse::<StatusRange>().is_err());
+        assert!("6xx".parse::<StatusRange>().is_err());
+    }
+
+    #[test]
+    fn test_status_range_parse_explicit() {
+        let r: StatusRange = "400-499".parse().unwrap();
+        assert_eq!(r, StatusRange { min: 400, max: 499 });
+        assert!("499-400".parse::<StatusRange>().is_err());
+        assert!("abc".parse::<StatusRange>().is_err());
+        assert!("4x".parse::<StatusRange>().is_err());
+        assert!("".parse::<StatusRange>().is_err());
+    }
+
+    #[test]
+    fn test_query_default_matches_everything() {
+        let q = TraceQuery::default();
+        assert!(q.matches(&make_trace(HttpMethod::Get, "http://a/x", 200, 100)));
+    }
+
+    #[test]
+    fn test_query_by_method() {
+        let q = TraceQuery {
+            methods: vec![HttpMethod::Post, HttpMethod::Put],
+            ..Default::default()
+        };
+        assert!(q.matches(&make_trace(HttpMethod::Post, "http://a", 200, 0)));
+        assert!(!q.matches(&make_trace(HttpMethod::Get, "http://a", 200, 0)));
+    }
+
+    #[test]
+    fn test_query_by_status() {
+        let q = TraceQuery {
+            status: Some("4xx".parse().unwrap()),
+            ..Default::default()
+        };
+        assert!(q.matches(&make_trace(HttpMethod::Get, "http://a", 404, 0)));
+        assert!(!q.matches(&make_trace(HttpMethod::Get, "http://a", 200, 0)));
+    }
+
+    #[test]
+    fn test_query_by_url_case_insensitive() {
+        let q = TraceQuery {
+            url_contains: Some("API/Users".to_string()),
+            ..Default::default()
+        };
+        assert!(q.matches(&make_trace(HttpMethod::Get, "http://x/api/users/1", 200, 0)));
+        assert!(!q.matches(&make_trace(HttpMethod::Get, "http://x/health", 200, 0)));
+    }
+
+    #[test]
+    fn test_query_time_range_inclusive() {
+        let q = TraceQuery {
+            since: Some(UNIX_EPOCH + Duration::from_secs(100)),
+            until: Some(UNIX_EPOCH + Duration::from_secs(200)),
+            ..Default::default()
+        };
+        assert!(!q.matches(&make_trace(HttpMethod::Get, "u", 200, 99)));
+        assert!(q.matches(&make_trace(HttpMethod::Get, "u", 200, 100)));
+        assert!(q.matches(&make_trace(HttpMethod::Get, "u", 200, 200)));
+        assert!(!q.matches(&make_trace(HttpMethod::Get, "u", 200, 201)));
+    }
+
+    #[test]
+    fn test_query_by_trace_id() {
+        let q = TraceQuery {
+            trace_id: Some(TraceId([2; 16])),
+            ..Default::default()
+        };
+        assert!(q.matches(&make_trace(HttpMethod::Get, "u", 200, 0)));
+        let q = TraceQuery {
+            trace_id: Some(TraceId([9; 16])),
+            ..Default::default()
+        };
+        assert!(!q.matches(&make_trace(HttpMethod::Get, "u", 200, 0)));
+    }
+
+    #[test]
+    fn test_query_combined_filters() {
+        let q = TraceQuery {
+            methods: vec![HttpMethod::Get],
+            status: Some("200".parse().unwrap()),
+            url_contains: Some("/api".to_string()),
+            ..Default::default()
+        };
+        assert!(q.matches(&make_trace(HttpMethod::Get, "http://x/api/a", 200, 0)));
+        assert!(!q.matches(&make_trace(HttpMethod::Post, "http://x/api/a", 200, 0)));
+        assert!(!q.matches(&make_trace(HttpMethod::Get, "http://x/api/a", 500, 0)));
+        assert!(!q.matches(&make_trace(HttpMethod::Get, "http://x/other", 200, 0)));
+    }
+}
diff --git a/crates/phantom-core/src/storage.rs b/crates/phantom-core/src/storage.rs
index 8fe3767..005d5d1 100644
--- a/crates/phantom-core/src/storage.rs
+++ b/crates/phantom-core/src/storage.rs
@@ -1,4 +1,5 @@
 use crate::error::StorageError;
+use crate::query::TraceQuery;
 use crate::trace::{HttpTrace, SpanId, TraceId};
 
 /// Abstraction over trace storage backends.
@@ -20,4 +21,12 @@ pub trait TraceStore: Send + Sync {
 
     /// Get total trace count.
     fn count(&self) -> Result<u64, StorageError>;
+
+    /// Filtered listing (newest first). See [`TraceQuery`] for filter semantics;
+    /// `query.offset` is applied after filtering, `query.limit` of 0 means
+    /// the implementation's default page size.
+    fn query(&self, query: &TraceQuery) -> Result<Vec<HttpTrace>, StorageError>;
+
+    /// Delete all stored traces and their indices.
+    fn clear(&self) -> Result<(), StorageError>;
 }
diff --git a/crates/phantom-core/src/trace.rs b/crates/phantom-core/src/trace.rs
index 56bdd43..7e025e8 100644
--- a/crates/phantom-core/src/trace.rs
+++ b/crates/phantom-core/src/trace.rs
@@ -1,9 +1,24 @@
 use std::collections::HashMap;
 use std::fmt;
+use std::str::FromStr;
 use std::time::{Duration, SystemTime};
 
 use serde::{Deserialize, Serialize};
 
+/// Decodes a fixed-length lowercase/uppercase hex string into a byte array.
+fn decode_hex<const N: usize>(s: &str) -> Option<[u8; N]> {
+    if s.len() != N * 2 || !s.is_ascii() {
+        return None;
+    }
+    let mut bytes = [0u8; N];
+    for (i, chunk) in s.as_bytes().chunks_exact(2).enumerate() {
+        let hi = (chunk[0] as char).to_digit(16)?;
+        let lo = (chunk[1] as char).to_digit(16)?;
+        bytes[i] = ((hi << 4) | lo) as u8;
+    }
+    Some(bytes)
+}
+
 /// Unique identifier for a trace (W3C Trace Context compatible, 128-bit).
 #[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
 pub struct TraceId(pub [u8; 16]);
@@ -12,6 +27,11 @@ impl TraceId {
     pub fn as_bytes(&self) -> &[u8; 16] {
         &self.0
     }
+
+    /// Parses a 32-character hex string (the `Display` format) back into a `TraceId`.
+    pub fn from_hex(s: &str) -> Option<Self> {
+        decode_hex(s).map(Self)
+    }
 }
 
 impl fmt::Display for TraceId {
@@ -31,6 +51,11 @@ impl SpanId {
     pub fn as_bytes(&self) -> &[u8; 8] {
         &self.0
     }
+
+    /// Parses a 16-character hex string (the `Display` format) back into a `SpanId`.
+    pub fn from_hex(s: &str) -> Option<Self> {
+        decode_hex(s).map(Self)
+    }
 }
 
 impl fmt::Display for SpanId {
@@ -74,6 +99,30 @@ impl fmt::Display for HttpMethod {
     }
 }
 
+/// Error returned when parsing an unrecognized HTTP method string.
+#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
+#[error("unknown HTTP method: {0:?}")]
+pub struct ParseMethodError(pub String);
+
+impl FromStr for HttpMethod {
+    type Err = ParseMethodError;
+
+    fn from_str(s: &str) -> Result<Self, Self::Err> {
+        match s.to_ascii_uppercase().as_str() {
+            "GET" => Ok(Self::Get),
+            "POST" => Ok(Self::Post),
+            "PUT" => Ok(Self::Put),
+            "DELETE" => Ok(Self::Delete),
+            "PATCH" => Ok(Self::Patch),
+            "HEAD" => Ok(Self::Head),
+            "OPTIONS" => Ok(Self::Options),
+            "TRACE" => Ok(Self::Trace),
+            "CONNECT" => Ok(Self::Connect),
+            _ => Err(ParseMethodError(s.to_string())),
+        }
+    }
+}
+
 /// A complete HTTP request-response pair with timing metadata.
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct HttpTrace {
@@ -104,3 +153,48 @@ pub struct HttpTrace {
     pub dest_addr: Option<String>,
     pub protocol_version: String,
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_span_id_from_hex_round_trip() {
+        let id = SpanId([0x01, 0x23, 0x45, 0x67, 0x89, 0xab, 0xcd, 0xef]);
+        let hex = id.to_string();
+        assert_eq!(hex, "0123456789abcdef");
+        assert_eq!(SpanId::from_hex(&hex), Some(id));
+    }
+
+    #[test]
+    fn test_trace_id_from_hex_round_trip() {
+        let id = TraceId([0xff; 16]);
+        let hex = id.to_string();
+        assert_eq!(hex.len(), 32);
+        assert_eq!(TraceId::from_hex(&hex), Some(id));
+        // uppercase also accepted
+        assert_eq!(
+            TraceId::from_hex(&hex.to_uppercase()),
+            Some(TraceId([0xff; 16]))
+        );
+    }
+
+    #[test]
+    fn test_from_hex_rejects_invalid() {
+        assert_eq!(SpanId::from_hex(""), None);
+        assert_eq!(SpanId::from_hex("0123456789abcde"), None); // too short
+        assert_eq!(SpanId::from_hex("0123456789abcdef00"), None); // too long
+        assert_eq!(SpanId::from_hex("0123456789abcdeg"), None); // non-hex char
+        assert_eq!(TraceId::from_hex("0123456789abcdef"), None); // span-length for trace
+    }
+
+    #[test]
+    fn test_http_method_from_str() {
+        assert_eq!("GET".parse::<HttpMethod>().unwrap(), HttpMethod::Get);
+        assert_eq!("get".parse::<HttpMethod>().unwrap(), HttpMethod::Get);
+        assert_eq!("Post".parse::<HttpMethod>().unwrap(), HttpMethod::Post);
+        assert_eq!("DELETE".parse::<HttpMethod>().unwrap(), HttpMethod::Delete);
+        assert!("FETCH".parse::<HttpMethod>().is_err());
+        assert!("".parse::<HttpMethod>().is_err());
+    }
+}
diff --git a/crates/phantom-core/src/view.rs b/crates/phantom-core/src/view.rs
new file mode 100644
index 0000000..c1c5c94
--- /dev/null
+++ b/crates/phantom-core/src/view.rs
@@ -0,0 +1,345 @@
+use std::collections::HashMap;
+use std::time::UNIX_EPOCH;
+
+use serde::Serialize;
+
+use crate::trace::HttpTrace;
+
+/// Controls how much of a trace is included when rendering a [`TraceView`].
+///
+/// Defaults include everything: unlimited bodies, no redaction.
+#[derive(Debug, Clone, Default)]
+pub struct RenderOptions {
+    /// Maximum body bytes to include; bodies longer than this are truncated
+    /// at a UTF-8 character boundary and flagged. `None` = unlimited.
+    pub max_body: Option<usize>,
+    /// Omit request/response bodies entirely (original sizes still reported).
+    pub headers_only: bool,
+    /// Header names (lower-cased) whose values are replaced with `"[redacted]"`.
+    pub redact_headers: Vec<String>,
+}
+
+impl RenderOptions {
+    /// Headers redacted by default in agent-facing contexts (MCP tools).
+    pub fn sensitive_headers() -> Vec<String> {
+        [
+            "authorization",
+            "proxy-authorization",
+            "cookie",
+            "set-cookie",
+        ]
+        .into_iter()
+        .map(String::from)
+        .collect()
+    }
+}
+
+/// Agent-friendly, fully serializable representation of an [`HttpTrace`].
+///
+/// This is the canonical JSON shape shared by the JSONL output stream, the
+/// query CLI, and the MCP server. With default [`RenderOptions`] the emitted
+/// fields are a superset of the historical JSONL schema (add-only:
+/// `*_body_bytes` and `*_body_truncated`).
+#[derive(Debug, Clone, Serialize)]
+pub struct TraceView {
+    /// Unix timestamp of the request in milliseconds.
+    pub timestamp_ms: u64,
+    /// Round-trip duration in milliseconds.
+    pub duration_ms: u64,
+    /// HTTP method ("GET", "POST", …).
+    pub method: String,
+    /// Full request URL.
+    pub url: String,
+    /// HTTP response status code.
+    pub status_code: u16,
+    /// Request headers (lower-cased keys).
+    pub request_headers: HashMap<String, String>,
+    /// Response headers (lower-cased keys).
+    pub response_headers: HashMap<String, String>,
+    /// Request body decoded as UTF-8 (replacement chars for non-UTF-8 bytes).
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub request_body: Option<String>,
+    /// Response body decoded as UTF-8 (replacement chars for non-UTF-8 bytes).
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub response_body: Option<String>,
+    /// Original request body size in bytes (present iff a body existed).
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub request_body_bytes: Option<u64>,
+    /// Original response body size in bytes (present iff a body existed).
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub response_body_bytes: Option<u64>,
+    /// True when `request_body` was truncated by `max_body`.
+    #[serde(skip_serializing_if = "std::ops::Not::not")]
+    pub request_body_truncated: bool,
+    /// True when `response_body` was truncated by `max_body`.
+    #[serde(skip_serializing_if = "std::ops::Not::not")]
+    pub response_body_truncated: bool,
+    /// Source socket address, if available.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub source_addr: Option<String>,
+    /// Destination socket address, if available.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub dest_addr: Option<String>,
+    /// HTTP protocol version string (e.g. "HTTP/1.1").
+    pub protocol_version: String,
+    /// 128-bit W3C trace ID (hex).
+    pub trace_id: String,
+    /// 64-bit span ID (hex).
+    pub span_id: String,
+}
+
+/// Decodes a body as lossy UTF-8, applying `headers_only`/`max_body` policy.
+/// Returns `(rendered_body, original_size, truncated)`.
+fn render_body(
+    body: &Option<Vec<u8>>,
+    opts: &RenderOptions,
+) -> (Option<String>, Option<u64>, bool) {
+    let Some(bytes) = body.as_ref() else {
+        return (None, None, false);
+    };
+    let size = Some(bytes.len() as u64);
+    if opts.headers_only {
+        return (None, size, false);
+    }
+    let mut text = String::from_utf8_lossy(bytes).into_owned();
+    let mut truncated = false;
+    if let Some(max) = opts.max_body
+        && text.len() > max
+    {
+        let mut cut = max;
+        while !text.is_char_boundary(cut) {
+            cut -= 1;
+        }
+        text.truncate(cut);
+        truncated = true;
+    }
+    (Some(text), size, truncated)
+}
+
+fn render_headers(headers: &HashMap<String, String>, redact: &[String]) -> HashMap<String, String> {
+    headers
+        .iter()
+        .map(|(k, v)| {
+            if redact.iter().any(|r| r.eq_ignore_ascii_case(k)) {
+                (k.clone(), "[redacted]".to_string())
+            } else {
+                (k.clone(), v.clone())
+            }
+        })
+        .collect()
+}
+
+impl TraceView {
+    pub fn render(trace: &HttpTrace, opts: &RenderOptions) -> Self {
+        let timestamp_ms = trace
+            .timestamp
+            .duration_since(UNIX_EPOCH)
+            .map(|d| d.as_millis() as u64)
+            .unwrap_or(0);
+        let (request_body, request_body_bytes, request_body_truncated) =
+            render_body(&trace.request_body, opts);
+        let (response_body, response_body_bytes, response_body_truncated) =
+            render_body(&trace.response_body, opts);
+
+        Self {
+            timestamp_ms,
+            duration_ms: trace.duration.as_millis() as u64,
+            method: trace.method.to_string(),
+            url: trace.url.clone(),
+            status_code: trace.status_code,
+            request_headers: render_headers(&trace.request_headers, &opts.redact_headers),
+            response_headers: render_headers(&trace.response_headers, &opts.redact_headers),
+            request_body,
+            response_body,
+            request_body_bytes,
+            response_body_bytes,
+            request_body_truncated,
+            response_body_truncated,
+            source_addr: trace.source_addr.clone(),
+            dest_addr: trace.dest_addr.clone(),
+            protocol_version: trace.protocol_version.clone(),
+            trace_id: trace.trace_id.to_string(),
+            span_id: trace.span_id.to_string(),
+        }
+    }
+}
+
+impl From<&HttpTrace> for TraceView {
+    fn from(trace: &HttpTrace) -> Self {
+        Self::render(trace, &RenderOptions::default())
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use std::time::{Duration, SystemTime};
+
+    use super::*;
+    use crate::trace::{HttpMethod, SpanId, TraceId};
+
+    fn make_trace(request_body: Option<Vec<u8>>, response_body: Option<Vec<u8>>) -> HttpTrace {
+        let mut request_headers = HashMap::new();
+        request_headers.insert("authorization".to_string(), "Bearer secret".to_string());
+        request_headers.insert("accept".to_string(), "application/json".to_string());
+        HttpTrace {
+            span_id: SpanId([1; 8]),
+            trace_id: TraceId([2; 16]),
+            parent_span_id: None,
+            method: HttpMethod::Post,
+            url: "http://example.com/api".to_string(),
+            request_headers,
+            request_body,
+            status_code: 200,
+            response_headers: HashMap::new(),
+            response_body,
+            timestamp: SystemTime::UNIX_EPOCH + Duration::from_millis(1500),
+            duration: Duration::from_millis(42),
+            source_addr: None,
+            dest_addr: None,
+            protocol_version: "HTTP/1.1".to_string(),
+        }
+    }
+
+    #[test]
+    fn test_render_default_keeps_full_body() {
+        let t = make_trace(Some(b"hello".to_vec()), None);
+        let v = TraceView::render(&t, &RenderOptions::default());
+        assert_eq!(v.request_body.as_deref(), Some("hello"));
+        assert_eq!(v.request_body_bytes, Some(5));
+        assert!(!v.request_body_truncated);
+        assert_eq!(v.response_body, None);
+        assert_eq!(v.response_body_bytes, None);
+        assert_eq!(v.timestamp_ms, 1500);
+        assert_eq!(v.duration_ms, 42);
+        assert_eq!(v.span_id, "0101010101010101");
+    }
+
+    #[test]
+    fn test_render_max_body_truncates() {
+        let t = make_trace(None, Some(b"0123456789".to_vec()));
+        let opts = RenderOptions {
+            max_body: Some(4),
+            ..Default::default()
+        };
+        let v = TraceView::render(&t, &opts);
+        assert_eq!(v.response_body.as_deref(), Some("0123"));
+        assert_eq!(v.response_body_bytes, Some(10));
+        assert!(v.response_body_truncated);
+    }
+
+    #[test]
+    fn test_render_truncation_respects_char_boundary() {
+        // "あ" is 3 bytes in UTF-8; cutting at byte 4 must back up to byte 3.
+        let t = make_trace(Some("ああ".as_bytes().to_vec()), None);
+        let opts = RenderOptions {
+            max_body: Some(4),
+            ..Default::default()
+        };
+        let v = TraceView::render(&t, &opts);
+        assert_eq!(v.request_body.as_deref(), Some("あ"));
+        assert_eq!(v.request_body_bytes, Some(6));
+        assert!(v.request_body_truncated);
+    }
+
+    #[test]
+    fn test_render_headers_only_omits_bodies_reports_sizes() {
+        let t = make_trace(Some(b"req".to_vec()), Some(b"resp".to_vec()));
+        let opts = RenderOptions {
+            headers_only: true,
+            ..Default::default()
+        };
+        let v = TraceView::render(&t, &opts);
+        assert_eq!(v.request_body, None);
+        assert_eq!(v.response_body, None);
+        assert_eq!(v.request_body_bytes, Some(3));
+        assert_eq!(v.response_body_bytes, Some(4));
+        assert!(!v.request_body_truncated);
+    }
+
+    #[test]
+    fn test_render_no_truncation_when_body_fits() {
+        let t = make_trace(Some(b"1234".to_vec()), None);
+        let opts = RenderOptions {
+            max_body: Some(4),
+            ..Default::default()
+        };
+        let v = TraceView::render(&t, &opts);
+        assert_eq!(v.request_body.as_deref(), Some("1234"));
+        assert!(!v.request_body_truncated);
+        assert_eq!(v.request_body_bytes, Some(4));
+    }
+
+    #[test]
+    fn test_render_max_body_zero_empties_body() {
+        let t = make_trace(Some(b"data".to_vec()), None);
+        let opts = RenderOptions {
+            max_body: Some(0),
+            ..Default::default()
+        };
+        let v = TraceView::render(&t, &opts);
+        assert_eq!(v.request_body.as_deref(), Some(""));
+        assert!(v.request_body_truncated);
+        assert_eq!(v.request_body_bytes, Some(4));
+    }
+
+    #[test]
+    fn test_render_lossy_decodes_invalid_utf8() {
+        let t = make_trace(Some(vec![0x68, 0x69, 0xff, 0xfe]), None);
+        let v = TraceView::render(&t, &RenderOptions::default());
+        let body = v.request_body.unwrap();
+        assert!(body.starts_with("hi"));
+        assert!(body.contains('\u{fffd}'));
+        // Size reports the original bytes, not the decoded string length.
+        assert_eq!(v.request_body_bytes, Some(4));
+    }
+
+    #[test]
+    fn test_render_redacts_headers() {
+        let t = make_trace(None, None);
+        let opts = RenderOptions {
+            redact_headers: RenderOptions::sensitive_headers(),
+            ..Default::default()
+        };
+        let v = TraceView::render(&t, &opts);
+        assert_eq!(v.request_headers["authorization"], "[redacted]");
+        assert_eq!(v.request_headers["accept"], "application/json");
+    }
+
+    #[test]
+    fn test_render_redaction_is_case_insensitive() {
+        let mut t = make_trace(None, None);
+        t.response_headers
+            .insert("Set-Cookie".to_string(), "sid=1".to_string());
+        let opts = RenderOptions {
+            redact_headers: vec!["AUTHORIZATION".to_string(), "set-cookie".to_string()],
+            ..Default::default()
+        };
+        let v = TraceView::render(&t, &opts);
+        assert_eq!(v.request_headers["authorization"], "[redacted]");
+        assert_eq!(v.response_headers["Set-Cookie"], "[redacted]");
+    }
+
+    #[test]
+    fn test_sensitive_headers_cover_credential_carriers() {
+        let list = RenderOptions::sensitive_headers();
+        for h in [
+            "authorization",
+            "proxy-authorization",
+            "cookie",
+            "set-cookie",
+        ] {
+            assert!(list.contains(&h.to_string()), "missing {h}");
+        }
+    }
+
+    #[test]
+    fn test_serialized_shape_skips_absent_fields() {
+        let t = make_trace(None, None);
+        let json = serde_json::to_value(TraceView::from(&t)).unwrap();
+        let obj = json.as_object().unwrap();
+        assert!(!obj.contains_key("request_body"));
+        assert!(!obj.contains_key("request_body_bytes"));
+        assert!(!obj.contains_key("request_body_truncated"));
+        assert_eq!(obj["method"], "POST");
+    }
+}
diff --git a/crates/phantom-storage/AGENTS.md b/crates/phantom-storage/AGENTS.md
index 0844c8c..9a58dc0 100644
--- a/crates/phantom-storage/AGENTS.md
+++ b/crates/phantom-storage/AGENTS.md
@@ -49,6 +49,8 @@ crates/phantom-storage/src/
 - `encode_timestamp` uses **big-endian nanoseconds** — critical for correct lexicographic ordering.
 - Error mapping: `.map_err(|e| StorageError::Open(e.to_string()))` pattern throughout. Never use `?` directly on fjall errors (no `From` impl).
 - `search_by_url` is a **full scan** (MVP approach, noted in comment). Acceptable for now.
+- `query()` scans `by_time` (bounded by since/until key range) or the `by_trace_id` prefix, then post-filters with `TraceQuery::matches`; offset is applied after filtering.
+- `open()` takes an advisory flock on `<data-dir>/phantom.lock` — fjall does not lock across processes itself; a second open fails with `StorageError::Open`.
 - `count()` uses `approximate_len()` — not exact.
 
 ## TEST CONVENTIONS
diff --git a/crates/phantom-storage/src/fjall_store.rs b/crates/phantom-storage/src/fjall_store.rs
index 1a57264..a6959e1 100644
--- a/crates/phantom-storage/src/fjall_store.rs
+++ b/crates/phantom-storage/src/fjall_store.rs
@@ -2,6 +2,7 @@ use std::time::{Duration, SystemTime, UNIX_EPOCH};
 
 use fjall::{Config, Keyspace, PartitionCreateOptions, PartitionHandle};
 use phantom_core::error::StorageError;
+use phantom_core::query::TraceQuery;
 use phantom_core::storage::TraceStore;
 use phantom_core::trace::{HttpTrace, SpanId, TraceId};
 
@@ -10,10 +11,30 @@ pub struct FjallTraceStore {
     traces: PartitionHandle,
     by_time: PartitionHandle,
     by_trace_id: PartitionHandle,
+    /// Advisory exclusive lock on the data directory, released on drop.
+    /// fjall itself does not lock across processes, and two writers on one
+    /// keyspace would corrupt it — so we enforce single-process access here.
+    _lock: std::fs::File,
 }
 
 impl FjallTraceStore {
     pub fn open(path: impl AsRef<std::path::Path>) -> Result<Self, StorageError> {
+        let path = path.as_ref();
+        std::fs::create_dir_all(path).map_err(|e| StorageError::Open(e.to_string()))?;
+        let lock_path = path.join("phantom.lock");
+        let lock = std::fs::OpenOptions::new()
+            .create(true)
+            .truncate(false)
+            .write(true)
+            .open(&lock_path)
+            .map_err(|e| StorageError::Open(format!("{}: {e}", lock_path.display())))?;
+        lock.try_lock().map_err(|_| {
+            StorageError::Open(format!(
+                "data dir {} holds an active store lock (another phantom process is using it)",
+                path.display()
+            ))
+        })?;
+
         let keyspace = Config::new(path)
             .open()
             .map_err(|e| StorageError::Open(e.to_string()))?;
@@ -38,6 +59,7 @@ impl FjallTraceStore {
             traces,
             by_time,
             by_trace_id,
+            _lock: lock,
         })
     }
 }
@@ -157,6 +179,72 @@ impl TraceStore for FjallTraceStore {
     fn count(&self) -> Result<u64, StorageError> {
         Ok(self.traces.approximate_len() as u64)
     }
+
+    fn query(&self, query: &TraceQuery) -> Result<Vec<HttpTrace>, StorageError> {
+        const DEFAULT_LIMIT: usize = 100;
+        let limit = if query.limit == 0 {
+            DEFAULT_LIMIT
+        } else {
+            query.limit
+        };
+
+        // With a trace_id filter, the by_trace_id prefix scan is far narrower
+        // than a time scan; otherwise scan by_time (newest first), bounded by
+        // the since/until key range when given.
+        let index_entries: Box<dyn Iterator<Item = fjall::Result<(fjall::Slice, fjall::Slice)>>> =
+            if let Some(trace_id) = &query.trace_id {
+                Box::new(self.by_trace_id.prefix(trace_id.as_bytes()))
+            } else {
+                let start: [u8; 16] = query
+                    .since
+                    .map(|ts| time_key(&ts, &SpanId([0x00; 8])))
+                    .unwrap_or([0x00; 16]);
+                let end: [u8; 16] = query
+                    .until
+                    .map(|ts| time_key(&ts, &SpanId([0xff; 8])))
+                    .unwrap_or([0xff; 16]);
+                Box::new(self.by_time.range(start..=end).rev())
+            };
+
+        let mut skipped = 0;
+        let mut results = Vec::new();
+        for entry in index_entries {
+            if results.len() >= limit {
+                break;
+            }
+            let (_key, value) = entry.map_err(|e| StorageError::Read(e.to_string()))?;
+            let span_id_bytes: [u8; 8] = value[..8]
+                .try_into()
+                .map_err(|_| StorageError::Read("invalid span_id in index".into()))?;
+            if let Some(trace) = self.get_by_span_id(&SpanId(span_id_bytes))?
+                && query.matches(&trace)
+            {
+                if skipped < query.offset {
+                    skipped += 1;
+                    continue;
+                }
+                results.push(trace);
+            }
+        }
+        Ok(results)
+    }
+
+    fn clear(&self) -> Result<(), StorageError> {
+        for partition in [&self.traces, &self.by_time, &self.by_trace_id] {
+            let keys: Vec<_> = partition
+                .keys()
+                .collect::<Result<_, _>>()
+                .map_err(|e| StorageError::Read(e.to_string()))?;
+            let mut batch = self.keyspace.batch();
+            for key in keys {
+                batch.remove(partition, key);
+            }
+            batch
+                .commit()
+                .map_err(|e| StorageError::Write(e.to_string()))?;
+        }
+        Ok(())
+    }
 }
 
 #[cfg(test)]
@@ -265,4 +353,211 @@ mod tests {
         let results = store.search_by_url("/api/", 10).unwrap();
         assert_eq!(results.len(), 2);
     }
+
+    use phantom_core::trace::HttpMethod;
+
+    fn make_trace_at(url: &str, status: u16, ts_secs: u64) -> HttpTrace {
+        let mut t = make_trace(url, status);
+        t.timestamp = std::time::UNIX_EPOCH + Duration::from_secs(ts_secs);
+        t
+    }
+
+    #[test]
+    fn test_query_by_method() {
+        let dir = tempfile::tempdir().unwrap();
+        let store = FjallTraceStore::open(dir.path()).unwrap();
+
+        let mut post = make_trace("http://a/create", 201);
+        post.method = HttpMethod::Post;
+        store.insert(&post).unwrap();
+        store.insert(&make_trace("http://a/read", 200)).unwrap();
+
+        let results = store
+            .query(&TraceQuery {
+                methods: vec![HttpMethod::Post],
+                ..Default::default()
+            })
+            .unwrap();
+        assert_eq!(results.len(), 1);
+        assert_eq!(results[0].url, "http://a/create");
+    }
+
+    #[test]
+    fn test_query_by_status_range() {
+        let dir = tempfile::tempdir().unwrap();
+        let store = FjallTraceStore::open(dir.path()).unwrap();
+
+        store.insert(&make_trace("http://a/ok", 200)).unwrap();
+        store.insert(&make_trace("http://a/missing", 404)).unwrap();
+        store.insert(&make_trace("http://a/boom", 500)).unwrap();
+
+        let results = store
+            .query(&TraceQuery {
+                status: Some("4xx".parse().unwrap()),
+                ..Default::default()
+            })
+            .unwrap();
+        assert_eq!(results.len(), 1);
+        assert_eq!(results[0].status_code, 404);
+    }
+
+    #[test]
+    fn test_query_time_range_bounds_scan() {
+        let dir = tempfile::tempdir().unwrap();
+        let store = FjallTraceStore::open(dir.path()).unwrap();
+
+        for ts in [100, 200, 300, 400] {
+            store
+                .insert(&make_trace_at(&format!("http://a/{ts}"), 200, ts))
+                .unwrap();
+        }
+
+        // Inclusive on both ends; newest first.
+        let results = store
+            .query(&TraceQuery {
+                since: Some(std::time::UNIX_EPOCH + Duration::from_secs(200)),
+                until: Some(std::time::UNIX_EPOCH + Duration::from_secs(300)),
+                ..Default::default()
+            })
+            .unwrap();
+        let urls: Vec<_> = results.iter().map(|t| t.url.as_str()).collect();
+        assert_eq!(urls, ["http://a/300", "http://a/200"]);
+    }
+
+    #[test]
+    fn test_query_open_ended_time_ranges() {
+        let dir = tempfile::tempdir().unwrap();
+        let store = FjallTraceStore::open(dir.path()).unwrap();
+
+        for ts in [100, 200, 300] {
+            store
+                .insert(&make_trace_at(&format!("http://a/{ts}"), 200, ts))
+                .unwrap();
+        }
+
+        // since only
+        let results = store
+            .query(&TraceQuery {
+                since: Some(std::time::UNIX_EPOCH + Duration::from_secs(200)),
+                ..Default::default()
+            })
+            .unwrap();
+        let urls: Vec<_> = results.iter().map(|t| t.url.as_str()).collect();
+        assert_eq!(urls, ["http://a/300", "http://a/200"]);
+
+        // until only
+        let results = store
+            .query(&TraceQuery {
+                until: Some(std::time::UNIX_EPOCH + Duration::from_secs(200)),
+                ..Default::default()
+            })
+            .unwrap();
+        let urls: Vec<_> = results.iter().map(|t| t.url.as_str()).collect();
+        assert_eq!(urls, ["http://a/200", "http://a/100"]);
+    }
+
+    #[test]
+    fn test_query_zero_limit_uses_default_of_100() {
+        let dir = tempfile::tempdir().unwrap();
+        let store = FjallTraceStore::open(dir.path()).unwrap();
+
+        for i in 0..120u64 {
+            store
+                .insert(&make_trace_at(&format!("http://a/{i}"), 200, 1000 + i))
+                .unwrap();
+        }
+
+        let results = store.query(&TraceQuery::default()).unwrap();
+        assert_eq!(results.len(), 100);
+        // Newest first: the default page starts at the most recent trace.
+        assert_eq!(results[0].url, "http://a/119");
+
+        let results = store
+            .query(&TraceQuery {
+                limit: 5,
+                ..Default::default()
+            })
+            .unwrap();
+        assert_eq!(results.len(), 5);
+    }
+
+    #[test]
+    fn test_query_offset_applied_after_filter() {
+        let dir = tempfile::tempdir().unwrap();
+        let store = FjallTraceStore::open(dir.path()).unwrap();
+
+        // Interleave matching (404) and non-matching (200) traces.
+        for i in 0..6u64 {
+            let status = if i % 2 == 0 { 404 } else { 200 };
+            store
+                .insert(&make_trace_at(&format!("http://a/{i}"), status, 100 + i))
+                .unwrap();
+        }
+
+        // Matching, newest first: /4, /2, /0. Offset 1 + limit 1 → /2.
+        let results = store
+            .query(&TraceQuery {
+                status: Some("404".parse().unwrap()),
+                offset: 1,
+                limit: 1,
+                ..Default::default()
+            })
+            .unwrap();
+        assert_eq!(results.len(), 1);
+        assert_eq!(results[0].url, "http://a/2");
+    }
+
+    #[test]
+    fn test_query_by_trace_id_with_filters() {
+        let dir = tempfile::tempdir().unwrap();
+        let store = FjallTraceStore::open(dir.path()).unwrap();
+
+        let shared = TraceId(rand_bytes_16());
+        for status in [200, 404] {
+            let mut t = make_trace(&format!("http://a/{status}"), status);
+            t.trace_id = shared.clone();
+            store.insert(&t).unwrap();
+        }
+        store.insert(&make_trace("http://other/404", 404)).unwrap();
+
+        let results = store
+            .query(&TraceQuery {
+                trace_id: Some(shared),
+                status: Some("404".parse().unwrap()),
+                ..Default::default()
+            })
+            .unwrap();
+        assert_eq!(results.len(), 1);
+        assert_eq!(results[0].url, "http://a/404");
+    }
+
+    #[test]
+    fn test_open_is_exclusive() {
+        let dir = tempfile::tempdir().unwrap();
+        let store = FjallTraceStore::open(dir.path()).unwrap();
+
+        let second = FjallTraceStore::open(dir.path());
+        assert!(matches!(second, Err(StorageError::Open(_))));
+
+        // Lock is released when the store is dropped.
+        drop(store);
+        assert!(FjallTraceStore::open(dir.path()).is_ok());
+    }
+
+    #[test]
+    fn test_clear() {
+        let dir = tempfile::tempdir().unwrap();
+        let store = FjallTraceStore::open(dir.path()).unwrap();
+
+        let trace = make_trace("http://a/x", 200);
+        let span_id = trace.span_id.clone();
+        store.insert(&trace).unwrap();
+        store.insert(&make_trace("http://a/y", 200)).unwrap();
+
+        store.clear().unwrap();
+
+        assert!(store.get_by_span_id(&span_id).unwrap().is_none());
+        assert!(store.list_recent(10, 0).unwrap().is_empty());
+        assert!(store.query(&TraceQuery::default()).unwrap().is_empty());
+    }
 }
diff --git a/src/cli.rs b/src/cli.rs
new file mode 100644
index 0000000..6455e88
--- /dev/null
+++ b/src/cli.rs
@@ -0,0 +1,359 @@
+use std::path::PathBuf;
+
+use clap::{Args, Parser, Subcommand, ValueEnum};
+use phantom_core::query::StatusRange;
+use phantom_core::trace::HttpMethod;
+
+#[derive(Debug, Clone, ValueEnum)]
+pub enum Backend {
+    /// MITM proxy — captures HTTP + HTTPS, cross-platform. Node.js HTTPS injected automatically.
+    Proxy,
+    /// LD_PRELOAD agent — captures HTTP + HTTPS, Linux only. No proxy config needed.
+    #[cfg(target_os = "linux")]
+    Ldpreload,
+}
+
+#[derive(Debug, Clone, Default, ValueEnum)]
+pub enum OutputMode {
+    /// Interactive terminal UI with trace list and detail view.
+    #[default]
+    Tui,
+    /// Stream traces as JSON Lines to stdout; auto-exits when child process finishes.
+    Jsonl,
+}
+
+/// Output format for query subcommands (`list`, `search`, `get`).
+#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, ValueEnum)]
+pub enum QueryFormat {
+    /// One compact JSON object per line (pipe to jq).
+    #[default]
+    Jsonl,
+    /// Pretty-printed JSON (array for list/search, object for get).
+    Json,
+    /// Human-readable fixed-width columns.
+    Table,
+}
+
+#[derive(Parser)]
+#[command(
+    name = "phantom",
+    about = "Zero-instrumentation HTTP/HTTPS API observability tool",
+    long_about = "phantom — Zero-instrumentation HTTP/HTTPS API observability\n\
+\n\
+Captures every HTTP and HTTPS request/response made by a target process\n\
+and displays them in an interactive TUI, streams them as JSON Lines, or\n\
+serves them to AI coding agents over MCP.\n\
+\n\
+Typical workflows:\n\
+\n\
+  # Capture traffic from a command (TUI):\n\
+  phantom run -- node app.js\n\
+\n\
+  # Capture and stream JSONL for scripting / AI analysis:\n\
+  phantom run --output jsonl -- node app.js\n\
+\n\
+  # Query previously captured traces:\n\
+  phantom list --status 5xx --since 10m\n\
+  phantom get <SPAN_ID>\n\
+\n\
+  # Run as an MCP server (capture control + queries over stdio):\n\
+  phantom mcp\n\
+\n\
+Note: the trace store is locked by a single phantom process at a time.\n\
+Query subcommands work while no capture is running; while `phantom run`\n\
+or `phantom mcp` is active, query through the MCP server instead.",
+    version
+)]
+pub struct Cli {
+    /// Directory where captured traces are persisted (Fjall key-value store).
+    /// Defaults to the platform data directory, e.g. ~/.local/share/phantom/data.
+    #[arg(short, long, global = true)]
+    pub data_dir: Option<PathBuf>,
+
+    /// Suppress status messages on stderr (machine-friendly output only).
+    #[arg(short, long, global = true)]
+    pub quiet: bool,
+
+    #[command(subcommand)]
+    pub command: Commands,
+}
+
+#[derive(Subcommand)]
+pub enum Commands {
+    /// Capture HTTP(S) traffic, optionally spawning a command to trace.
+    Run(RunArgs),
+    /// List captured traces (newest first) with filters.
+    List(ListArgs),
+    /// Show a single trace by span ID.
+    Get(GetArgs),
+    /// Shorthand for `list --url <PATTERN>`.
+    Search(SearchArgs),
+    /// Print trace store statistics as JSON.
+    Stats,
+    /// Delete all captured traces.
+    Clear(ClearArgs),
+    /// Run as an MCP (Model Context Protocol) server over stdio.
+    ///
+    /// Exposes capture control and trace queries as MCP tools for AI coding
+    /// agents. Register with e.g.: claude mcp add phantom -- phantom mcp
+    Mcp,
+}
+
+#[derive(Args)]
+#[command(
+    long_about = "Capture HTTP(S) traffic, optionally spawning a command to trace.\n\
+\n\
+━━━ CAPTURE BACKENDS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n\
+\n\
+  proxy  (default, cross-platform)\n\
+    Starts a MITM proxy on 127.0.0.1:<PORT>.  Intercepts HTTP and HTTPS.\n\
+\n\
+    • Node.js  (`phantom run -- node app.js`)\n\
+      proxy-preload.js is injected automatically via --require.  Both http://\n\
+      and https:// are captured with zero application changes.\n\
+\n\
+    • PHP  (`phantom run -- php app.php`)\n\
+      The MITM CA certificate is injected automatically via -d curl.cainfo=.\n\
+      curl-based HTTP and HTTPS (incl. Guzzle's default handler) are captured\n\
+      with zero application changes.  Requires PHP >= 5.3.7 for curl.cainfo;\n\
+      only the curl extension is covered (not PHP streams).\n\
+\n\
+    • Other commands  (`phantom run -- curl http://api.example.com/v1`)\n\
+      HTTP_PROXY / HTTPS_PROXY (and lowercase variants) are set automatically.\n\
+      Plain HTTP is captured; HTTPS is captured if the application honours\n\
+      these env vars for CONNECT tunnelling (as libcurl does by default).\n\
+\n\
+    • Manual  (start phantom alone, then configure your app)\n\
+      Set HTTP_PROXY=http://127.0.0.1:8080 in the target process yourself.\n\
+\n\
+  ldpreload  (Linux only)\n\
+    Injects libphantom_agent.so via LD_PRELOAD.  Hooks send/recv/close at\n\
+    the libc level for plain HTTP, and OpenSSL SSL_write/SSL_read for HTTPS\n\
+    (captured above the TLS layer, before encryption). No proxy config\n\
+    required and no MITM certificate involved — works for any dynamically\n\
+    linked process, language-agnostic (e.g. PHP's curl extension).\n\
+\n\
+━━━ OUTPUT MODES ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n\
+\n\
+  tui   (default) — Interactive terminal UI with trace list + detail view.\n\
+\n\
+  jsonl — One JSON object per line on stdout.  phantom exits automatically\n\
+          when the child process exits, propagating its exit code (ideal\n\
+          for scripting and AI agents).\n\
+\n\
+  JSONL record schema (all fields always present unless marked optional):\n\
+    trace_id                 string   W3C-compatible 128-bit trace ID (hex, 32 chars)\n\
+    span_id                  string   64-bit span ID (hex, 16 chars)\n\
+    timestamp_ms             number   Unix epoch milliseconds — request start time\n\
+    duration_ms              number   Round-trip latency in milliseconds\n\
+    method                   string   HTTP verb: \"GET\", \"POST\", \"PUT\", \"DELETE\", …\n\
+    url                      string   Full request URL (scheme + host + path + query)\n\
+    status_code              number   HTTP response status code (200, 404, 500, …)\n\
+    protocol_version         string   HTTP version string, e.g. \"HTTP/1.1\"\n\
+    request_headers          object   Lower-cased header names → values\n\
+    response_headers         object   Lower-cased header names → values\n\
+    request_body             string?  UTF-8 decoded body; omitted when empty\n\
+    response_body            string?  UTF-8 decoded body; omitted when empty\n\
+    request_body_bytes       number?  Original body size; present when a body existed\n\
+    response_body_bytes      number?  Original body size; present when a body existed\n\
+    request_body_truncated   bool?    Present (true) when --max-body truncated the body\n\
+    response_body_truncated  bool?    Present (true) when --max-body truncated the body\n\
+    source_addr              string?  Client socket address, e.g. \"127.0.0.1:54321\"\n\
+    dest_addr                string?  Server socket address, e.g. \"93.184.216.34:443\"",
+    after_long_help = "EXAMPLES\n\
+\n\
+  # Trace a Node.js app — HTTP + HTTPS captured, zero app changes:\n\
+  phantom run -- node app.js\n\
+\n\
+  # Stream traces as JSONL for scripting / AI analysis:\n\
+  phantom run --output jsonl -- node app.js\n\
+\n\
+  # Truncate bodies to keep output small:\n\
+  phantom run --output jsonl --max-body 256 -- node app.js\n\
+\n\
+  # Filter errors with jq:\n\
+  phantom run --output jsonl -- node app.js | jq 'select(.status_code >= 400)'\n\
+\n\
+  # LD_PRELOAD mode (Linux only):\n\
+  cargo build -p phantom-agent\n\
+  phantom run --backend ldpreload \\\n\
+          --agent-lib ./target/debug/libphantom_agent.so \\\n\
+          -- curl http://api.example.com/v1/users"
+)]
+pub struct RunArgs {
+    /// Capture backend: 'proxy' (MITM, cross-platform) or 'ldpreload' (Linux, HTTP + HTTPS).
+    #[arg(short, long, value_enum, default_value = "proxy")]
+    pub backend: Backend,
+
+    /// Output mode: 'tui' opens the interactive UI; 'jsonl' streams one trace
+    /// per line to stdout and exits with the child's exit code when it finishes.
+    #[arg(short, long, value_enum, default_value = "tui")]
+    pub output: OutputMode,
+
+    /// TCP port the proxy listens on.
+    #[arg(short, long, default_value = "8080")]
+    pub port: u16,
+
+    /// Disable TLS certificate verification for connections to backend servers.
+    /// Use when tracing apps that talk to servers with self-signed certificates.
+    #[arg(long, default_value = "false")]
+    pub insecure: bool,
+
+    /// Path to libphantom_agent.so  [required for --backend ldpreload]
+    ///
+    /// Build with: cargo build -p phantom-agent
+    /// Then pass:  --agent-lib ./target/debug/libphantom_agent.so
+    #[arg(long, value_name = "PATH")]
+    pub agent_lib: Option<PathBuf>,
+
+    /// Inject faults into proxied requests (proxy backend only).
+    ///
+    /// SPEC formats:
+    ///   delay:100ms              fixed 100 ms delay on all requests
+    ///   delay:100ms-500ms        random delay in the given range
+    ///   delay:200ms:/api         delay only URLs containing "/api"
+    ///   error:503                return HTTP 503 for all requests
+    ///   error:503:0.5            return HTTP 503 with 50% probability
+    ///   error:500:0.1:/api       10% chance of HTTP 500 on URLs containing "/api"
+    ///
+    /// Rules are applied in order; delays and errors can be combined.
+    /// Repeat the flag to add multiple rules:
+    ///   --fault delay:50ms --fault error:500:0.1
+    #[arg(long, value_name = "SPEC")]
+    pub fault: Vec<String>,
+
+    /// Truncate request/response bodies to N bytes in JSONL output
+    /// (0 = unlimited). Truncated records carry `*_body_truncated: true`
+    /// and the original size in `*_body_bytes`.
+    #[arg(long, value_name = "N", default_value = "0")]
+    pub max_body: usize,
+
+    /// Omit request/response bodies from JSONL output entirely
+    /// (original sizes still reported in `*_body_bytes`).
+    #[arg(long)]
+    pub headers_only: bool,
+
+    /// Command to spawn and trace (everything after `--`).
+    ///
+    /// proxy mode:     HTTP_PROXY is set automatically; Node.js additionally
+    ///                 gets proxy-preload.js injected via --require (captures HTTPS too).
+    /// ldpreload mode: LD_PRELOAD + PHANTOM_SOCKET are set automatically.
+    #[arg(last = true, value_name = "CMD")]
+    pub command: Vec<String>,
+}
+
+/// Filter and rendering flags shared by `list` and `search`.
+#[derive(Args)]
+pub struct FilterArgs {
+    /// Only these HTTP methods (repeatable): --method GET --method POST
+    #[arg(long = "method", value_name = "METHOD")]
+    pub methods: Vec<HttpMethod>,
+
+    /// Status code filter: exact ("404"), class ("4xx"), or range ("400-499").
+    #[arg(long, value_name = "RANGE")]
+    pub status: Option<StatusRange>,
+
+    /// Only traces newer than this: RFC3339 ("2026-07-12T10:00:00Z")
+    /// or a relative duration ago ("30s", "10m", "2h").
+    #[arg(long, value_name = "TIME")]
+    pub since: Option<String>,
+
+    /// Only traces older than this: RFC3339 or a relative duration ago.
+    #[arg(long, value_name = "TIME")]
+    pub until: Option<String>,
+
+    /// Only spans belonging to this 32-char hex trace ID.
+    #[arg(long, value_name = "HEX32")]
+    pub trace_id: Option<String>,
+
+    /// Maximum number of traces to return.
+    #[arg(long, default_value = "50")]
+    pub limit: usize,
+
+    /// Number of matching traces to skip (for pagination).
+    #[arg(long, default_value = "0")]
+    pub offset: usize,
+
+    /// Output format.
+    #[arg(long, value_enum, default_value = "jsonl")]
+    pub format: QueryFormat,
+
+    /// Truncate bodies to N bytes (0 = unlimited).
+    #[arg(long, value_name = "N", default_value = "1024")]
+    pub max_body: usize,
+
+    /// Omit bodies entirely (original sizes still reported).
+    #[arg(long)]
+    pub headers_only: bool,
+
+    /// Replace this header's value with "[redacted]" (repeatable).
+    #[arg(long = "redact-header", value_name = "NAME")]
+    pub redact_headers: Vec<String>,
+}
+
+#[derive(Args)]
+#[command(after_long_help = "EXAMPLES\n\
+\n\
+  # Recent failures, compact:\n\
+  phantom list --status 5xx --limit 10 --format table\n\
+\n\
+  # POSTs to the users API in the last 10 minutes, as JSONL for jq:\n\
+  phantom list --method POST --url /api/users --since 10m | jq .url\n\
+\n\
+  # Everything from one distributed trace:\n\
+  phantom list --trace-id 0123456789abcdef0123456789abcdef")]
+pub struct ListArgs {
+    /// Only URLs containing this substring (case-insensitive).
+    #[arg(long, value_name = "SUBSTR")]
+    pub url: Option<String>,
+
+    #[command(flatten)]
+    pub filter: FilterArgs,
+}
+
+#[derive(Args)]
+pub struct SearchArgs {
+    /// URL substring to search for (case-insensitive).
+    pub pattern: String,
+
+    #[command(flatten)]
+    pub filter: FilterArgs,
+}
+
+#[derive(Args)]
+pub struct GetArgs {
+    /// 16-character hex span ID (as shown by `phantom list`).
+    pub span_id: String,
+
+    /// Output format ('json' is pretty-printed; 'jsonl' is one compact line).
+    #[arg(long, value_enum, default_value = "json")]
+    pub format: QueryFormat,
+
+    /// Truncate bodies to N bytes (0 = unlimited).
+    #[arg(long, value_name = "N", default_value = "0")]
+    pub max_body: usize,
+
+    /// Omit bodies entirely (original sizes still reported).
+    #[arg(long)]
+    pub headers_only: bool,
+}
+
+#[derive(Args)]
+pub struct ClearArgs {
+    /// Confirm deletion (required; refuses to run without it).
+    #[arg(long)]
+    pub yes: bool,
+}
+
+/// Resolved global flags passed to command handlers.
+pub struct GlobalOpts {
+    pub quiet: bool,
+    pub data_dir: PathBuf,
+}
+
+pub fn default_data_dir() -> PathBuf {
+    dirs::data_local_dir()
+        .unwrap_or_else(|| PathBuf::from("."))
+        .join("phantom")
+        .join("data")
+}
diff --git a/src/commands/mod.rs b/src/commands/mod.rs
new file mode 100644
index 0000000..d4c26e9
--- /dev/null
+++ b/src/commands/mod.rs
@@ -0,0 +1,2 @@
+pub mod query;
+pub mod run;
diff --git a/src/commands/query.rs b/src/commands/query.rs
new file mode 100644
index 0000000..e7c9c48
--- /dev/null
+++ b/src/commands/query.rs
@@ -0,0 +1,229 @@
+use std::time::SystemTime;
+
+use phantom_core::query::TraceQuery;
+use phantom_core::storage::TraceStore;
+use phantom_core::trace::{HttpTrace, SpanId, TraceId};
+use phantom_core::view::{RenderOptions, TraceView};
+
+use crate::cli::{FilterArgs, GetArgs, ListArgs, QueryFormat, SearchArgs};
+
+/// Parse a `--since`/`--until` value: RFC3339 timestamp, or a relative
+/// duration meaning "that long ago" (e.g. "30s", "10m", "2h").
+fn parse_time(s: &str) -> anyhow::Result<SystemTime> {
+    if let Ok(duration) = humantime::parse_duration(s) {
+        return SystemTime::now()
+            .checked_sub(duration)
+            .ok_or_else(|| anyhow::anyhow!("relative time {s:?} is before the epoch"));
+    }
+    humantime::parse_rfc3339(s).map_err(|e| {
+        anyhow::anyhow!(
+            "invalid time {s:?}: {e} (expected RFC3339 like \"2026-07-12T10:00:00Z\" \
+             or a relative duration like \"10m\")"
+        )
+    })
+}
+
+fn build_query(url: Option<String>, filter: &FilterArgs) -> anyhow::Result<TraceQuery> {
+    let trace_id = filter
+        .trace_id
+        .as_deref()
+        .map(|s| {
+            TraceId::from_hex(s)
+                .ok_or_else(|| anyhow::anyhow!("invalid trace ID {s:?}: expected 32 hex chars"))
+        })
+        .transpose()?;
+
+    Ok(TraceQuery {
+        methods: filter.methods.clone(),
+        status: filter.status,
+        url_contains: url,
+        since: filter.since.as_deref().map(parse_time).transpose()?,
+        until: filter.until.as_deref().map(parse_time).transpose()?,
+        trace_id,
+        limit: filter.limit,
+        offset: filter.offset,
+    })
+}
+
+fn render_options(max_body: usize, headers_only: bool, redact: &[String]) -> RenderOptions {
+    RenderOptions {
+        max_body: (max_body > 0).then_some(max_body),
+        headers_only,
+        redact_headers: redact.iter().map(|h| h.to_lowercase()).collect(),
+    }
+}
+
+fn print_table(views: &[TraceView]) {
+    println!(
+        "{:<24}  {:<7}  {:>6}  {:>8}  {:<17}  URL",
+        "TIME", "METHOD", "STATUS", "DURATION", "SPAN_ID"
+    );
+    for v in views {
+        let time = humantime::format_rfc3339_millis(
+            std::time::UNIX_EPOCH + std::time::Duration::from_millis(v.timestamp_ms),
+        );
+        println!(
+            "{:<24}  {:<7}  {:>6}  {:>6}ms  {:<17}  {}",
+            time, v.method, v.status_code, v.duration_ms, v.span_id, v.url
+        );
+    }
+}
+
+fn output_traces(
+    traces: &[HttpTrace],
+    format: QueryFormat,
+    opts: &RenderOptions,
+) -> anyhow::Result<()> {
+    let views: Vec<TraceView> = traces.iter().map(|t| TraceView::render(t, opts)).collect();
+    match format {
+        QueryFormat::Jsonl => {
+            for view in &views {
+                println!("{}", serde_json::to_string(view)?);
+            }
+        }
+        QueryFormat::Json => println!("{}", serde_json::to_string_pretty(&views)?),
+        QueryFormat::Table => print_table(&views),
+    }
+    Ok(())
+}
+
+pub fn list(store: &dyn TraceStore, args: ListArgs) -> anyhow::Result<()> {
+    let query = build_query(args.url, &args.filter)?;
+    let traces = store.query(&query)?;
+    let opts = render_options(
+        args.filter.max_body,
+        args.filter.headers_only,
+        &args.filter.redact_headers,
+    );
+    output_traces(&traces, args.filter.format, &opts)
+}
+
+pub fn search(store: &dyn TraceStore, args: SearchArgs) -> anyhow::Result<()> {
+    let query = build_query(Some(args.pattern), &args.filter)?;
+    let traces = store.query(&query)?;
+    let opts = render_options(
+        args.filter.max_body,
+        args.filter.headers_only,
+        &args.filter.redact_headers,
+    );
+    output_traces(&traces, args.filter.format, &opts)
+}
+
+/// Returns `false` (exit code 1) when the span ID is unknown.
+pub fn get(store: &dyn TraceStore, args: GetArgs) -> anyhow::Result<bool> {
+    let span_id = SpanId::from_hex(&args.span_id).ok_or_else(|| {
+        anyhow::anyhow!("invalid span ID {:?}: expected 16 hex chars", args.span_id)
+    })?;
+
+    let Some(trace) = store.get_by_span_id(&span_id)? else {
+        eprintln!("phantom: no trace found for span ID {}", args.span_id);
+        return Ok(false);
+    };
+
+    let opts = render_options(args.max_body, args.headers_only, &[]);
+    let view = TraceView::render(&trace, &opts);
+    match args.format {
+        QueryFormat::Jsonl => println!("{}", serde_json::to_string(&view)?),
+        _ => println!("{}", serde_json::to_string_pretty(&view)?),
+    }
+    Ok(true)
+}
+
+pub fn stats(store: &dyn TraceStore, data_dir: &std::path::Path) -> anyhow::Result<()> {
+    println!(
+        "{}",
+        serde_json::json!({
+            "total_traces": store.count()?,
+            "data_dir": data_dir.display().to_string(),
+        })
+    );
+    Ok(())
+}
+
+/// Returns `false` (exit code 1) when `--yes` was not passed.
+pub fn clear(store: &dyn TraceStore, yes: bool, quiet: bool) -> anyhow::Result<bool> {
+    if !yes {
+        eprintln!("phantom: refusing to delete all traces without --yes");
+        return Ok(false);
+    }
+    store.clear()?;
+    if !quiet {
+        eprintln!("phantom: all traces cleared");
+    }
+    Ok(true)
+}
+
+#[cfg(test)]
+mod tests {
+    use std::time::{Duration, UNIX_EPOCH};
+
+    use super::*;
+
+    #[test]
+    fn test_parse_time_rfc3339() {
+        let t = parse_time("2026-01-01T00:00:00Z").unwrap();
+        assert_eq!(t, UNIX_EPOCH + Duration::from_secs(1_767_225_600));
+    }
+
+    #[test]
+    fn test_parse_time_relative_means_ago() {
+        let before = SystemTime::now();
+        let t = parse_time("10m").unwrap();
+        let ago = before.duration_since(t).unwrap();
+        // Within a small tolerance of exactly 10 minutes before "now".
+        assert!(
+            ago >= Duration::from_secs(599) && ago <= Duration::from_secs(601),
+            "expected ~600s ago, got {ago:?}"
+        );
+    }
+
+    #[test]
+    fn test_parse_time_relative_units() {
+        for (input, secs) in [("30s", 30), ("2h", 7200), ("1d", 86400)] {
+            let t = parse_time(input).unwrap();
+            let ago = SystemTime::now().duration_since(t).unwrap().as_secs();
+            assert!(
+                ago.abs_diff(secs) <= 1,
+                "{input}: expected ~{secs}s ago, got {ago}s"
+            );
+        }
+    }
+
+    #[test]
+    fn test_parse_time_rejects_garbage() {
+        for input in ["", "yesterday", "2026-13-01T00:00:00Z", "10 parsecs"] {
+            assert!(parse_time(input).is_err(), "{input:?} should not parse");
+        }
+    }
+
+    #[test]
+    fn test_build_query_rejects_bad_trace_id() {
+        let filter = FilterArgs {
+            methods: Vec::new(),
+            status: None,
+            since: None,
+            until: None,
+            trace_id: Some("not-hex".to_string()),
+            limit: 50,
+            offset: 0,
+            format: QueryFormat::Jsonl,
+            max_body: 0,
+            headers_only: false,
+            redact_headers: Vec::new(),
+        };
+        let err = build_query(None, &filter).unwrap_err();
+        assert!(err.to_string().contains("invalid trace ID"));
+    }
+
+    #[test]
+    fn test_render_options_zero_max_body_means_unlimited() {
+        assert_eq!(render_options(0, false, &[]).max_body, None);
+        assert_eq!(render_options(16, false, &[]).max_body, Some(16));
+    }
+
+    #[test]
+    fn test_render_options_lowercases_redact_headers() {
+        let opts = render_options(0, false, &["X-Api-Key".to_string()]);
+        assert_eq!(opts.redact_headers, ["x-api-key"]);
+    }
+}
diff --git a/src/commands/run.rs b/src/commands/run.rs
new file mode 100644
index 0000000..57c6f74
--- /dev/null
+++ b/src/commands/run.rs
@@ -0,0 +1,251 @@
+use std::process::ExitStatus;
+use std::sync::Arc;
+
+use phantom_capture::ProxyCaptureBackend;
+use phantom_core::capture::CaptureBackend;
+use phantom_core::storage::TraceStore;
+use phantom_core::trace::HttpTrace;
+use phantom_core::view::{RenderOptions, TraceView};
+use phantom_storage::FjallTraceStore;
+
+use crate::cli::{GlobalOpts, OutputMode, RunArgs};
+use crate::runner::{TempScript, build_fault_config, spawn_proxy_child, wait_for_proxy};
+
+/// Render options for the JSONL stream, from `run` flags.
+fn jsonl_render_options(args: &RunArgs) -> RenderOptions {
+    RenderOptions {
+        max_body: (args.max_body > 0).then_some(args.max_body),
+        headers_only: args.headers_only,
+        redact_headers: Vec::new(),
+    }
+}
+
+/// Runs the JSONL output loop: each captured trace is serialized and written to
+/// stdout as a single JSON object followed by a newline.
+///
+/// Exits when:
+/// - The trace channel is closed (sender dropped),
+/// - Ctrl-C is received, or
+/// - The optional `child` process exits.
+///
+/// Returns the child's exit status (when a child was spawned and exited) so
+/// the caller can propagate its exit code.
+async fn run_jsonl_output(
+    store: Arc<FjallTraceStore>,
+    mut trace_rx: tokio::sync::mpsc::Receiver<HttpTrace>,
+    child: Option<std::process::Child>,
+    opts: &RenderOptions,
+    quiet: bool,
+) -> anyhow::Result<Option<ExitStatus>> {
+    // Spawn a background thread to wait() on the child so we don't block the
+    // async executor.  The child's exit status is sent through a oneshot.
+    let mut child_done: Option<tokio::sync::oneshot::Receiver<std::io::Result<ExitStatus>>> =
+        if let Some(mut c) = child {
+            let (tx, rx) = tokio::sync::oneshot::channel();
+            std::thread::spawn(move || {
+                let _ = tx.send(c.wait());
+            });
+            Some(rx)
+        } else {
+            None
+        };
+
+    let ctrl_c = tokio::signal::ctrl_c();
+    tokio::pin!(ctrl_c);
+
+    let mut traces_captured: u64 = 0;
+    let mut child_status: Option<ExitStatus> = None;
+
+    let mut emit = |t: &HttpTrace| -> anyhow::Result<()> {
+        store.insert(t).ok();
+        println!("{}", serde_json::to_string(&TraceView::render(t, opts))?);
+        traces_captured += 1;
+        Ok(())
+    };
+
+    loop {
+        tokio::select! {
+            maybe_trace = trace_rx.recv() => {
+                match maybe_trace {
+                    Some(t) => emit(&t)?,
+                    None => break,
+                }
+            }
+            _ = &mut ctrl_c => break,
+            // When the child exits, wait briefly for the backend to flush any
+            // in-flight datagrams, then drain whatever arrived.
+            status = async {
+                if let Some(rx) = child_done.as_mut() {
+                    rx.await
+                } else {
+                    std::future::pending().await
+                }
+            } => {
+                if let Ok(Ok(status)) = status {
+                    child_status = Some(status);
+                }
+                tokio::time::sleep(std::time::Duration::from_millis(200)).await;
+                while let Ok(t) = trace_rx.try_recv() {
+                    emit(&t)?;
+                }
+                break;
+            }
+        }
+    }
+
+    if !quiet {
+        // Machine-readable end-of-run summary on stderr (stdout stays pure JSONL).
+        eprintln!(
+            "{}",
+            serde_json::json!({
+                "event": "exit",
+                "child_exit_code": child_status.and_then(|s| s.code()),
+                "traces_captured": traces_captured,
+            })
+        );
+    }
+
+    Ok(child_status)
+}
+
+pub async fn run_proxy(
+    globals: &GlobalOpts,
+    args: RunArgs,
+    store: Arc<FjallTraceStore>,
+) -> anyhow::Result<Option<ExitStatus>> {
+    let fault_config = build_fault_config(&args.fault)?;
+    let mut backend = ProxyCaptureBackend::new(args.port, args.insecure).with_faults(fault_config);
+    let backend_name = backend.name().to_string();
+    let trace_rx = backend.start().map_err(|e| anyhow::anyhow!("{e}"))?;
+
+    // Optionally spawn a child command routed through the proxy.
+    let child_and_script: Option<(std::process::Child, Option<TempScript>)> =
+        if !args.command.is_empty() {
+            // Wait for the proxy to be ready before spawning the child.
+            wait_for_proxy(args.port).await?;
+            let ca_cert_pem = backend.ca_cert_pem();
+            let (child, ts) = spawn_proxy_child(&args.command, args.port, ca_cert_pem.as_deref())?;
+            if !globals.quiet {
+                eprintln!(
+                    "phantom: spawned PID {} → {}",
+                    child.id(),
+                    args.command.join(" ")
+                );
+            }
+            Some((child, ts))
+        } else {
+            None
+        };
+
+    let mut child_status = None;
+    match args.output {
+        OutputMode::Tui => {
+            if !globals.quiet {
+                if args.command.is_empty() {
+                    eprintln!("phantom: proxy listening on 127.0.0.1:{}", args.port);
+                    eprintln!("  Set your HTTP proxy to http://127.0.0.1:{}", args.port);
+                    eprintln!(
+                        "  Example: curl -x http://127.0.0.1:{} http://httpbin.org/get",
+                        args.port
+                    );
+                }
+                eprintln!("phantom: traces stored in {}", globals.data_dir.display());
+            }
+            phantom_tui::run_tui(store, trace_rx, &backend_name).await?;
+        }
+        OutputMode::Jsonl => {
+            if !globals.quiet {
+                eprintln!(
+                    "phantom: proxy listening on 127.0.0.1:{} [jsonl mode]",
+                    args.port
+                );
+            }
+            // Split into child and script guard separately so the TempScript
+            // is NOT dropped until after run_jsonl_output completes (the file
+            // must exist while node is loading it via --require).
+            let (child, _script_guard) = match child_and_script {
+                Some((c, ts)) => (Some(c), ts),
+                None => (None, None),
+            };
+            let opts = jsonl_render_options(&args);
+            child_status = run_jsonl_output(store, trace_rx, child, &opts, globals.quiet).await?;
+            // _script_guard dropped here — temp file deleted after child exits.
+        }
+    }
+
+    backend.stop().map_err(|e| anyhow::anyhow!("{e}"))?;
+    Ok(child_status)
+}
+
+#[cfg(target_os = "linux")]
+pub async fn run_ldpreload(
+    globals: &GlobalOpts,
+    args: RunArgs,
+    store: Arc<FjallTraceStore>,
+) -> anyhow::Result<Option<ExitStatus>> {
+    use phantom_capture::LdPreloadCaptureBackend;
+
+    let agent_lib = args.agent_lib.clone().ok_or_else(|| {
+        anyhow::anyhow!(
+            "--agent-lib <PATH> is required for --backend ldpreload\n\
+            Example: --agent-lib ./target/debug/libphantom_agent.so"
+        )
+    })?;
+
+    if args.command.is_empty() {
+        anyhow::bail!(
+            "A command to trace is required for --backend ldpreload.\n\
+            Usage: phantom run --backend ldpreload --agent-lib ./libphantom_agent.so -- curl http://example.com"
+        );
+    }
+
+    // Generate a unique socket path for this run.
+    let socket_path = std::env::temp_dir().join(format!(
+        "phantom-{}.sock",
+        std::time::SystemTime::now()
+            .duration_since(std::time::UNIX_EPOCH)
+            .map(|d| d.as_millis())
+            .unwrap_or(0)
+    ));
+
+    let mut backend = LdPreloadCaptureBackend::new(socket_path.clone());
+    let backend_name = backend.name().to_string();
+    let trace_rx = backend.start().map_err(|e| anyhow::anyhow!("{e}"))?;
+
+    if !globals.quiet {
+        eprintln!("phantom: ldpreload backend active");
+        eprintln!("  agent lib : {}", agent_lib.display());
+        eprintln!("  socket    : {}", socket_path.display());
+        eprintln!("  command   : {}", args.command.join(" "));
+        eprintln!("phantom: traces stored in {}", globals.data_dir.display());
+    }
+
+    // Spawn the target process with LD_PRELOAD and PHANTOM_SOCKET set.
+    let child = std::process::Command::new(&args.command[0])
+        .args(&args.command[1..])
+        .env("LD_PRELOAD", &agent_lib)
+        .env("PHANTOM_SOCKET", &socket_path)
+        .spawn()
+        .map_err(|e| anyhow::anyhow!("failed to spawn {:?}: {e}", args.command[0]))?;
+
+    if !globals.quiet {
+        eprintln!("phantom: spawned PID {}", child.id());
+    }
+
+    let mut child_status = None;
+    match args.output {
+        OutputMode::Tui => {
+            // In TUI mode the user quits manually; child runs in background.
+            phantom_tui::run_tui(store, trace_rx, &backend_name).await?;
+        }
+        OutputMode::Jsonl => {
+            // In JSONL mode we exit automatically when the child finishes.
+            let opts = jsonl_render_options(&args);
+            child_status =
+                run_jsonl_output(store, trace_rx, Some(child), &opts, globals.quiet).await?;
+        }
+    }
+
+    backend.stop().map_err(|e| anyhow::anyhow!("{e}"))?;
+    Ok(child_status)
+}
diff --git a/src/main.rs b/src/main.rs
index 1ecaaf9..0037fe2 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -1,708 +1,119 @@
-use std::path::{Path, PathBuf};
+mod cli;
+mod commands;
+mod mcp;
+mod runner;
+
+use std::process::ExitCode;
 use std::sync::Arc;
-use std::time::UNIX_EPOCH;
 
-use clap::{Parser, ValueEnum};
-use phantom_capture::{FaultConfig, ProxyCaptureBackend};
-use phantom_core::capture::CaptureBackend;
-use phantom_core::storage::TraceStore;
-use phantom_core::trace::HttpTrace;
+use clap::Parser;
 use phantom_storage::FjallTraceStore;
-use serde::Serialize;
-
-// ─────────────────────────────────────────────────────────────────────────────
-// Embedded proxy preload script (Node.js transparent injection)
-// ─────────────────────────────────────────────────────────────────────────────
-
-/// The proxy-preload.js content, embedded at compile time.
-/// Written to a temp file when tracing Node.js processes via `phantom -- node …`.
-const NODE_PROXY_PRELOAD: &str = include_str!("../tests/apps/node-app/proxy-preload.js");
-
-/// The Java Agent JAR, embedded at compile time.
-/// Written to a temp file when tracing Java processes via `phantom -- java …`.
-const JAVA_AGENT_JAR: &[u8] = include_bytes!("../crates/phantom-java-agent/phantom-java-agent.jar");
-
-// ─────────────────────────────────────────────────────────────────────────────
-// CLI
-// ─────────────────────────────────────────────────────────────────────────────
-
-#[derive(Debug, Clone, ValueEnum)]
-enum Backend {
-    /// MITM proxy — captures HTTP + HTTPS, cross-platform. Node.js HTTPS injected automatically.
-    Proxy,
-    /// LD_PRELOAD agent — captures HTTP + HTTPS, Linux only. No proxy config needed.
-    #[cfg(target_os = "linux")]
-    Ldpreload,
-}
-
-#[derive(Debug, Clone, Default, ValueEnum)]
-enum OutputMode {
-    /// Interactive terminal UI with trace list and detail view.
-    #[default]
-    Tui,
-    /// Stream traces as JSON Lines to stdout; auto-exits when child process finishes.
-    Jsonl,
-}
-
-#[derive(Parser)]
-#[command(
-    name = "phantom",
-    about = "Zero-instrumentation HTTP/HTTPS API observability tool",
-    long_about = "phantom — Zero-instrumentation HTTP/HTTPS API observability\n\
-\n\
-Captures every HTTP and HTTPS request/response made by a target process\n\
-and displays them in an interactive TUI or streams them as JSON Lines.\n\
-The target application requires NO code changes.\n\
-\n\
-━━━ CAPTURE BACKENDS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n\
-\n\
-  proxy  (default, cross-platform)\n\
-    Starts a MITM proxy on 127.0.0.1:<PORT>.  Intercepts HTTP and HTTPS.\n\
-\n\
-    • Node.js  (`phantom -- node app.js`)\n\
-      proxy-preload.js is injected automatically via --require.  Both http://\n\
-      and https:// are captured with zero application changes.\n\
-\n\
-    • PHP  (`phantom -- php app.php`)\n\
-      The MITM CA certificate is injected automatically via -d curl.cainfo=.\n\
-      curl-based HTTP and HTTPS (incl. Guzzle's default handler) are captured\n\
-      with zero application changes.  Requires PHP >= 5.3.7 for curl.cainfo;\n\
-      only the curl extension is covered (not PHP streams).\n\
-\n\
-    • Other commands  (`phantom -- curl http://api.example.com/v1`)\n\
-      HTTP_PROXY / HTTPS_PROXY (and lowercase variants) are set automatically.\n\
-      Plain HTTP is captured; HTTPS is captured if the application honours\n\
-      these env vars for CONNECT tunnelling (as libcurl does by default).\n\
-\n\
-    • Manual  (start phantom alone, then configure your app)\n\
-      Set HTTP_PROXY=http://127.0.0.1:8080 in the target process yourself.\n\
-\n\
-  ldpreload  (Linux only)\n\
-    Injects libphantom_agent.so via LD_PRELOAD.  Hooks send/recv/close at\n\
-    the libc level for plain HTTP, and OpenSSL SSL_write/SSL_read for HTTPS\n\
-    (captured above the TLS layer, before encryption). No proxy config\n\
-    required and no MITM certificate involved — works for any dynamically\n\
-    linked process, language-agnostic (e.g. PHP's curl extension).\n\
-\n\
-━━━ OUTPUT MODES ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n\
-\n\
-  tui   (default) — Interactive terminal UI with trace list + detail view.\n\
-\n\
-  jsonl — One JSON object per line on stdout.  phantom exits automatically\n\
-          when the child process exits (ideal for scripting and AI agents).\n\
-\n\
-  JSONL record schema (all fields always present unless marked optional):\n\
-    trace_id          string   W3C-compatible 128-bit trace ID (hex, 32 chars)\n\
-    span_id           string   64-bit span ID (hex, 16 chars)\n\
-    timestamp_ms      number   Unix epoch milliseconds — request start time\n\
-    duration_ms       number   Round-trip latency in milliseconds\n\
-    method            string   HTTP verb: \"GET\", \"POST\", \"PUT\", \"DELETE\", …\n\
-    url               string   Full request URL (scheme + host + path + query)\n\
-    status_code       number   HTTP response status code (200, 404, 500, …)\n\
-    protocol_version  string   HTTP version string, e.g. \"HTTP/1.1\"\n\
-    request_headers   object   Lower-cased header names → values\n\
-    response_headers  object   Lower-cased header names → values\n\
-    request_body      string?  UTF-8 decoded body; omitted when empty\n\
-    response_body     string?  UTF-8 decoded body; omitted when empty\n\
-    source_addr       string?  Client socket address, e.g. \"127.0.0.1:54321\"\n\
-    dest_addr         string?  Server socket address, e.g. \"93.184.216.34:443\"",
-    after_long_help = "EXAMPLES\n\
-\n\
-  ┌─ Proxy mode (default) ──────────────────────────────────────────────────┐\n\
-\n\
-  # Trace a Node.js app — HTTP + HTTPS captured, zero app changes:\n\
-  phantom -- node app.js\n\
-\n\
-  # Stream traces as JSONL for scripting / AI analysis:\n\
-  phantom --output jsonl -- node app.js\n\
-\n\
-  # Allow self-signed TLS certs on backend servers:\n\
-  phantom --insecure --output jsonl -- node app.js\n\
-\n\
-  # Trace a PHP app — curl-based HTTP + HTTPS captured, zero app changes:\n\
-  phantom -- php app.php\n\
-\n\
-  # Trace any command (plain HTTP only, HTTPS if app uses HTTP_PROXY CONNECT):\n\
-  phantom -- curl http://api.example.com/v1/users\n\
-\n\
-  # Start proxy only, configure target app manually:\n\
-  phantom\n\
-  # then in another shell:\n\
-  HTTP_PROXY=http://127.0.0.1:8080 node app.js\n\
-\n\
-  # Custom port, custom data directory:\n\
-  phantom --port 9090 --data-dir ./traces -- node app.js\n\
-\n\
-  └─────────────────────────────────────────────────────────────────────────┘\n\
-\n\
-  ┌─ LD_PRELOAD mode (Linux only) ──────────────────────────────────────────┐\n\
-\n\
-  # Build the agent first:\n\
-  cargo build -p phantom-agent\n\
-\n\
-  # Trace a process (HTTP + HTTPS, no MITM certificate needed):\n\
-  phantom --backend ldpreload \\\n\
-          --agent-lib ./target/debug/libphantom_agent.so \\\n\
-          -- curl http://api.example.com/v1/users\n\
-\n\
-  └─────────────────────────────────────────────────────────────────────────┘\n\
-\n\
-  ┌─ Consume JSONL from another process ────────────────────────────────────┐\n\
-\n\
-  phantom --output jsonl -- node app.js \\\n\
-    | jq 'select(.status_code >= 400)'          # filter errors\n\
-\n\
-  phantom --output jsonl -- node app.js \\\n\
-    | jq '{method,url,status_code,duration_ms}' # compact summary\n\
-\n\
-  └─────────────────────────────────────────────────────────────────────────┘",
-    version
-)]
-struct Cli {
-    /// Capture backend: 'proxy' (MITM, cross-platform) or 'ldpreload' (Linux, HTTP + HTTPS).
-    #[arg(short, long, value_enum, default_value = "proxy")]
-    backend: Backend,
-
-    /// Output mode: 'tui' opens the interactive UI; 'jsonl' streams one trace
-    /// per line to stdout and exits when the child process finishes.
-    #[arg(short, long, value_enum, default_value = "tui")]
-    output: OutputMode,
-
-    /// TCP port the proxy listens on.
-    #[arg(short, long, default_value = "8080")]
-    port: u16,
-
-    /// Disable TLS certificate verification for connections to backend servers.
-    /// Use when tracing apps that talk to servers with self-signed certificates.
-    #[arg(long, default_value = "false")]
-    insecure: bool,
-
-    /// Directory where captured traces are persisted (Fjall key-value store).
-    /// Defaults to the platform data directory, e.g. ~/.local/share/phantom/data.
-    #[arg(short, long)]
-    data_dir: Option<PathBuf>,
 
-    /// Path to libphantom_agent.so  [required for --backend ldpreload]
-    ///
-    /// Build with: cargo build -p phantom-agent
-    /// Then pass:  --agent-lib ./target/debug/libphantom_agent.so
-    #[arg(long, value_name = "PATH")]
-    agent_lib: Option<PathBuf>,
+use cli::{Backend, Cli, Commands, GlobalOpts, default_data_dir};
 
-    /// Inject faults into proxied requests (proxy backend only).
-    ///
-    /// SPEC formats:
-    ///   delay:100ms              fixed 100 ms delay on all requests
-    ///   delay:100ms-500ms        random delay in the given range
-    ///   delay:200ms:/api         delay only URLs containing "/api"
-    ///   error:503                return HTTP 503 for all requests
-    ///   error:503:0.5            return HTTP 503 with 50% probability
-    ///   error:500:0.1:/api       10% chance of HTTP 500 on URLs containing "/api"
-    ///
-    /// Rules are applied in order; delays and errors can be combined.
-    /// Repeat the flag to add multiple rules:
-    ///   --fault delay:50ms --fault error:500:0.1
-    #[arg(long, value_name = "SPEC")]
-    fault: Vec<String>,
-
-    /// Command to spawn and trace (everything after `--`).
-    ///
-    /// proxy mode:     HTTP_PROXY is set automatically; Node.js additionally
-    ///                 gets proxy-preload.js injected via --require (captures HTTPS too).
-    /// ldpreload mode: LD_PRELOAD + PHANTOM_SOCKET are set automatically.
-    #[arg(last = true, value_name = "CMD")]
-    command: Vec<String>,
-}
-
-fn default_data_dir() -> PathBuf {
-    dirs::data_local_dir()
-        .unwrap_or_else(|| PathBuf::from("."))
-        .join("phantom")
-        .join("data")
-}
-
-// ─────────────────────────────────────────────────────────────────────────────
-// JSONL output
-// ─────────────────────────────────────────────────────────────────────────────
-
-/// Human-friendly, fully serializable representation of an `HttpTrace`.
-/// Emitted as one JSON object per line to stdout in `--output jsonl` mode.
-#[derive(Serialize)]
-struct JsonlTrace {
-    /// Unix timestamp of the request in milliseconds.
-    timestamp_ms: u64,
-    /// Round-trip duration in milliseconds.
-    duration_ms: u64,
-    /// HTTP method ("GET", "POST", …).
-    method: String,
-    /// Full request URL.
-    url: String,
-    /// HTTP response status code.
-    status_code: u16,
-    /// Request headers (lower-cased keys).
-    request_headers: std::collections::HashMap<String, String>,
-    /// Response headers (lower-cased keys).
-    response_headers: std::collections::HashMap<String, String>,
-    /// Request body decoded as UTF-8 (replacement chars for non-UTF-8 bytes).
-    #[serde(skip_serializing_if = "Option::is_none")]
-    request_body: Option<String>,
-    /// Response body decoded as UTF-8 (replacement chars for non-UTF-8 bytes).
-    #[serde(skip_serializing_if = "Option::is_none")]
-    response_body: Option<String>,
-    /// Source socket address, if available.
-    #[serde(skip_serializing_if = "Option::is_none")]
-    source_addr: Option<String>,
-    /// Destination socket address, if available.
-    #[serde(skip_serializing_if = "Option::is_none")]
-    dest_addr: Option<String>,
-    /// HTTP protocol version string (e.g. "HTTP/1.1").
-    protocol_version: String,
-    /// 128-bit W3C trace ID (hex).
-    trace_id: String,
-    /// 64-bit span ID (hex).
-    span_id: String,
-}
-
-fn body_to_str(body: &Option<Vec<u8>>) -> Option<String> {
-    body.as_ref()
-        .map(|b| String::from_utf8_lossy(b).into_owned())
-}
-
-fn trace_to_jsonl(t: &HttpTrace) -> JsonlTrace {
-    let timestamp_ms = t
-        .timestamp
-        .duration_since(UNIX_EPOCH)
-        .map(|d| d.as_millis() as u64)
-        .unwrap_or(0);
-
-    JsonlTrace {
-        timestamp_ms,
-        duration_ms: t.duration.as_millis() as u64,
-        method: t.method.to_string(),
-        url: t.url.clone(),
-        status_code: t.status_code,
-        request_headers: t.request_headers.clone(),
-        response_headers: t.response_headers.clone(),
-        request_body: body_to_str(&t.request_body),
-        response_body: body_to_str(&t.response_body),
-        source_addr: t.source_addr.clone(),
-        dest_addr: t.dest_addr.clone(),
-        protocol_version: t.protocol_version.clone(),
-        trace_id: t.trace_id.to_string(),
-        span_id: t.span_id.to_string(),
+/// Maps a child process's exit status onto our own exit code:
+/// the child's code clamped to u8, or 128+signal on Unix signal death.
+fn exit_code_from_status(status: std::process::ExitStatus) -> ExitCode {
+    if let Some(code) = status.code() {
+        return ExitCode::from(code.clamp(0, 255) as u8);
     }
-}
-
-/// Runs the JSONL output loop: each captured trace is serialized and written to
-/// stdout as a single JSON object followed by a newline.
-///
-/// Exits when:
-/// - The trace channel is closed (sender dropped),
-/// - Ctrl-C is received, or
-/// - The optional `child` process exits (ldpreload mode).
-async fn run_jsonl_output(
-    store: Arc<FjallTraceStore>,
-    mut trace_rx: tokio::sync::mpsc::Receiver<HttpTrace>,
-    child: Option<std::process::Child>,
-) -> anyhow::Result<()> {
-    // Spawn a background thread to wait() on the child so we don't block the
-    // async executor.  Signal completion via a oneshot channel.
-    let mut child_done: Option<tokio::sync::oneshot::Receiver<()>> = if let Some(mut c) = child {
-        let (tx, rx) = tokio::sync::oneshot::channel();
-        std::thread::spawn(move || {
-            let _ = c.wait();
-            let _ = tx.send(());
-        });
-        Some(rx)
-    } else {
-        None
-    };
-
-    let ctrl_c = tokio::signal::ctrl_c();
-    tokio::pin!(ctrl_c);
-
-    loop {
-        tokio::select! {
-            maybe_trace = trace_rx.recv() => {
-                match maybe_trace {
-                    Some(t) => {
-                        store.insert(&t).ok();
-                        println!("{}", serde_json::to_string(&trace_to_jsonl(&t))?);
-                    }
-                    None => break,
-                }
-            }
-            _ = &mut ctrl_c => break,
-            // When the child exits, wait briefly for the backend to flush any
-            // in-flight datagrams, then drain whatever arrived.
-            _ = async {
-                if let Some(rx) = child_done.as_mut() {
-                    let _ = rx.await;
-                } else {
-                    std::future::pending::<()>().await;
-                }
-            } => {
-                tokio::time::sleep(std::time::Duration::from_millis(200)).await;
-                while let Ok(t) = trace_rx.try_recv() {
-                    store.insert(&t).ok();
-                    println!("{}", serde_json::to_string(&trace_to_jsonl(&t))?);
-                }
-                break;
-            }
+    #[cfg(unix)]
+    {
+        use std::os::unix::process::ExitStatusExt;
+        if let Some(signal) = status.signal() {
+            return ExitCode::from(128u8.saturating_add(signal.clamp(0, 127) as u8));
         }
     }
-
-    Ok(())
+    ExitCode::FAILURE
 }
 
-// ─────────────────────────────────────────────────────────────────────────────
-// Main
-// ─────────────────────────────────────────────────────────────────────────────
+/// Opens the trace store for a query command, adding a hint about fjall's
+/// single-process lock when another phantom instance holds it.
+fn open_store_for_query(data_dir: &std::path::Path) -> anyhow::Result<FjallTraceStore> {
+    FjallTraceStore::open(data_dir).map_err(|e| {
+        anyhow::anyhow!(
+            "{e}\n\
+             hint: another phantom process (run/mcp) may hold the store lock on\n\
+             {}. Stop it first, or query through the running MCP server.",
+            data_dir.display()
+        )
+    })
+}
 
 #[tokio::main]
-async fn main() -> anyhow::Result<()> {
+async fn main() -> anyhow::Result<ExitCode> {
+    let cli = Cli::parse();
+
+    // All diagnostics go to stderr so stdout stays pure JSONL / JSON.
+    let default_directive = if cli.quiet {
+        "phantom=error"
+    } else {
+        "phantom=info"
+    };
     tracing_subscriber::fmt()
+        .with_writer(std::io::stderr)
         .with_env_filter(
             tracing_subscriber::EnvFilter::from_default_env()
-                .add_directive("phantom=info".parse()?),
+                .add_directive(default_directive.parse()?),
         )
         .init();
 
-    let cli = Cli::parse();
-
     let data_dir = cli.data_dir.clone().unwrap_or_else(default_data_dir);
     std::fs::create_dir_all(&data_dir)?;
+    let globals = GlobalOpts {
+        quiet: cli.quiet,
+        data_dir: data_dir.clone(),
+    };
 
-    let store = Arc::new(FjallTraceStore::open(&data_dir)?);
-
-    match cli.backend {
-        Backend::Proxy => run_proxy(cli, store).await,
-        #[cfg(target_os = "linux")]
-        Backend::Ldpreload => run_ldpreload(cli, store).await,
-    }
-}
-
-// ─────────────────────────────────────────────────────────────────────────────
-// Fault injection
-// ─────────────────────────────────────────────────────────────────────────────
-
-fn build_fault_config(specs: &[String]) -> anyhow::Result<FaultConfig> {
-    let mut rules = Vec::new();
-    for spec in specs {
-        let rule = phantom_capture::parse_fault_spec(spec)
-            .map_err(|e| anyhow::anyhow!("--fault {spec:?}: {e}"))?;
-        rules.push(rule);
-    }
-    Ok(FaultConfig { rules })
-}
-
-// ─────────────────────────────────────────────────────────────────────────────
-// Proxy backend
-// ─────────────────────────────────────────────────────────────────────────────
-
-/// RAII guard that deletes a temporary script file on drop.
-struct TempScript(PathBuf);
-
-impl Drop for TempScript {
-    fn drop(&mut self) {
-        let _ = std::fs::remove_file(&self.0);
-    }
-}
-
-/// Returns `true` if `exe` (path or bare name) resolves to `node` or `nodejs`.
-fn is_node_command(exe: &str) -> bool {
-    let base = Path::new(exe)
-        .file_name()
-        .and_then(|n| n.to_str())
-        .unwrap_or(exe);
-    base == "node" || base == "nodejs"
-}
-
-/// Returns `true` if `exe` (path or bare name) resolves to `java` or `javaw`.
-fn is_java_command(exe: &str) -> bool {
-    let base = Path::new(exe)
-        .file_name()
-        .and_then(|n| n.to_str())
-        .unwrap_or(exe);
-    base == "java" || base == "javaw"
-}
-
-/// Returns `true` if `exe` (path or bare name) resolves to `php` or a
-/// version-suffixed PHP binary (e.g. `php7.4`, `php8.2`, `php5.3`).
-fn is_php_command(exe: &str) -> bool {
-    let base = Path::new(exe)
-        .file_name()
-        .and_then(|n| n.to_str())
-        .unwrap_or(exe);
-    base == "php"
-        || (base.starts_with("php")
-            && !base[3..].is_empty()
-            && base[3..].chars().all(|c| c.is_ascii_digit() || c == '.'))
-}
-
-/// Spawns `command` as a child process routed through the phantom proxy.
-///
-/// * `HTTP_PROXY` / `HTTPS_PROXY` (and lowercase variants) are set so plain
-///   HTTP and HTTP-client-honoured HTTPS (e.g. libcurl) are captured.
-/// * For Node.js executables the embedded proxy-preload script is written to a
-///   temp file and prepended as `--require <path>` so HTTPS is also captured
-///   without touching the application source.
-/// * For Java executables, the phantom-java-agent.jar is injected via -javaagent
-///   to force proxy settings and bypass SSL verification globally.
-/// * For PHP executables, the MITM CA certificate is written to a temp PEM
-///   file and injected via `-d curl.cainfo=<path>` so the curl extension
-///   trusts phantom's HTTPS interception without any application changes.
-///
-/// Returns `(child, Option<TempScript>)`.  The `TempScript` must be kept alive
-/// until after the child exits so the file is not deleted prematurely.
-fn spawn_proxy_child(
-    command: &[String],
-    proxy_port: u16,
-    ca_cert_pem: Option<&str>,
-) -> anyhow::Result<(std::process::Child, Option<TempScript>)> {
-    let exe = &command[0];
-    let proxy_url = format!("http://127.0.0.1:{proxy_port}");
-
-    let mut temp_script: Option<TempScript> = None;
-    let mut actual_args = command[1..].to_vec();
-
-    if is_node_command(exe) {
-        // Write the embedded preload script to a temp file.
-        let script_path =
-            std::env::temp_dir().join(format!("phantom-preload-{}.js", std::process::id()));
-        std::fs::write(&script_path, NODE_PROXY_PRELOAD)
-            .map_err(|e| anyhow::anyhow!("failed to write proxy preload script: {e}"))?;
-        temp_script = Some(TempScript(script_path.clone()));
-
-        // Prepend --require <script> before the rest of the args.
-        let mut args = vec![
-            "--require".to_string(),
-            script_path.to_string_lossy().into_owned(),
-        ];
-        args.extend_from_slice(&command[1..]);
-        actual_args = args;
-    }
-
-    if is_php_command(exe)
-        && let Some(pem) = ca_cert_pem
-    {
-        // Write the MITM CA certificate to a temp PEM file.
-        let ca_path = std::env::temp_dir().join(format!("phantom-ca-{}.pem", std::process::id()));
-        std::fs::write(&ca_path, pem)
-            .map_err(|e| anyhow::anyhow!("failed to write CA cert: {e}"))?;
-        temp_script = Some(TempScript(ca_path.clone()));
-
-        // Prepend -d curl.cainfo=<path> before the rest of the args, so
-        // the curl extension trusts phantom's MITM certificate without
-        // any changes to the application's own curl_setopt() calls.
-        let mut args = vec![
-            "-d".to_string(),
-            format!("curl.cainfo={}", ca_path.display()),
-        ];
-        args.extend_from_slice(&actual_args);
-        actual_args = args;
-    }
-
-    let mut cmd = std::process::Command::new(exe);
-    cmd.args(&actual_args)
-        .env("HTTP_PROXY", &proxy_url)
-        .env("http_proxy", &proxy_url);
-
-    // Node.js handles HTTPS itself via the injected proxy-preload.js (a
-    // custom ProxyTunnelAgent / undici ProxyAgent). Setting HTTPS_PROXY here
-    // would make libraries like axios configure their own competing
-    // httpsAgent from the env var, conflicting with that injected agent and
-    // breaking HTTPS capture. So HTTPS_PROXY/NO_PROXY are only set for
-    // non-Node commands (e.g. curl, PHP's curl extension), which rely on
-    // libcurl's native env-var proxy detection instead.
-    if !is_node_command(exe) {
-        cmd.env("HTTPS_PROXY", &proxy_url)
-            .env("https_proxy", &proxy_url)
-            // Clear any inherited no-proxy exclusions (e.g. for `localhost`)
-            // so libcurl doesn't bypass phantom's proxy for local targets.
-            // Mirrors the Java branch's explicit `-Dhttp.nonProxyHosts=` below.
-            .env("NO_PROXY", "")
-            .env("no_proxy", "");
-    }
-
-    // For Java processes, inject proxy settings and the Java Agent via JAVA_TOOL_OPTIONS.
-    if is_java_command(exe) {
-        // Write the embedded Java Agent to a temp file.
-        let agent_path =
-            std::env::temp_dir().join(format!("phantom-agent-{}.jar", std::process::id()));
-        std::fs::write(&agent_path, JAVA_AGENT_JAR)
-            .map_err(|e| anyhow::anyhow!("failed to write java agent jar: {e}"))?;
-        temp_script = Some(TempScript(agent_path.clone()));
-
-        let jvm_opts = format!(
-            " -Dhttp.proxyHost=127.0.0.1 -Dhttp.proxyPort={proxy_port} \
-              -Dhttps.proxyHost=127.0.0.1 -Dhttps.proxyPort={proxy_port} \
-              -Dhttp.nonProxyHosts= -Dhttps.nonProxyHosts= \
-              -javaagent:{}",
-            agent_path.display()
-        );
-
-        let existing = std::env::var("JAVA_TOOL_OPTIONS").unwrap_or_default();
-        cmd.env("JAVA_TOOL_OPTIONS", format!("{existing}{jvm_opts}"));
-    }
-
-    let child = cmd
-        .spawn()
-        .map_err(|e| anyhow::anyhow!("failed to spawn {:?}: {e}", exe))?;
-
-    Ok((child, temp_script))
-}
-
-async fn run_proxy(cli: Cli, store: Arc<FjallTraceStore>) -> anyhow::Result<()> {
-    let fault_config = build_fault_config(&cli.fault)?;
-    let mut backend = ProxyCaptureBackend::new(cli.port, cli.insecure).with_faults(fault_config);
-    let backend_name = backend.name().to_string();
-    let trace_rx = backend.start().map_err(|e| anyhow::anyhow!("{e}"))?;
-
-    // Optionally spawn a child command routed through the proxy.
-    let child_and_script: Option<(std::process::Child, Option<TempScript>)> =
-        if !cli.command.is_empty() {
-            // Wait for the proxy to be ready before spawning the child.
-            wait_for_proxy(cli.port).await?;
-            let ca_cert_pem = backend.ca_cert_pem();
-            let (child, ts) = spawn_proxy_child(&cli.command, cli.port, ca_cert_pem.as_deref())?;
-            eprintln!(
-                "phantom: spawned PID {} → {}",
-                child.id(),
-                cli.command.join(" ")
-            );
-            Some((child, ts))
-        } else {
-            None
-        };
-
-    match cli.output {
-        OutputMode::Tui => {
-            if cli.command.is_empty() {
-                eprintln!("phantom: proxy listening on 127.0.0.1:{}", cli.port);
-                eprintln!("  Set your HTTP proxy to http://127.0.0.1:{}", cli.port);
-                eprintln!(
-                    "  Example: curl -x http://127.0.0.1:{} http://httpbin.org/get",
-                    cli.port
-                );
-            }
-            eprintln!(
-                "phantom: traces stored in {}",
-                store_path_display(&cli.data_dir)
-            );
-            phantom_tui::run_tui(store, trace_rx, &backend_name).await?;
-        }
-        OutputMode::Jsonl => {
-            eprintln!(
-                "phantom: proxy listening on 127.0.0.1:{} [jsonl mode]",
-                cli.port
-            );
-            // Split into child and script guard separately so the TempScript
-            // is NOT dropped until after run_jsonl_output completes (the file
-            // must exist while node is loading it via --require).
-            let (child, _script_guard) = match child_and_script {
-                Some((c, ts)) => (Some(c), ts),
-                None => (None, None),
+    match cli.command {
+        Commands::Run(args) => {
+            let store = Arc::new(FjallTraceStore::open(&data_dir)?);
+            let child_status = match args.backend {
+                Backend::Proxy => commands::run::run_proxy(&globals, args, store).await?,
+                #[cfg(target_os = "linux")]
+                Backend::Ldpreload => commands::run::run_ldpreload(&globals, args, store).await?,
             };
-            run_jsonl_output(store, trace_rx, child).await?;
-            // _script_guard dropped here — temp file deleted after child exits.
+            Ok(child_status
+                .map(exit_code_from_status)
+                .unwrap_or(ExitCode::SUCCESS))
         }
-    }
-
-    backend.stop().map_err(|e| anyhow::anyhow!("{e}"))?;
-    Ok(())
-}
-
-/// Poll until the proxy port is accepting connections (or timeout after 5 s).
-async fn wait_for_proxy(port: u16) -> anyhow::Result<()> {
-    let deadline = tokio::time::Instant::now() + std::time::Duration::from_secs(5);
-    loop {
-        if tokio::net::TcpStream::connect(format!("127.0.0.1:{port}"))
-            .await
-            .is_ok()
-        {
-            return Ok(());
+        Commands::List(args) => {
+            let store = open_store_for_query(&data_dir)?;
+            commands::query::list(&store, args)?;
+            Ok(ExitCode::SUCCESS)
         }
-        if tokio::time::Instant::now() >= deadline {
-            anyhow::bail!("proxy did not become ready on port {port} within 5 s");
+        Commands::Search(args) => {
+            let store = open_store_for_query(&data_dir)?;
+            commands::query::search(&store, args)?;
+            Ok(ExitCode::SUCCESS)
         }
-        tokio::time::sleep(std::time::Duration::from_millis(50)).await;
-    }
-}
-
-// ─────────────────────────────────────────────────────────────────────────────
-// LD_PRELOAD backend (Linux only)
-// ─────────────────────────────────────────────────────────────────────────────
-
-#[cfg(target_os = "linux")]
-async fn run_ldpreload(cli: Cli, store: Arc<FjallTraceStore>) -> anyhow::Result<()> {
-    use phantom_capture::LdPreloadCaptureBackend;
-
-    let agent_lib = cli.agent_lib.clone().ok_or_else(|| {
-        anyhow::anyhow!(
-            "--agent-lib <PATH> is required for --backend ldpreload\n\
-            Example: --agent-lib ./target/debug/libphantom_agent.so"
-        )
-    })?;
-
-    if cli.command.is_empty() {
-        anyhow::bail!(
-            "A command to trace is required for --backend ldpreload.\n\
-            Usage: phantom --backend ldpreload --agent-lib ./libphantom_agent.so -- curl http://example.com"
-        );
-    }
-
-    // Generate a unique socket path for this run.
-    let socket_path = std::env::temp_dir().join(format!(
-        "phantom-{}.sock",
-        std::time::SystemTime::now()
-            .duration_since(std::time::UNIX_EPOCH)
-            .map(|d| d.as_millis())
-            .unwrap_or(0)
-    ));
-
-    let mut backend = LdPreloadCaptureBackend::new(socket_path.clone());
-    let backend_name = backend.name().to_string();
-    let trace_rx = backend.start().map_err(|e| anyhow::anyhow!("{e}"))?;
-
-    eprintln!("phantom: ldpreload backend active");
-    eprintln!("  agent lib : {}", agent_lib.display());
-    eprintln!("  socket    : {}", socket_path.display());
-    eprintln!("  command   : {}", cli.command.join(" "));
-    eprintln!(
-        "phantom: traces stored in {}",
-        store_path_display(&cli.data_dir)
-    );
-
-    // Spawn the target process with LD_PRELOAD and PHANTOM_SOCKET set.
-    let child = std::process::Command::new(&cli.command[0])
-        .args(&cli.command[1..])
-        .env("LD_PRELOAD", &agent_lib)
-        .env("PHANTOM_SOCKET", &socket_path)
-        .spawn()
-        .map_err(|e| anyhow::anyhow!("failed to spawn {:?}: {e}", cli.command[0]))?;
-
-    eprintln!("phantom: spawned PID {}", child.id());
-
-    match cli.output {
-        OutputMode::Tui => {
-            // In TUI mode the user quits manually; child runs in background.
-            phantom_tui::run_tui(store, trace_rx, &backend_name).await?;
+        Commands::Get(args) => {
+            let store = open_store_for_query(&data_dir)?;
+            let found = commands::query::get(&store, args)?;
+            Ok(if found {
+                ExitCode::SUCCESS
+            } else {
+                ExitCode::FAILURE
+            })
+        }
+        Commands::Stats => {
+            let store = open_store_for_query(&data_dir)?;
+            commands::query::stats(&store, &data_dir)?;
+            Ok(ExitCode::SUCCESS)
+        }
+        Commands::Clear(args) => {
+            let store = open_store_for_query(&data_dir)?;
+            let cleared = commands::query::clear(&store, args.yes, globals.quiet)?;
+            Ok(if cleared {
+                ExitCode::SUCCESS
+            } else {
+                ExitCode::FAILURE
+            })
         }
-        OutputMode::Jsonl => {
-            // In JSONL mode we exit automatically when the child finishes.
-            run_jsonl_output(store, trace_rx, Some(child)).await?;
+        Commands::Mcp => {
+            let store = Arc::new(open_store_for_query(&data_dir)?);
+            mcp::run_mcp(store, data_dir).await?;
+            Ok(ExitCode::SUCCESS)
         }
     }
-
-    backend.stop().map_err(|e| anyhow::anyhow!("{e}"))?;
-    Ok(())
-}
-
-fn store_path_display(override_dir: &Option<PathBuf>) -> String {
-    override_dir
-        .clone()
-        .unwrap_or_else(default_data_dir)
-        .display()
-        .to_string()
 }
diff --git a/src/mcp/mod.rs b/src/mcp/mod.rs
new file mode 100644
index 0000000..905f1f9
--- /dev/null
+++ b/src/mcp/mod.rs
@@ -0,0 +1,4 @@
+pub mod server;
+pub mod session;
+
+pub use server::run_mcp;
diff --git a/src/mcp/server.rs b/src/mcp/server.rs
new file mode 100644
index 0000000..7396710
--- /dev/null
+++ b/src/mcp/server.rs
@@ -0,0 +1,365 @@
+use std::path::PathBuf;
+use std::sync::Arc;
+
+use rmcp::handler::server::router::tool::ToolRouter;
+use rmcp::handler::server::wrapper::Parameters;
+use rmcp::model::{CallToolResult, ContentBlock, ServerCapabilities, ServerInfo};
+use rmcp::{
+    ErrorData as McpError, ServerHandler, ServiceExt, schemars, tool, tool_handler, tool_router,
+    transport::stdio,
+};
+use serde::Deserialize;
+
+use phantom_core::query::TraceQuery;
+use phantom_core::storage::TraceStore;
+use phantom_core::trace::{SpanId, TraceId};
+use phantom_core::view::{RenderOptions, TraceView};
+use phantom_storage::FjallTraceStore;
+
+use super::session::{CaptureManager, ChildState, SessionStatus};
+
+const INSTRUCTIONS: &str = "phantom captures HTTP/HTTPS traffic from processes with zero \
+instrumentation and stores every request/response pair as a queryable trace.\n\
+Typical flow: call start_capture with the command to trace (e.g. [\"node\", \"app.js\"]); \
+poll capture_status until its child has exited (or keep the session running for servers); \
+then call list_traces with filters (method, status like \"5xx\", url_contains, since_ms) \
+to inspect what the process did on the network. Use get_trace with a span_id for full \
+request/response detail. Bodies are truncated by default to save context — raise max_body \
+when you need more. Traces persist across sessions until clear_traces.";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Tool parameter types
+// ─────────────────────────────────────────────────────────────────────────────
+
+#[derive(Debug, Deserialize, schemars::JsonSchema)]
+pub struct StartCaptureParams {
+    /// Command to spawn and trace, as argv (e.g. ["node", "app.js"]).
+    /// Node/PHP/Java get transparent HTTPS injection automatically.
+    /// Empty or omitted = start a proxy-only session (configure clients
+    /// with HTTP_PROXY=http://127.0.0.1:<port> yourself).
+    #[serde(default)]
+    pub command: Vec<String>,
+    /// Proxy port; omit for an automatically chosen free port.
+    pub port: Option<u16>,
+    /// Disable TLS verification toward backend servers (self-signed certs).
+    #[serde(default)]
+    pub insecure: bool,
+    /// Fault injection specs, e.g. "delay:100ms", "error:503:0.5:/api".
+    #[serde(default)]
+    pub fault: Vec<String>,
+}
+
+#[derive(Debug, Deserialize, schemars::JsonSchema)]
+pub struct StopCaptureParams {
+    /// Session ID returned by start_capture.
+    pub session_id: String,
+}
+
+#[derive(Debug, Default, Deserialize, schemars::JsonSchema)]
+pub struct CaptureStatusParams {
+    /// Session ID to inspect; omit for all sessions.
+    pub session_id: Option<String>,
+}
+
+#[derive(Debug, Default, Deserialize, schemars::JsonSchema)]
+pub struct ListTracesParams {
+    /// Only these HTTP methods (e.g. ["GET", "POST"]); omit for all.
+    #[serde(default)]
+    pub method: Vec<String>,
+    /// Status filter: exact ("404"), class ("4xx"), or range ("400-499").
+    pub status: Option<String>,
+    /// Only URLs containing this substring (case-insensitive).
+    pub url_contains: Option<String>,
+    /// Only traces at or after this Unix-epoch-milliseconds timestamp.
+    pub since_ms: Option<u64>,
+    /// Only traces at or before this Unix-epoch-milliseconds timestamp.
+    pub until_ms: Option<u64>,
+    /// Only spans of this 32-char hex trace ID.
+    pub trace_id: Option<String>,
+    /// Maximum traces to return (default 20).
+    pub limit: Option<u32>,
+    /// Matching traces to skip, for pagination (default 0).
+    pub offset: Option<u32>,
+    /// Truncate bodies to this many bytes (default 256; 0 = omit nothing).
+    /// Truncated bodies carry *_body_truncated: true and *_body_bytes.
+    pub max_body: Option<u32>,
+    /// Omit bodies entirely (sizes still reported).
+    #[serde(default)]
+    pub headers_only: bool,
+    /// Replace authorization/cookie-style header values with "[redacted]"
+    /// (default true).
+    pub redact_sensitive_headers: Option<bool>,
+}
+
+#[derive(Debug, Deserialize, schemars::JsonSchema)]
+pub struct GetTraceParams {
+    /// 16-char hex span ID (from list_traces).
+    pub span_id: String,
+    /// Truncate bodies to this many bytes (default 4096; 0 = unlimited).
+    pub max_body: Option<u32>,
+    /// Omit bodies entirely (sizes still reported).
+    #[serde(default)]
+    pub headers_only: bool,
+    /// Replace authorization/cookie-style header values with "[redacted]"
+    /// (default true).
+    pub redact_sensitive_headers: Option<bool>,
+}
+
+#[derive(Debug, Deserialize, schemars::JsonSchema)]
+pub struct ClearTracesParams {
+    /// Must be true; guards against accidental deletion.
+    pub confirm: bool,
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Server
+// ─────────────────────────────────────────────────────────────────────────────
+
+#[derive(Clone)]
+pub struct PhantomMcp {
+    store: Arc<FjallTraceStore>,
+    sessions: Arc<CaptureManager>,
+    data_dir: PathBuf,
+    tool_router: ToolRouter<Self>,
+}
+
+fn json_result(value: serde_json::Value) -> Result<CallToolResult, McpError> {
+    Ok(CallToolResult::success(vec![ContentBlock::json(value)?]))
+}
+
+fn internal_error(e: impl std::fmt::Display) -> McpError {
+    McpError::internal_error(e.to_string(), None)
+}
+
+fn invalid_params(msg: impl Into<String>) -> McpError {
+    McpError::invalid_params(msg.into(), None)
+}
+
+fn session_status_json(s: &SessionStatus) -> serde_json::Value {
+    let (state, exit_code) = match s.child_state {
+        ChildState::None => ("proxy_only", None),
+        ChildState::Running => ("running", None),
+        ChildState::Exited(code) => ("exited", code),
+    };
+    serde_json::json!({
+        "session_id": s.id,
+        "port": s.port,
+        "proxy_url": format!("http://127.0.0.1:{}", s.port),
+        "command": s.command,
+        "pid": s.child_pid,
+        "state": state,
+        "exit_code": exit_code,
+        "trace_count": s.trace_count,
+        "started_at_ms": s.started_at_ms,
+    })
+}
+
+fn render_options(
+    max_body: Option<u32>,
+    default_max_body: usize,
+    headers_only: bool,
+    redact_sensitive: Option<bool>,
+) -> RenderOptions {
+    let max_body = match max_body {
+        Some(0) => None,
+        Some(n) => Some(n as usize),
+        None => Some(default_max_body),
+    };
+    RenderOptions {
+        max_body,
+        headers_only,
+        redact_headers: if redact_sensitive.unwrap_or(true) {
+            RenderOptions::sensitive_headers()
+        } else {
+            Vec::new()
+        },
+    }
+}
+
+#[tool_router(router = tool_router)]
+impl PhantomMcp {
+    pub fn new(
+        store: Arc<FjallTraceStore>,
+        sessions: Arc<CaptureManager>,
+        data_dir: PathBuf,
+    ) -> Self {
+        Self {
+            store,
+            sessions,
+            data_dir,
+            tool_router: Self::tool_router(),
+        }
+    }
+
+    /// Runs a store query on a blocking thread (fjall is synchronous).
+    async fn query_store<T, F>(&self, f: F) -> Result<T, McpError>
+    where
+        T: Send + 'static,
+        F: FnOnce(&FjallTraceStore) -> Result<T, phantom_core::error::StorageError>
+            + Send
+            + 'static,
+    {
+        let store = self.store.clone();
+        tokio::task::spawn_blocking(move || f(&store))
+            .await
+            .map_err(internal_error)?
+            .map_err(internal_error)
+    }
+
+    #[tool(
+        description = "Start capturing HTTP(S) traffic. Spawns the given command routed through a MITM proxy (Node/PHP/Java get transparent HTTPS injection), or starts a proxy-only session when no command is given. Returns the session_id and proxy port. The session keeps capturing after the child exits, until stop_capture."
+    )]
+    async fn start_capture(
+        &self,
+        Parameters(p): Parameters<StartCaptureParams>,
+    ) -> Result<CallToolResult, McpError> {
+        let status = self
+            .sessions
+            .start(self.store.clone(), p.command, p.port, p.insecure, &p.fault)
+            .await
+            .map_err(internal_error)?;
+        json_result(session_status_json(&status))
+    }
+
+    #[tool(
+        description = "Stop a capture session: kills a still-running traced child and shuts the proxy down. Returns the final session status including the child's exit_code."
+    )]
+    async fn stop_capture(
+        &self,
+        Parameters(p): Parameters<StopCaptureParams>,
+    ) -> Result<CallToolResult, McpError> {
+        match self.sessions.stop(&p.session_id) {
+            Some(status) => json_result(session_status_json(&status)),
+            None => Err(invalid_params(format!(
+                "unknown session ID {:?}",
+                p.session_id
+            ))),
+        }
+    }
+
+    #[tool(
+        description = "Status of capture sessions: child state (running/exited + exit_code), trace_count so far, port. Pass session_id for one session, omit for all. Poll this after start_capture to detect when the traced command finished."
+    )]
+    async fn capture_status(
+        &self,
+        Parameters(p): Parameters<CaptureStatusParams>,
+    ) -> Result<CallToolResult, McpError> {
+        let statuses = self.sessions.status(p.session_id.as_deref());
+        if p.session_id.is_some() && statuses.is_empty() {
+            return Err(invalid_params("unknown session ID"));
+        }
+        json_result(serde_json::json!({
+            "sessions": statuses.iter().map(session_status_json).collect::<Vec<_>>(),
+        }))
+    }
+
+    #[tool(
+        description = "List captured traces, newest first, with filters. Bodies are truncated to max_body bytes (default 256) to protect context — use get_trace for full detail. Returns request/response summary per trace including span_id."
+    )]
+    async fn list_traces(
+        &self,
+        Parameters(p): Parameters<ListTracesParams>,
+    ) -> Result<CallToolResult, McpError> {
+        let methods = p
+            .method
+            .iter()
+            .map(|m| m.parse())
+            .collect::<Result<Vec<_>, _>>()
+            .map_err(|e: phantom_core::trace::ParseMethodError| invalid_params(e.to_string()))?;
+        let status = p.status.as_deref().map(|s| s.parse()).transpose().map_err(
+            |e: phantom_core::query::ParseStatusRangeError| invalid_params(e.to_string()),
+        )?;
+        let trace_id = p
+            .trace_id
+            .as_deref()
+            .map(|s| {
+                TraceId::from_hex(s)
+                    .ok_or_else(|| invalid_params("invalid trace_id: expected 32 hex chars"))
+            })
+            .transpose()?;
+        let to_time = |ms: u64| std::time::UNIX_EPOCH + std::time::Duration::from_millis(ms);
+
+        let query = TraceQuery {
+            methods,
+            status,
+            url_contains: p.url_contains,
+            since: p.since_ms.map(to_time),
+            until: p.until_ms.map(to_time),
+            trace_id,
+            limit: p.limit.unwrap_or(20) as usize,
+            offset: p.offset.unwrap_or(0) as usize,
+        };
+        let traces = self.query_store(move |s| s.query(&query)).await?;
+
+        let opts = render_options(p.max_body, 256, p.headers_only, p.redact_sensitive_headers);
+        let views: Vec<TraceView> = traces.iter().map(|t| TraceView::render(t, &opts)).collect();
+        json_result(serde_json::json!({ "traces": views }))
+    }
+
+    #[tool(
+        description = "Fetch one trace by its 16-char hex span_id with full request/response detail. Bodies are truncated to max_body bytes (default 4096); pass max_body: 0 for the complete body."
+    )]
+    async fn get_trace(
+        &self,
+        Parameters(p): Parameters<GetTraceParams>,
+    ) -> Result<CallToolResult, McpError> {
+        let span_id = SpanId::from_hex(&p.span_id)
+            .ok_or_else(|| invalid_params("invalid span_id: expected 16 hex chars"))?;
+        let trace = self
+            .query_store(move |s| s.get_by_span_id(&span_id))
+            .await?
+            .ok_or_else(|| invalid_params(format!("no trace found for span ID {}", p.span_id)))?;
+
+        let opts = render_options(p.max_body, 4096, p.headers_only, p.redact_sensitive_headers);
+        json_result(serde_json::to_value(TraceView::render(&trace, &opts)).map_err(internal_error)?)
+    }
+
+    #[tool(
+        description = "Trace store statistics: total stored traces (approximate), data directory, number of active capture sessions."
+    )]
+    async fn get_stats(&self) -> Result<CallToolResult, McpError> {
+        let total = self.query_store(|s| s.count()).await?;
+        json_result(serde_json::json!({
+            "total_traces": total,
+            "data_dir": self.data_dir.display().to_string(),
+            "active_sessions": self.sessions.active_count(),
+        }))
+    }
+
+    #[tool(
+        description = "Delete all stored traces. Requires confirm: true. Traces captured by still-running sessions after the clear are kept."
+    )]
+    async fn clear_traces(
+        &self,
+        Parameters(p): Parameters<ClearTracesParams>,
+    ) -> Result<CallToolResult, McpError> {
+        if !p.confirm {
+            return Err(invalid_params("pass confirm: true to delete all traces"));
+        }
+        self.query_store(|s| s.clear()).await?;
+        json_result(serde_json::json!({ "cleared": true }))
+    }
+}
+
+#[tool_handler(router = self.tool_router)]
+impl ServerHandler for PhantomMcp {
+    fn get_info(&self) -> ServerInfo {
+        ServerInfo::new(ServerCapabilities::builder().enable_tools().build())
+            .with_instructions(INSTRUCTIONS)
+    }
+}
+
+/// Serves MCP over stdio until the client disconnects, then tears down all
+/// capture sessions.
+pub async fn run_mcp(store: Arc<FjallTraceStore>, data_dir: PathBuf) -> anyhow::Result<()> {
+    let sessions = Arc::new(CaptureManager::default());
+    let server = PhantomMcp::new(store, sessions.clone(), data_dir);
+    let service = server
+        .serve(stdio())
+        .await
+        .map_err(|e| anyhow::anyhow!("MCP server failed to start: {e}"))?;
+    let quit_reason = service.waiting().await?;
+    tracing::info!("MCP server stopped: {quit_reason:?}");
+    sessions.stop_all();
+    Ok(())
+}
diff --git a/src/mcp/session.rs b/src/mcp/session.rs
new file mode 100644
index 0000000..8d6fa64
--- /dev/null
+++ b/src/mcp/session.rs
@@ -0,0 +1,233 @@
+use std::collections::HashMap;
+use std::sync::atomic::{AtomicU64, Ordering};
+use std::sync::{Arc, Mutex};
+use std::time::{SystemTime, UNIX_EPOCH};
+
+use phantom_capture::ProxyCaptureBackend;
+use phantom_core::capture::CaptureBackend;
+use phantom_core::storage::TraceStore;
+use phantom_storage::FjallTraceStore;
+
+use crate::runner::{TempScript, build_fault_config, spawn_proxy_child, wait_for_proxy};
+
+/// Lifecycle state of a capture session's traced child process.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum ChildState {
+    /// No child was spawned (proxy-only session).
+    None,
+    Running,
+    Exited(Option<i32>),
+}
+
+/// One running capture: a MITM proxy plus (optionally) a traced child process.
+pub struct CaptureSession {
+    pub id: String,
+    pub port: u16,
+    pub command: Vec<String>,
+    pub child_pid: Option<u32>,
+    pub started_at_ms: u64,
+    pub trace_count: Arc<AtomicU64>,
+    child_state: Arc<Mutex<ChildState>>,
+    child: Option<Arc<Mutex<std::process::Child>>>,
+    backend: ProxyCaptureBackend,
+    /// Keeps the injected preload/CA temp file alive for the child's lifetime.
+    _temp_script: Option<TempScript>,
+}
+
+impl CaptureSession {
+    pub fn child_state(&self) -> ChildState {
+        *self.child_state.lock().unwrap()
+    }
+}
+
+/// Owns all capture sessions of one MCP server process.
+#[derive(Default)]
+pub struct CaptureManager {
+    sessions: Mutex<HashMap<String, CaptureSession>>,
+}
+
+/// Snapshot of a session for `capture_status` responses.
+pub struct SessionStatus {
+    pub id: String,
+    pub port: u16,
+    pub command: Vec<String>,
+    pub child_pid: Option<u32>,
+    pub started_at_ms: u64,
+    pub trace_count: u64,
+    pub child_state: ChildState,
+}
+
+fn random_session_id() -> String {
+    let nanos = SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .map(|d| d.as_nanos())
+        .unwrap_or(0);
+    format!("{:08x}", (nanos as u64 ^ (nanos >> 64) as u64) as u32)
+}
+
+fn now_ms() -> u64 {
+    SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .map(|d| d.as_millis() as u64)
+        .unwrap_or(0)
+}
+
+/// Reserve an OS-assigned free TCP port (small race until the proxy binds it).
+fn free_port() -> anyhow::Result<u16> {
+    Ok(std::net::TcpListener::bind("127.0.0.1:0")?
+        .local_addr()?
+        .port())
+}
+
+impl CaptureManager {
+    /// Starts a proxy capture session, optionally spawning `command` through it.
+    /// Traces are pumped into `store`; the session runs until `stop()`.
+    pub async fn start(
+        &self,
+        store: Arc<FjallTraceStore>,
+        command: Vec<String>,
+        port: Option<u16>,
+        insecure: bool,
+        fault: &[String],
+    ) -> anyhow::Result<SessionStatus> {
+        let port = match port {
+            Some(p) => p,
+            None => free_port()?,
+        };
+        let fault_config = build_fault_config(fault)?;
+        let mut backend = ProxyCaptureBackend::new(port, insecure).with_faults(fault_config);
+        let mut trace_rx = backend.start().map_err(|e| anyhow::anyhow!("{e}"))?;
+        wait_for_proxy(port).await?;
+
+        // Pump captured traces into the store off the async executor.
+        let trace_count = Arc::new(AtomicU64::new(0));
+        let pump_count = trace_count.clone();
+        let pump_store = store.clone();
+        tokio::spawn(async move {
+            while let Some(trace) = trace_rx.recv().await {
+                let store = pump_store.clone();
+                let insert = tokio::task::spawn_blocking(move || store.insert(&trace)).await;
+                match insert {
+                    Ok(Ok(())) => {
+                        pump_count.fetch_add(1, Ordering::Relaxed);
+                    }
+                    Ok(Err(e)) => tracing::warn!("failed to store trace: {e}"),
+                    Err(e) => tracing::warn!("trace insert task failed: {e}"),
+                }
+            }
+        });
+
+        // Optionally spawn the traced child.
+        let child_state = Arc::new(Mutex::new(ChildState::None));
+        let mut child_pid = None;
+        let mut child_handle = None;
+        let mut temp_script = None;
+        if !command.is_empty() {
+            let ca_cert_pem = backend.ca_cert_pem();
+            let (child, ts) = spawn_proxy_child(&command, port, ca_cert_pem.as_deref())?;
+            child_pid = Some(child.id());
+            temp_script = ts;
+            *child_state.lock().unwrap() = ChildState::Running;
+
+            let child = Arc::new(Mutex::new(child));
+            child_handle = Some(child.clone());
+            let state = child_state.clone();
+            // Poll try_wait instead of a blocking wait() so stop() can take
+            // the child lock to kill without deadlocking against the waiter.
+            tokio::spawn(async move {
+                loop {
+                    let status = child.lock().unwrap().try_wait();
+                    match status {
+                        Ok(Some(st)) => {
+                            *state.lock().unwrap() = ChildState::Exited(st.code());
+                            break;
+                        }
+                        Ok(None) => {
+                            tokio::time::sleep(std::time::Duration::from_millis(100)).await;
+                        }
+                        Err(_) => break,
+                    }
+                }
+            });
+        }
+
+        let session = CaptureSession {
+            id: random_session_id(),
+            port,
+            command,
+            child_pid,
+            started_at_ms: now_ms(),
+            trace_count,
+            child_state,
+            child: child_handle,
+            backend,
+            _temp_script: temp_script,
+        };
+        let status = snapshot(&session);
+        self.sessions
+            .lock()
+            .unwrap()
+            .insert(session.id.clone(), session);
+        Ok(status)
+    }
+
+    /// Stops a session: kills a still-running child and shuts the proxy down.
+    /// Returns the final status, or `None` for an unknown session ID.
+    pub fn stop(&self, session_id: &str) -> Option<SessionStatus> {
+        let mut session = self.sessions.lock().unwrap().remove(session_id)?;
+        shutdown_session(&mut session);
+        Some(snapshot(&session))
+    }
+
+    /// Status of one session, or all sessions when `session_id` is `None`.
+    pub fn status(&self, session_id: Option<&str>) -> Vec<SessionStatus> {
+        let sessions = self.sessions.lock().unwrap();
+        match session_id {
+            Some(id) => sessions.get(id).map(snapshot).into_iter().collect(),
+            None => {
+                let mut all: Vec<_> = sessions.values().map(snapshot).collect();
+                all.sort_by_key(|s| s.started_at_ms);
+                all
+            }
+        }
+    }
+
+    pub fn active_count(&self) -> usize {
+        self.sessions.lock().unwrap().len()
+    }
+
+    /// Stops every session (server shutdown path).
+    pub fn stop_all(&self) {
+        let mut sessions = self.sessions.lock().unwrap();
+        for (_, mut session) in sessions.drain() {
+            shutdown_session(&mut session);
+        }
+    }
+}
+
+fn snapshot(session: &CaptureSession) -> SessionStatus {
+    SessionStatus {
+        id: session.id.clone(),
+        port: session.port,
+        command: session.command.clone(),
+        child_pid: session.child_pid,
+        started_at_ms: session.started_at_ms,
+        trace_count: session.trace_count.load(Ordering::Relaxed),
+        child_state: session.child_state(),
+    }
+}
+
+fn shutdown_session(session: &mut CaptureSession) {
+    if let Some(child) = &session.child
+        && session.child_state() == ChildState::Running
+    {
+        let mut child = child.lock().unwrap();
+        let _ = child.kill();
+        if let Ok(st) = child.wait() {
+            *session.child_state.lock().unwrap() = ChildState::Exited(st.code());
+        }
+    }
+    if let Err(e) = session.backend.stop() {
+        tracing::warn!("failed to stop capture backend: {e}");
+    }
+}
diff --git a/src/runner.rs b/src/runner.rs
new file mode 100644
index 0000000..224002a
--- /dev/null
+++ b/src/runner.rs
@@ -0,0 +1,200 @@
+use std::path::{Path, PathBuf};
+
+use phantom_capture::FaultConfig;
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Embedded injection assets
+// ─────────────────────────────────────────────────────────────────────────────
+
+/// The proxy-preload.js content, embedded at compile time.
+/// Written to a temp file when tracing Node.js processes via `phantom run -- node …`.
+const NODE_PROXY_PRELOAD: &str = include_str!("../tests/apps/node-app/proxy-preload.js");
+
+/// The Java Agent JAR, embedded at compile time.
+/// Written to a temp file when tracing Java processes via `phantom run -- java …`.
+const JAVA_AGENT_JAR: &[u8] = include_bytes!("../crates/phantom-java-agent/phantom-java-agent.jar");
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Child process spawning
+// ─────────────────────────────────────────────────────────────────────────────
+
+/// RAII guard that deletes a temporary script file on drop.
+pub struct TempScript(pub PathBuf);
+
+impl Drop for TempScript {
+    fn drop(&mut self) {
+        let _ = std::fs::remove_file(&self.0);
+    }
+}
+
+/// Returns `true` if `exe` (path or bare name) resolves to `node` or `nodejs`.
+fn is_node_command(exe: &str) -> bool {
+    let base = Path::new(exe)
+        .file_name()
+        .and_then(|n| n.to_str())
+        .unwrap_or(exe);
+    base == "node" || base == "nodejs"
+}
+
+/// Returns `true` if `exe` (path or bare name) resolves to `java` or `javaw`.
+fn is_java_command(exe: &str) -> bool {
+    let base = Path::new(exe)
+        .file_name()
+        .and_then(|n| n.to_str())
+        .unwrap_or(exe);
+    base == "java" || base == "javaw"
+}
+
+/// Returns `true` if `exe` (path or bare name) resolves to `php` or a
+/// version-suffixed PHP binary (e.g. `php7.4`, `php8.2`, `php5.3`).
+fn is_php_command(exe: &str) -> bool {
+    let base = Path::new(exe)
+        .file_name()
+        .and_then(|n| n.to_str())
+        .unwrap_or(exe);
+    base == "php"
+        || (base.starts_with("php")
+            && !base[3..].is_empty()
+            && base[3..].chars().all(|c| c.is_ascii_digit() || c == '.'))
+}
+
+/// Spawns `command` as a child process routed through the phantom proxy.
+///
+/// * `HTTP_PROXY` / `HTTPS_PROXY` (and lowercase variants) are set so plain
+///   HTTP and HTTP-client-honoured HTTPS (e.g. libcurl) are captured.
+/// * For Node.js executables the embedded proxy-preload script is written to a
+///   temp file and prepended as `--require <path>` so HTTPS is also captured
+///   without touching the application source.
+/// * For Java executables, the phantom-java-agent.jar is injected via -javaagent
+///   to force proxy settings and bypass SSL verification globally.
+/// * For PHP executables, the MITM CA certificate is written to a temp PEM
+///   file and injected via `-d curl.cainfo=<path>` so the curl extension
+///   trusts phantom's HTTPS interception without any application changes.
+///
+/// Returns `(child, Option<TempScript>)`.  The `TempScript` must be kept alive
+/// until after the child exits so the file is not deleted prematurely.
+pub fn spawn_proxy_child(
+    command: &[String],
+    proxy_port: u16,
+    ca_cert_pem: Option<&str>,
+) -> anyhow::Result<(std::process::Child, Option<TempScript>)> {
+    let exe = &command[0];
+    let proxy_url = format!("http://127.0.0.1:{proxy_port}");
+
+    let mut temp_script: Option<TempScript> = None;
+    let mut actual_args = command[1..].to_vec();
+
+    if is_node_command(exe) {
+        // Write the embedded preload script to a temp file.
+        let script_path =
+            std::env::temp_dir().join(format!("phantom-preload-{}.js", std::process::id()));
+        std::fs::write(&script_path, NODE_PROXY_PRELOAD)
+            .map_err(|e| anyhow::anyhow!("failed to write proxy preload script: {e}"))?;
+        temp_script = Some(TempScript(script_path.clone()));
+
+        // Prepend --require <script> before the rest of the args.
+        let mut args = vec![
+            "--require".to_string(),
+            script_path.to_string_lossy().into_owned(),
+        ];
+        args.extend_from_slice(&command[1..]);
+        actual_args = args;
+    }
+
+    if is_php_command(exe)
+        && let Some(pem) = ca_cert_pem
+    {
+        // Write the MITM CA certificate to a temp PEM file.
+        let ca_path = std::env::temp_dir().join(format!("phantom-ca-{}.pem", std::process::id()));
+        std::fs::write(&ca_path, pem)
+            .map_err(|e| anyhow::anyhow!("failed to write CA cert: {e}"))?;
+        temp_script = Some(TempScript(ca_path.clone()));
+
+        // Prepend -d curl.cainfo=<path> before the rest of the args, so
+        // the curl extension trusts phantom's MITM certificate without
+        // any changes to the application's own curl_setopt() calls.
+        let mut args = vec![
+            "-d".to_string(),
+            format!("curl.cainfo={}", ca_path.display()),
+        ];
+        args.extend_from_slice(&actual_args);
+        actual_args = args;
+    }
+
+    let mut cmd = std::process::Command::new(exe);
+    cmd.args(&actual_args)
+        .env("HTTP_PROXY", &proxy_url)
+        .env("http_proxy", &proxy_url);
+
+    // Node.js handles HTTPS itself via the injected proxy-preload.js (a
+    // custom ProxyTunnelAgent / undici ProxyAgent). Setting HTTPS_PROXY here
+    // would make libraries like axios configure their own competing
+    // httpsAgent from the env var, conflicting with that injected agent and
+    // breaking HTTPS capture. So HTTPS_PROXY/NO_PROXY are only set for
+    // non-Node commands (e.g. curl, PHP's curl extension), which rely on
+    // libcurl's native env-var proxy detection instead.
+    if !is_node_command(exe) {
+        cmd.env("HTTPS_PROXY", &proxy_url)
+            .env("https_proxy", &proxy_url)
+            // Clear any inherited no-proxy exclusions (e.g. for `localhost`)
+            // so libcurl doesn't bypass phantom's proxy for local targets.
+            // Mirrors the Java branch's explicit `-Dhttp.nonProxyHosts=` below.
+            .env("NO_PROXY", "")
+            .env("no_proxy", "");
+    }
+
+    // For Java processes, inject proxy settings and the Java Agent via JAVA_TOOL_OPTIONS.
+    if is_java_command(exe) {
+        // Write the embedded Java Agent to a temp file.
+        let agent_path =
+            std::env::temp_dir().join(format!("phantom-agent-{}.jar", std::process::id()));
+        std::fs::write(&agent_path, JAVA_AGENT_JAR)
+            .map_err(|e| anyhow::anyhow!("failed to write java agent jar: {e}"))?;
+        temp_script = Some(TempScript(agent_path.clone()));
+
+        let jvm_opts = format!(
+            " -Dhttp.proxyHost=127.0.0.1 -Dhttp.proxyPort={proxy_port} \
+              -Dhttps.proxyHost=127.0.0.1 -Dhttps.proxyPort={proxy_port} \
+              -Dhttp.nonProxyHosts= -Dhttps.nonProxyHosts= \
+              -javaagent:{}",
+            agent_path.display()
+        );
+
+        let existing = std::env::var("JAVA_TOOL_OPTIONS").unwrap_or_default();
+        cmd.env("JAVA_TOOL_OPTIONS", format!("{existing}{jvm_opts}"));
+    }
+
+    let child = cmd
+        .spawn()
+        .map_err(|e| anyhow::anyhow!("failed to spawn {:?}: {e}", exe))?;
+
+    Ok((child, temp_script))
+}
+
+/// Poll until the proxy port is accepting connections (or timeout after 5 s).
+pub async fn wait_for_proxy(port: u16) -> anyhow::Result<()> {
+    let deadline = tokio::time::Instant::now() + std::time::Duration::from_secs(5);
+    loop {
+        if tokio::net::TcpStream::connect(format!("127.0.0.1:{port}"))
+            .await
+            .is_ok()
+        {
+            return Ok(());
+        }
+        if tokio::time::Instant::now() >= deadline {
+            anyhow::bail!("proxy did not become ready on port {port} within 5 s");
+        }
+        tokio::time::sleep(std::time::Duration::from_millis(50)).await;
+    }
+}
+
+/// Parse repeated `--fault SPEC` flags into a `FaultConfig`.
+pub fn build_fault_config(specs: &[String]) -> anyhow::Result<FaultConfig> {
+    let mut rules = Vec::new();
+    for spec in specs {
+        let rule = phantom_capture::parse_fault_spec(spec)
+            .map_err(|e| anyhow::anyhow!("--fault {spec:?}: {e}"))?;
+        rules.push(rule);
+    }
+    Ok(FaultConfig { rules })
+}
diff --git a/tests/cli_query_integration.rs b/tests/cli_query_integration.rs
new file mode 100644
index 0000000..1e9de55
--- /dev/null
+++ b/tests/cli_query_integration.rs
@@ -0,0 +1,478 @@
+//! CLI integration tests for agent-facing behavior:
+//!   - `phantom run` propagates the traced child's exit code
+//!   - stdout stays pure JSONL (diagnostics go to stderr)
+//!   - `phantom list` / `get` / `stats` query previously captured traces
+//!   - query subcommands fail with a lock hint while another process holds
+//!     the store
+//!
+//! Requirements: `curl` on PATH for the capture-based tests (skipped otherwise).
+//! Run: `cargo test --test cli_query_integration`
+
+use std::io::{Read, Write as IoWrite};
+use std::net::{TcpListener, TcpStream};
+use std::path::Path;
+use std::process::{Command, Stdio};
+use std::time::{Duration, Instant};
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Helpers (same patterns as fault_injection.rs)
+// ─────────────────────────────────────────────────────────────────────────────
+
+fn available_port() -> u16 {
+    TcpListener::bind("127.0.0.1:0")
+        .expect("bind :0")
+        .local_addr()
+        .unwrap()
+        .port()
+}
+
+fn wait_for_port(port: u16, timeout: Duration) -> bool {
+    let start = Instant::now();
+    while start.elapsed() < timeout {
+        if TcpStream::connect(format!("127.0.0.1:{port}")).is_ok() {
+            return true;
+        }
+        std::thread::sleep(Duration::from_millis(50));
+    }
+    false
+}
+
+const HEALTH_BODY: &str = r#"{"status":"ok","padding":"0123456789"}"#;
+
+fn handle_stream(stream: &mut (impl Read + IoWrite)) {
+    let mut buf = [0u8; 8192];
+    let n = match stream.read(&mut buf) {
+        Ok(0) | Err(_) => return,
+        Ok(n) => n,
+    };
+    let req = String::from_utf8_lossy(&buf[..n]);
+    let first = req.lines().next().unwrap_or("");
+    let (status, body) = if first.contains("/api/health") {
+        ("200 OK", HEALTH_BODY)
+    } else {
+        ("404 Not Found", r#"{"error":"Not Found"}"#)
+    };
+    let resp = format!(
+        "HTTP/1.1 {status}\r\nContent-Type: application/json\r\nContent-Length: {}\r\nConnection: close\r\n\r\n{body}",
+        body.len()
+    );
+    let _ = stream.write_all(resp.as_bytes());
+    let _ = stream.flush();
+}
+
+fn start_http_backend(port: u16) -> std::thread::JoinHandle<()> {
+    std::thread::spawn(move || {
+        let listener = TcpListener::bind(format!("127.0.0.1:{port}")).unwrap();
+        for stream in listener.incoming() {
+            match stream {
+                Ok(mut s) => handle_stream(&mut s),
+                Err(_) => break,
+            }
+        }
+    })
+}
+
+fn curl_missing() -> bool {
+    Command::new("curl")
+        .arg("--version")
+        .stdout(Stdio::null())
+        .stderr(Stdio::null())
+        .status()
+        .is_err()
+}
+
+/// Run `phantom run -o jsonl <extra_run_flags>` tracing one curl GET against
+/// the mock backend, persisting traces into `data_dir`.
+fn capture_health_request(data_dir: &Path, extra_run_flags: &[&str]) -> std::process::Output {
+    let phantom_bin = env!("CARGO_BIN_EXE_phantom");
+    let backend_port = available_port();
+    let proxy_port = available_port();
+
+    let _backend = start_http_backend(backend_port);
+    assert!(
+        wait_for_port(backend_port, Duration::from_secs(3)),
+        "HTTP backend did not start"
+    );
+
+    let out = Command::new(phantom_bin)
+        .args(["run", "--output", "jsonl", "--port"])
+        .arg(proxy_port.to_string())
+        .arg("--data-dir")
+        .arg(data_dir)
+        .args(extra_run_flags)
+        .env("no_proxy", "")
+        .env("NO_PROXY", "")
+        .arg("--")
+        .args(["curl", "--silent", "--output", "/dev/null", "--proxy"])
+        .arg(format!("http://127.0.0.1:{proxy_port}"))
+        .arg(format!("http://127.0.0.1:{backend_port}/api/health"))
+        .output()
+        .expect("run phantom");
+    assert!(
+        out.status.success(),
+        "phantom run failed: {}",
+        String::from_utf8_lossy(&out.stderr)
+    );
+    out
+}
+
+/// Run `phantom run -o jsonl` tracing one curl GET against the mock backend,
+/// persisting traces into `data_dir`. Returns phantom's stdout.
+fn capture_one_health_request(data_dir: &Path) -> String {
+    let out = capture_health_request(data_dir, &[]);
+    String::from_utf8_lossy(&out.stdout).into_owned()
+}
+
+fn phantom_query(data_dir: &Path, args: &[&str]) -> std::process::Output {
+    Command::new(env!("CARGO_BIN_EXE_phantom"))
+        .args(args)
+        .arg("--data-dir")
+        .arg(data_dir)
+        .output()
+        .expect("run phantom query")
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Exit code propagation
+// ─────────────────────────────────────────────────────────────────────────────
+
+#[test]
+fn test_run_propagates_child_exit_code() {
+    let tmp_dir = tempfile::tempdir().expect("tempdir");
+    let out = Command::new(env!("CARGO_BIN_EXE_phantom"))
+        .args(["run", "--output", "jsonl", "--port"])
+        .arg(available_port().to_string())
+        .arg("--data-dir")
+        .arg(tmp_dir.path())
+        .args(["--", "sh", "-c", "exit 3"])
+        .output()
+        .expect("run phantom");
+    assert_eq!(
+        out.status.code(),
+        Some(3),
+        "child exit code not propagated; stderr: {}",
+        String::from_utf8_lossy(&out.stderr)
+    );
+
+    // The end-of-run summary is machine-readable JSON on stderr.
+    let stderr = String::from_utf8_lossy(&out.stderr);
+    let summary = stderr
+        .lines()
+        .filter_map(|l| serde_json::from_str::<serde_json::Value>(l).ok())
+        .find(|v| v["event"] == "exit")
+        .expect("exit summary on stderr");
+    assert_eq!(summary["child_exit_code"], 3);
+}
+
+#[test]
+fn test_run_success_exit_code_zero() {
+    let tmp_dir = tempfile::tempdir().expect("tempdir");
+    let out = Command::new(env!("CARGO_BIN_EXE_phantom"))
+        .args(["run", "--output", "jsonl", "--port"])
+        .arg(available_port().to_string())
+        .arg("--data-dir")
+        .arg(tmp_dir.path())
+        .args(["--", "sh", "-c", "exit 0"])
+        .output()
+        .expect("run phantom");
+    assert_eq!(out.status.code(), Some(0));
+}
+
+#[cfg(unix)]
+#[test]
+fn test_run_signal_death_maps_to_128_plus_signal() {
+    let tmp_dir = tempfile::tempdir().expect("tempdir");
+    let out = Command::new(env!("CARGO_BIN_EXE_phantom"))
+        .args(["run", "--output", "jsonl", "--port"])
+        .arg(available_port().to_string())
+        .arg("--data-dir")
+        .arg(tmp_dir.path())
+        .args(["--", "sh", "-c", "kill -9 $$"])
+        .output()
+        .expect("run phantom");
+    assert_eq!(
+        out.status.code(),
+        Some(128 + 9),
+        "SIGKILLed child should map to exit 137; stderr: {}",
+        String::from_utf8_lossy(&out.stderr)
+    );
+}
+
+#[test]
+fn test_run_quiet_suppresses_status_and_summary() {
+    let tmp_dir = tempfile::tempdir().expect("tempdir");
+    let out = Command::new(env!("CARGO_BIN_EXE_phantom"))
+        .args(["--quiet", "run", "--output", "jsonl", "--port"])
+        .arg(available_port().to_string())
+        .arg("--data-dir")
+        .arg(tmp_dir.path())
+        .args(["--", "sh", "-c", "exit 5"])
+        .output()
+        .expect("run phantom");
+    // Exit code still propagates in quiet mode.
+    assert_eq!(out.status.code(), Some(5));
+    let stderr = String::from_utf8_lossy(&out.stderr);
+    assert!(
+        !stderr.contains("phantom:"),
+        "status lines must be suppressed: {stderr}"
+    );
+    assert!(
+        !stderr.contains("\"event\""),
+        "exit summary must be suppressed: {stderr}"
+    );
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// JSONL purity + query subcommands
+// ─────────────────────────────────────────────────────────────────────────────
+
+#[test]
+fn test_capture_then_query_via_cli() {
+    if curl_missing() {
+        eprintln!("SKIP: `curl` not found");
+        return;
+    }
+
+    let tmp_dir = tempfile::tempdir().expect("tempdir");
+    let stdout = capture_one_health_request(tmp_dir.path());
+
+    // stdout must be pure JSONL: every non-empty line parses as JSON.
+    let mut traces = Vec::new();
+    for line in stdout.lines().filter(|l| !l.trim().is_empty()) {
+        let v: serde_json::Value = serde_json::from_str(line)
+            .unwrap_or_else(|e| panic!("non-JSON stdout line {line:?}: {e}"));
+        traces.push(v);
+    }
+    assert_eq!(traces.len(), 1, "expected exactly one captured trace");
+    assert_eq!(traces[0]["status_code"], 200);
+    let span_id = traces[0]["span_id"].as_str().unwrap().to_string();
+
+    // list: status filter matches
+    let out = phantom_query(tmp_dir.path(), &["list", "--status", "2xx"]);
+    assert!(out.status.success());
+    let listed: Vec<serde_json::Value> = String::from_utf8_lossy(&out.stdout)
+        .lines()
+        .map(|l| serde_json::from_str(l).unwrap())
+        .collect();
+    assert_eq!(listed.len(), 1);
+    assert_eq!(listed[0]["span_id"], span_id.as_str());
+    assert!(
+        listed[0]["url"].as_str().unwrap().contains("/api/health"),
+        "unexpected url: {}",
+        listed[0]["url"]
+    );
+
+    // list: non-matching filter returns nothing
+    let out = phantom_query(tmp_dir.path(), &["list", "--status", "5xx"]);
+    assert!(out.status.success());
+    assert!(out.stdout.is_empty());
+
+    // list: --max-body truncation is flagged and reports the original size
+    let out = phantom_query(
+        tmp_dir.path(),
+        &["list", "--max-body", "4", "--format", "jsonl"],
+    );
+    assert!(out.status.success());
+    let v: serde_json::Value =
+        serde_json::from_str(String::from_utf8_lossy(&out.stdout).lines().next().unwrap()).unwrap();
+    assert_eq!(v["response_body"].as_str().unwrap().len(), 4);
+    assert_eq!(v["response_body_truncated"], true);
+    assert_eq!(
+        v["response_body_bytes"].as_u64().unwrap(),
+        HEALTH_BODY.len() as u64
+    );
+
+    // list: --headers-only omits bodies but keeps sizes
+    let out = phantom_query(tmp_dir.path(), &["list", "--headers-only"]);
+    let v: serde_json::Value =
+        serde_json::from_str(String::from_utf8_lossy(&out.stdout).lines().next().unwrap()).unwrap();
+    assert!(v.get("response_body").is_none());
+    assert!(v.get("response_body_bytes").is_some());
+
+    // get: found → exit 0, pretty JSON object
+    let out = phantom_query(tmp_dir.path(), &["get", &span_id]);
+    assert!(out.status.success());
+    let v: serde_json::Value = serde_json::from_slice(&out.stdout).unwrap();
+    assert_eq!(v["span_id"], span_id.as_str());
+
+    // get: unknown span → exit 1
+    let out = phantom_query(tmp_dir.path(), &["get", "ffffffffffffffff"]);
+    assert_eq!(out.status.code(), Some(1));
+
+    // search: positional pattern filters by URL substring
+    let out = phantom_query(tmp_dir.path(), &["search", "/api/health"]);
+    assert!(out.status.success());
+    assert_eq!(String::from_utf8_lossy(&out.stdout).lines().count(), 1);
+    let out = phantom_query(tmp_dir.path(), &["search", "/nowhere"]);
+    assert!(out.stdout.is_empty());
+
+    // stats: reports the trace count as JSON
+    let out = phantom_query(tmp_dir.path(), &["stats"]);
+    assert!(out.status.success());
+    let v: serde_json::Value = serde_json::from_slice(&out.stdout).unwrap();
+    assert!(v["total_traces"].is_u64());
+
+    // clear: refuses without --yes, works with it
+    let out = phantom_query(tmp_dir.path(), &["clear"]);
+    assert_eq!(out.status.code(), Some(1));
+    let out = phantom_query(tmp_dir.path(), &["clear", "--yes"]);
+    assert!(out.status.success());
+    let out = phantom_query(tmp_dir.path(), &["list"]);
+    assert!(out.stdout.is_empty());
+}
+
+#[test]
+fn test_run_stream_respects_max_body_and_reports_summary() {
+    if curl_missing() {
+        eprintln!("SKIP: `curl` not found");
+        return;
+    }
+
+    let tmp_dir = tempfile::tempdir().expect("tempdir");
+    let out = capture_health_request(tmp_dir.path(), &["--max-body", "4"]);
+
+    // Live JSONL stream honours --max-body and flags the truncation.
+    let stdout = String::from_utf8_lossy(&out.stdout);
+    let v: serde_json::Value = serde_json::from_str(stdout.lines().next().expect("one trace"))
+        .expect("trace line is JSON");
+    assert_eq!(v["response_body"].as_str().unwrap().len(), 4);
+    assert_eq!(v["response_body_truncated"], true);
+    assert_eq!(
+        v["response_body_bytes"].as_u64().unwrap(),
+        HEALTH_BODY.len() as u64
+    );
+
+    // The stderr exit summary counts the captured traces.
+    let stderr = String::from_utf8_lossy(&out.stderr);
+    let summary = stderr
+        .lines()
+        .filter_map(|l| serde_json::from_str::<serde_json::Value>(l).ok())
+        .find(|v| v["event"] == "exit")
+        .expect("exit summary on stderr");
+    assert_eq!(summary["traces_captured"], 1);
+    assert_eq!(summary["child_exit_code"], 0);
+}
+
+#[test]
+fn test_run_stream_headers_only() {
+    if curl_missing() {
+        eprintln!("SKIP: `curl` not found");
+        return;
+    }
+
+    let tmp_dir = tempfile::tempdir().expect("tempdir");
+    let out = capture_health_request(tmp_dir.path(), &["--headers-only"]);
+    let stdout = String::from_utf8_lossy(&out.stdout);
+    let v: serde_json::Value =
+        serde_json::from_str(stdout.lines().next().expect("one trace")).unwrap();
+    assert!(v.get("response_body").is_none());
+    assert_eq!(
+        v["response_body_bytes"].as_u64().unwrap(),
+        HEALTH_BODY.len() as u64
+    );
+    // The full body is still persisted — only the stream output is reduced.
+    let listed = phantom_query(tmp_dir.path(), &["list"]);
+    let stored: serde_json::Value = serde_json::from_str(
+        String::from_utf8_lossy(&listed.stdout)
+            .lines()
+            .next()
+            .unwrap(),
+    )
+    .unwrap();
+    assert_eq!(stored["response_body"].as_str().unwrap(), HEALTH_BODY);
+}
+
+#[test]
+fn test_list_filters_method_time_and_trace_id() {
+    if curl_missing() {
+        eprintln!("SKIP: `curl` not found");
+        return;
+    }
+
+    let tmp_dir = tempfile::tempdir().expect("tempdir");
+    let stdout = capture_one_health_request(tmp_dir.path());
+    let captured: serde_json::Value =
+        serde_json::from_str(stdout.lines().next().expect("one trace")).unwrap();
+    let trace_id = captured["trace_id"].as_str().unwrap();
+
+    // --method: GET matches, POST does not.
+    let out = phantom_query(tmp_dir.path(), &["list", "--method", "GET"]);
+    assert_eq!(String::from_utf8_lossy(&out.stdout).lines().count(), 1);
+    let out = phantom_query(tmp_dir.path(), &["list", "--method", "POST"]);
+    assert!(out.stdout.is_empty());
+
+    // --since/--until with relative times: the trace is inside (1h ago, now]
+    // and outside windows entirely in the past.
+    let out = phantom_query(tmp_dir.path(), &["list", "--since", "1h"]);
+    assert_eq!(String::from_utf8_lossy(&out.stdout).lines().count(), 1);
+    let out = phantom_query(tmp_dir.path(), &["list", "--until", "1h"]);
+    assert!(out.stdout.is_empty());
+
+    // --trace-id round trip.
+    let out = phantom_query(tmp_dir.path(), &["list", "--trace-id", trace_id]);
+    assert_eq!(String::from_utf8_lossy(&out.stdout).lines().count(), 1);
+    let other_id = "0".repeat(32);
+    let out = phantom_query(tmp_dir.path(), &["list", "--trace-id", &other_id]);
+    assert!(out.stdout.is_empty());
+
+    // --format json produces a pretty-printed array.
+    let out = phantom_query(tmp_dir.path(), &["list", "--format", "json"]);
+    let arr: serde_json::Value = serde_json::from_slice(&out.stdout).expect("json array");
+    assert_eq!(arr.as_array().unwrap().len(), 1);
+
+    // --redact-header masks the named header in output.
+    let out = phantom_query(tmp_dir.path(), &["list", "--redact-header", "User-Agent"]);
+    let v: serde_json::Value =
+        serde_json::from_str(String::from_utf8_lossy(&out.stdout).lines().next().unwrap()).unwrap();
+    assert_eq!(v["request_headers"]["user-agent"], "[redacted]");
+}
+
+#[test]
+fn test_query_invalid_arguments_fail_fast() {
+    let tmp_dir = tempfile::tempdir().expect("tempdir");
+
+    // clap rejects an unparsable status range before touching the store.
+    let out = phantom_query(tmp_dir.path(), &["list", "--status", "bogus"]);
+    assert_eq!(out.status.code(), Some(2));
+    assert!(
+        String::from_utf8_lossy(&out.stderr).contains("invalid status range"),
+        "stderr should explain the status parse failure"
+    );
+
+    // Non-hex span/trace IDs are rejected with a clear message and exit 1.
+    let out = phantom_query(tmp_dir.path(), &["get", "not-a-span-id"]);
+    assert_eq!(out.status.code(), Some(1));
+    assert!(String::from_utf8_lossy(&out.stderr).contains("invalid span ID"));
+
+    let out = phantom_query(tmp_dir.path(), &["list", "--trace-id", "xyz"]);
+    assert_eq!(out.status.code(), Some(1));
+    assert!(String::from_utf8_lossy(&out.stderr).contains("invalid trace ID"));
+
+    // Unparsable --since values are rejected.
+    let out = phantom_query(tmp_dir.path(), &["list", "--since", "yesterday"]);
+    assert_eq!(out.status.code(), Some(1));
+    assert!(String::from_utf8_lossy(&out.stderr).contains("invalid time"));
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Store lock UX
+// ─────────────────────────────────────────────────────────────────────────────
+
+#[test]
+fn test_query_while_store_locked() {
+    let tmp_dir = tempfile::tempdir().expect("tempdir");
+
+    // Hold the store open in this process (simulates a running phantom run/mcp).
+    let _store = phantom_storage::FjallTraceStore::open(tmp_dir.path()).expect("open store");
+
+    let out = phantom_query(tmp_dir.path(), &["list"]);
+    assert!(
+        !out.status.success(),
+        "list should fail while the store is locked"
+    );
+    let stderr = String::from_utf8_lossy(&out.stderr);
+    assert!(
+        stderr.contains("store lock"),
+        "expected lock hint in stderr, got: {stderr}"
+    );
+}
diff --git a/tests/fault_injection.rs b/tests/fault_injection.rs
index b6edbfd..94934bc 100644
--- a/tests/fault_injection.rs
+++ b/tests/fault_injection.rs
@@ -153,6 +153,7 @@ fn test_fault_error_always() {
     // no_proxy / NO_PROXY must be cleared so curl routes 127.0.0.1 through the proxy.
     let out = Command::new(phantom_bin)
         .args([
+            "run",
             "--backend",
             "proxy",
             "--output",
@@ -252,6 +253,7 @@ fn test_fault_delay_adds_latency() {
 
     let out = Command::new(phantom_bin)
         .args([
+            "run",
             "--backend",
             "proxy",
             "--output",
@@ -337,6 +339,7 @@ fn test_fault_url_pattern_filter() {
 
     let out1 = Command::new(phantom_bin)
         .args([
+            "run",
             "--backend",
             "proxy",
             "--output",
@@ -384,6 +387,7 @@ fn test_fault_url_pattern_filter() {
 
     let out2 = Command::new(phantom_bin)
         .args([
+            "run",
             "--backend",
             "proxy",
             "--output",
diff --git a/tests/integration/lib.sh b/tests/integration/lib.sh
index de98e80..cff3b85 100755
--- a/tests/integration/lib.sh
+++ b/tests/integration/lib.sh
@@ -290,7 +290,7 @@ run_phantom_capture() {
     # The child process (curl) shares stdout with phantom, so its body output
     # may be interleaved.  We match on "trace_id" which is unique to phantom's
     # output, then extract the JSON object.
-    timeout 10 "$PHANTOM" --backend ldpreload --output jsonl \
+    timeout 10 "$PHANTOM" run --backend ldpreload --output jsonl \
         --agent-lib "$AGENT_LIB" -- $cmd 2>/dev/null \
         | grep -o '{"timestamp_ms".*}$' || true
 }
diff --git a/tests/mcp_stdio_integration.rs b/tests/mcp_stdio_integration.rs
new file mode 100644
index 0000000..6e7ea82
--- /dev/null
+++ b/tests/mcp_stdio_integration.rs
@@ -0,0 +1,476 @@
+//! MCP server smoke test: speaks raw newline-delimited JSON-RPC to
+//! `phantom mcp` over stdio (no MCP client library involved).
+//!
+//! Covers: initialize handshake, tools/list, get_stats, start_capture with a
+//! traced curl child against an in-process mock backend, capture_status
+//! polling, list_traces filtering, get_trace, stop_capture, clean shutdown
+//! on stdin EOF.
+//!
+//! Requirements: `curl` on PATH for the capture round-trip (that part is
+//! skipped otherwise). Run: `cargo test --test mcp_stdio_integration`
+
+use std::io::{BufRead, BufReader, Read, Write as IoWrite};
+use std::net::TcpListener;
+use std::process::{Child, ChildStdin, Command, Stdio};
+use std::time::{Duration, Instant};
+
+use serde_json::{Value, json};
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Mock HTTP backend (same pattern as fault_injection.rs)
+// ─────────────────────────────────────────────────────────────────────────────
+
+const HEALTH_BODY: &str = r#"{"status":"ok"}"#;
+
+fn start_http_backend() -> u16 {
+    let listener = TcpListener::bind("127.0.0.1:0").expect("bind mock backend");
+    let port = listener.local_addr().unwrap().port();
+    std::thread::spawn(move || {
+        for stream in listener.incoming() {
+            let Ok(mut s) = stream else { break };
+            let mut buf = [0u8; 8192];
+            let n = match s.read(&mut buf) {
+                Ok(0) | Err(_) => continue,
+                Ok(n) => n,
+            };
+            let req = String::from_utf8_lossy(&buf[..n]);
+            let (status, body) = if req.lines().next().unwrap_or("").contains("/api/health") {
+                ("200 OK", HEALTH_BODY)
+            } else {
+                ("404 Not Found", r#"{"error":"Not Found"}"#)
+            };
+            let resp = format!(
+                "HTTP/1.1 {status}\r\nContent-Type: application/json\r\nContent-Length: {}\r\nConnection: close\r\n\r\n{body}",
+                body.len()
+            );
+            let _ = s.write_all(resp.as_bytes());
+        }
+    });
+    port
+}
+
+fn curl_missing() -> bool {
+    Command::new("curl")
+        .arg("--version")
+        .stdout(Stdio::null())
+        .stderr(Stdio::null())
+        .status()
+        .is_err()
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Minimal JSON-RPC client over the child's stdio
+// ─────────────────────────────────────────────────────────────────────────────
+
+struct McpClient {
+    child: Child,
+    stdin: ChildStdin,
+    reader: BufReader<std::process::ChildStdout>,
+    next_id: u64,
+}
+
+impl McpClient {
+    fn start(data_dir: &std::path::Path) -> Self {
+        let mut child = Command::new(env!("CARGO_BIN_EXE_phantom"))
+            .args(["mcp", "--data-dir"])
+            .arg(data_dir)
+            .stdin(Stdio::piped())
+            .stdout(Stdio::piped())
+            .stderr(Stdio::null())
+            .spawn()
+            .expect("spawn phantom mcp");
+        let stdin = child.stdin.take().unwrap();
+        let reader = BufReader::new(child.stdout.take().unwrap());
+        let mut client = Self {
+            child,
+            stdin,
+            reader,
+            next_id: 0,
+        };
+        client.initialize();
+        client
+    }
+
+    fn send(&mut self, msg: &Value) {
+        let mut line = msg.to_string();
+        line.push('\n');
+        self.stdin.write_all(line.as_bytes()).expect("write to mcp");
+        self.stdin.flush().unwrap();
+    }
+
+    /// Sends a request and reads lines until its full JSON-RPC response
+    /// arrives (skipping any server-initiated notifications).
+    fn request_raw(&mut self, method: &str, params: Value) -> Value {
+        self.next_id += 1;
+        let id = self.next_id;
+        self.send(&json!({"jsonrpc": "2.0", "id": id, "method": method, "params": params}));
+        loop {
+            let mut line = String::new();
+            let n = self.reader.read_line(&mut line).expect("read from mcp");
+            assert!(n > 0, "mcp server closed stdout while awaiting {method}");
+            let v: Value = serde_json::from_str(&line).expect("mcp response is JSON");
+            if v["id"] == json!(id) {
+                return v;
+            }
+        }
+    }
+
+    /// Like `request_raw`, but asserts success and returns only the result.
+    fn request(&mut self, method: &str, params: Value) -> Value {
+        let v = self.request_raw(method, params);
+        assert!(
+            v.get("error").is_none(),
+            "{method} returned error: {}",
+            v["error"]
+        );
+        v["result"].clone()
+    }
+
+    /// Calls an MCP tool and returns the parsed JSON content of its result.
+    fn call_tool(&mut self, name: &str, arguments: Value) -> Value {
+        let result = self.request("tools/call", json!({"name": name, "arguments": arguments}));
+        assert_ne!(
+            result["isError"],
+            json!(true),
+            "tool {name} failed: {result}"
+        );
+        let content = &result["content"][0];
+        // Content is either structured json or a text block containing JSON.
+        if let Some(text) = content["text"].as_str() {
+            serde_json::from_str(text).unwrap_or_else(|_| json!(text))
+        } else {
+            content["json"].clone()
+        }
+    }
+
+    /// Calls a tool that is expected to fail; returns the error message.
+    /// Tool failures may surface as a JSON-RPC error or as a CallToolResult
+    /// with isError: true, depending on the failure layer.
+    fn call_tool_expect_error(&mut self, name: &str, arguments: Value) -> String {
+        let v = self.request_raw("tools/call", json!({"name": name, "arguments": arguments}));
+        if let Some(err) = v.get("error") {
+            return err["message"].as_str().unwrap_or_default().to_string();
+        }
+        let result = &v["result"];
+        assert_eq!(
+            result["isError"],
+            json!(true),
+            "tool {name} unexpectedly succeeded: {result}"
+        );
+        result["content"][0]["text"]
+            .as_str()
+            .unwrap_or_default()
+            .to_string()
+    }
+
+    fn initialize(&mut self) {
+        let result = self.request(
+            "initialize",
+            json!({
+                "protocolVersion": "2025-06-18",
+                "capabilities": {},
+                "clientInfo": {"name": "phantom-test", "version": "0"}
+            }),
+        );
+        assert!(
+            result["capabilities"]["tools"].is_object(),
+            "server must advertise tools capability: {result}"
+        );
+        self.send(&json!({"jsonrpc": "2.0", "method": "notifications/initialized"}));
+    }
+
+    /// Closes stdin and expects the server to exit cleanly.
+    fn shutdown(mut self) {
+        drop(self.stdin);
+        let deadline = Instant::now() + Duration::from_secs(10);
+        loop {
+            match self.child.try_wait().expect("try_wait") {
+                Some(status) => {
+                    assert!(status.success(), "mcp server exited with {status}");
+                    return;
+                }
+                None if Instant::now() > deadline => {
+                    let _ = self.child.kill();
+                    panic!("mcp server did not exit within 10s of stdin EOF");
+                }
+                None => std::thread::sleep(Duration::from_millis(50)),
+            }
+        }
+    }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Tests
+// ─────────────────────────────────────────────────────────────────────────────
+
+const EXPECTED_TOOLS: [&str; 7] = [
+    "start_capture",
+    "stop_capture",
+    "capture_status",
+    "list_traces",
+    "get_trace",
+    "get_stats",
+    "clear_traces",
+];
+
+#[test]
+fn test_mcp_stdio_round_trip() {
+    let tmp_dir = tempfile::tempdir().expect("tempdir");
+    let mut client = McpClient::start(tmp_dir.path());
+
+    // tools/list exposes exactly the expected tool set.
+    let tools = client.request("tools/list", json!({}));
+    let names: Vec<&str> = tools["tools"]
+        .as_array()
+        .unwrap()
+        .iter()
+        .map(|t| t["name"].as_str().unwrap())
+        .collect();
+    for expected in EXPECTED_TOOLS {
+        assert!(
+            names.contains(&expected),
+            "missing tool {expected}: {names:?}"
+        );
+    }
+    assert_eq!(
+        names.len(),
+        EXPECTED_TOOLS.len(),
+        "unexpected tools: {names:?}"
+    );
+
+    // Empty store.
+    let stats = client.call_tool("get_stats", json!({}));
+    assert_eq!(stats["total_traces"], 0);
+    assert_eq!(stats["active_sessions"], 0);
+
+    if curl_missing() {
+        eprintln!("SKIP: `curl` not found — skipping capture round-trip");
+        client.shutdown();
+        return;
+    }
+
+    // Start a capture that traces one curl request against the mock backend.
+    let backend_port = start_http_backend();
+    let started = client.call_tool(
+        "start_capture",
+        json!({
+            "command": [
+                "sh", "-c",
+                format!(
+                    "curl --silent --output /dev/null --proxy \"$HTTP_PROXY\" http://127.0.0.1:{backend_port}/api/health"
+                )
+            ]
+        }),
+    );
+    let session_id = started["session_id"]
+        .as_str()
+        .expect("session_id")
+        .to_string();
+    assert!(started["port"].as_u64().unwrap() > 0);
+    assert_eq!(started["state"], "running");
+
+    // Poll until the child exits and the trace is pumped.
+    let deadline = Instant::now() + Duration::from_secs(15);
+    loop {
+        let status = client.call_tool("capture_status", json!({"session_id": session_id}));
+        let session = &status["sessions"][0];
+        if session["state"] == "exited" && session["trace_count"].as_u64() == Some(1) {
+            assert_eq!(session["exit_code"], 0);
+            break;
+        }
+        assert!(
+            Instant::now() < deadline,
+            "capture did not finish in time: {status}"
+        );
+        std::thread::sleep(Duration::from_millis(100));
+    }
+
+    // list_traces sees the request; body is present (small) and status matches.
+    let listed = client.call_tool("list_traces", json!({"status": "2xx"}));
+    let traces = listed["traces"].as_array().unwrap();
+    assert_eq!(traces.len(), 1, "expected one trace: {listed}");
+    assert!(traces[0]["url"].as_str().unwrap().contains("/api/health"));
+    let span_id = traces[0]["span_id"].as_str().unwrap().to_string();
+
+    // Non-matching filter.
+    let listed = client.call_tool("list_traces", json!({"status": "5xx"}));
+    assert!(listed["traces"].as_array().unwrap().is_empty());
+
+    // max_body truncation is flagged.
+    let listed = client.call_tool("list_traces", json!({"max_body": 4}));
+    let t = &listed["traces"][0];
+    assert_eq!(t["response_body"].as_str().unwrap().len(), 4);
+    assert_eq!(t["response_body_truncated"], true);
+
+    // get_trace returns full detail.
+    let trace = client.call_tool("get_trace", json!({"span_id": span_id}));
+    assert_eq!(trace["span_id"], span_id.as_str());
+    assert_eq!(trace["response_body"].as_str().unwrap(), HEALTH_BODY);
+
+    // stop_capture tears the session down.
+    let stopped = client.call_tool("stop_capture", json!({"session_id": session_id}));
+    assert_eq!(stopped["state"], "exited");
+    let stats = client.call_tool("get_stats", json!({}));
+    assert_eq!(stats["active_sessions"], 0);
+    assert_eq!(stats["total_traces"], 1);
+
+    // clear_traces requires confirm and empties the store.
+    let cleared = client.call_tool("clear_traces", json!({"confirm": true}));
+    assert_eq!(cleared["cleared"], true);
+    let listed = client.call_tool("list_traces", json!({}));
+    assert!(listed["traces"].as_array().unwrap().is_empty());
+
+    client.shutdown();
+}
+
+#[test]
+fn test_mcp_tool_error_paths() {
+    let tmp_dir = tempfile::tempdir().expect("tempdir");
+    let mut client = McpClient::start(tmp_dir.path());
+
+    // Unknown / malformed span IDs.
+    let msg = client.call_tool_expect_error("get_trace", json!({"span_id": "ffffffffffffffff"}));
+    assert!(msg.contains("no trace found"), "unexpected message: {msg}");
+    let msg = client.call_tool_expect_error("get_trace", json!({"span_id": "not-hex"}));
+    assert!(msg.contains("invalid span_id"), "unexpected message: {msg}");
+
+    // Unknown session IDs.
+    let msg = client.call_tool_expect_error("stop_capture", json!({"session_id": "deadbeef"}));
+    assert!(msg.contains("unknown session"), "unexpected message: {msg}");
+    let msg = client.call_tool_expect_error("capture_status", json!({"session_id": "deadbeef"}));
+    assert!(msg.contains("unknown session"), "unexpected message: {msg}");
+
+    // Malformed filters.
+    let msg = client.call_tool_expect_error("list_traces", json!({"method": ["FETCH"]}));
+    assert!(
+        msg.contains("unknown HTTP method"),
+        "unexpected message: {msg}"
+    );
+    let msg = client.call_tool_expect_error("list_traces", json!({"status": "bogus"}));
+    assert!(
+        msg.contains("invalid status range"),
+        "unexpected message: {msg}"
+    );
+    let msg = client.call_tool_expect_error("list_traces", json!({"trace_id": "xyz"}));
+    assert!(
+        msg.contains("invalid trace_id"),
+        "unexpected message: {msg}"
+    );
+
+    // clear_traces without confirmation refuses and deletes nothing.
+    let msg = client.call_tool_expect_error("clear_traces", json!({"confirm": false}));
+    assert!(msg.contains("confirm"), "unexpected message: {msg}");
+
+    client.shutdown();
+}
+
+#[test]
+fn test_mcp_proxy_only_session() {
+    if curl_missing() {
+        eprintln!("SKIP: `curl` not found");
+        return;
+    }
+
+    let tmp_dir = tempfile::tempdir().expect("tempdir");
+    let mut client = McpClient::start(tmp_dir.path());
+    let backend_port = start_http_backend();
+
+    // No command: phantom starts the proxy and reports proxy_only state.
+    let started = client.call_tool("start_capture", json!({}));
+    assert_eq!(started["state"], "proxy_only");
+    assert_eq!(started["pid"], Value::Null);
+    let session_id = started["session_id"].as_str().unwrap().to_string();
+    let proxy_url = started["proxy_url"].as_str().unwrap().to_string();
+
+    // A client configured with the returned proxy_url is captured.
+    // no_proxy must be cleared so curl routes 127.0.0.1 through the proxy.
+    let status = Command::new("curl")
+        .args(["--silent", "--output", "/dev/null", "--proxy", &proxy_url])
+        .arg(format!("http://127.0.0.1:{backend_port}/api/health"))
+        .env("NO_PROXY", "")
+        .env("no_proxy", "")
+        .status()
+        .expect("curl through proxy");
+    assert!(status.success(), "curl through the proxy failed");
+
+    // The trace shows up without any child process involved.
+    let deadline = Instant::now() + Duration::from_secs(10);
+    loop {
+        let status = client.call_tool("capture_status", json!({"session_id": session_id}));
+        if status["sessions"][0]["trace_count"].as_u64() == Some(1) {
+            break;
+        }
+        assert!(
+            Instant::now() < deadline,
+            "trace was not captured: {status}"
+        );
+        std::thread::sleep(Duration::from_millis(100));
+    }
+
+    let stopped = client.call_tool("stop_capture", json!({"session_id": session_id}));
+    assert_eq!(stopped["state"], "proxy_only");
+    assert_eq!(stopped["trace_count"], 1);
+
+    client.shutdown();
+}
+
+#[test]
+fn test_mcp_redacts_sensitive_headers_by_default() {
+    if curl_missing() {
+        eprintln!("SKIP: `curl` not found");
+        return;
+    }
+
+    let tmp_dir = tempfile::tempdir().expect("tempdir");
+    let mut client = McpClient::start(tmp_dir.path());
+    let backend_port = start_http_backend();
+
+    let started = client.call_tool(
+        "start_capture",
+        json!({
+            "command": [
+                "sh", "-c",
+                format!(
+                    "curl --silent --output /dev/null --proxy \"$HTTP_PROXY\" \
+                     -H 'Authorization: Bearer sekrit-token' \
+                     http://127.0.0.1:{backend_port}/api/health"
+                )
+            ]
+        }),
+    );
+    let session_id = started["session_id"].as_str().unwrap().to_string();
+
+    let deadline = Instant::now() + Duration::from_secs(15);
+    loop {
+        let status = client.call_tool("capture_status", json!({"session_id": session_id}));
+        let session = &status["sessions"][0];
+        if session["state"] == "exited" && session["trace_count"].as_u64() == Some(1) {
+            break;
+        }
+        assert!(
+            Instant::now() < deadline,
+            "capture did not finish: {status}"
+        );
+        std::thread::sleep(Duration::from_millis(100));
+    }
+
+    // Default: the authorization value never reaches the agent.
+    let listed = client.call_tool("list_traces", json!({}));
+    let headers = &listed["traces"][0]["request_headers"];
+    assert_eq!(headers["authorization"], "[redacted]");
+
+    // Same for get_trace.
+    let span_id = listed["traces"][0]["span_id"].as_str().unwrap().to_string();
+    let trace = client.call_tool("get_trace", json!({"span_id": span_id}));
+    assert_eq!(trace["request_headers"]["authorization"], "[redacted]");
+
+    // Explicit opt-out reveals the raw value.
+    let listed = client.call_tool("list_traces", json!({"redact_sensitive_headers": false}));
+    assert_eq!(
+        listed["traces"][0]["request_headers"]["authorization"],
+        "Bearer sekrit-token"
+    );
+
+    client.call_tool("stop_capture", json!({"session_id": session_id}));
+    client.shutdown();
+}
diff --git a/tests/proxy_java_clients_integration.rs b/tests/proxy_java_clients_integration.rs
index e3fd159..c1f8d0a 100644
--- a/tests/proxy_java_clients_integration.rs
+++ b/tests/proxy_java_clients_integration.rs
@@ -228,6 +228,7 @@ fn test_proxy_captures_java_http_clients() {
     // so the Java app needs zero proxy configuration of its own.
     let phantom_output = Command::new(phantom_bin)
         .args([
+            "run",
             "--backend",
             "proxy",
             "--output",
diff --git a/tests/proxy_node_integration.rs b/tests/proxy_node_integration.rs
index b0f5736..9b3d893 100644
--- a/tests/proxy_node_integration.rs
+++ b/tests/proxy_node_integration.rs
@@ -185,6 +185,7 @@ fn test_proxy_captures_node_app_traffic() {
     // The proxy-preload.js is injected automatically by phantom for Node.js.
     let phantom_output = Command::new(phantom_bin)
         .args([
+            "run",
             "--backend",
             "proxy",
             "--output",
@@ -402,6 +403,7 @@ fn test_proxy_captures_alternative_http_clients() {
     // AND undici/fetch via setGlobalDispatcher.
     let phantom_output = Command::new(phantom_bin)
         .args([
+            "run",
             "--backend",
             "proxy",
             "--output",
diff --git a/tests/proxy_php_integration.rs b/tests/proxy_php_integration.rs
index 3c9ae1e..ef49e40 100644
--- a/tests/proxy_php_integration.rs
+++ b/tests/proxy_php_integration.rs
@@ -202,6 +202,7 @@ fn test_proxy_captures_php_curl_traffic() {
     // cert via the injected -d curl.cainfo=<path>, with normal verification.
     let phantom_output = Command::new(phantom_bin)
         .args([
+            "run",
             "--backend",
             "proxy",
             "--output",
diff --git a/tests/proxy_php_ldpreload_integration.rs b/tests/proxy_php_ldpreload_integration.rs
index 56e9dc2..98c7073 100644
--- a/tests/proxy_php_ldpreload_integration.rs
+++ b/tests/proxy_php_ldpreload_integration.rs
@@ -221,7 +221,14 @@ fn test_ldpreload_captures_php_curl_traffic() {
     // directly to the backends and the agent captures traffic at the libc /
     // OpenSSL layer underneath it.
     let phantom_output = Command::new(phantom_bin)
-        .args(["--backend", "ldpreload", "--output", "jsonl", "--agent-lib"])
+        .args([
+            "run",
+            "--backend",
+            "ldpreload",
+            "--output",
+            "jsonl",
+            "--agent-lib",
+        ])
         .arg(&agent_lib)
         .arg("--data-dir")
         .arg(tmp_dir.path())