From 05f6430025c65bb48442c843f75bf5d83b724c4c Mon Sep 17 00:00:00 2001
From: Luca Martial <lucamrtl@gmail.com>
Date: Fri, 15 May 2026 06:15:25 -0700
Subject: [PATCH] docs: add mcp cli reference

---
 .../content/docs/cli-reference/index.mdx      | 12 +++-
 .../content/docs/cli-reference/ktx-mcp.mdx    | 70 +++++++++++++++++++
 .../content/docs/cli-reference/meta.json      |  1 +
 3 files changed, 81 insertions(+), 2 deletions(-)
 create mode 100644 docs-site/content/docs/cli-reference/ktx-mcp.mdx

diff --git a/docs-site/content/docs/cli-reference/index.mdx b/docs-site/content/docs/cli-reference/index.mdx
index c4ef07db..065339ca 100644
--- a/docs-site/content/docs/cli-reference/index.mdx
+++ b/docs-site/content/docs/cli-reference/index.mdx
@@ -4,8 +4,8 @@ description: "Command map and shared options for the KTX CLI."
 ---
 
 The `ktx` CLI sets up local projects, builds agent-ready context, checks
-connections, queries semantic-layer sources, searches wiki pages, and manages
-the bundled Python runtime.
+connections, queries semantic-layer sources, searches wiki pages, runs the MCP
+server, and manages the bundled Python runtime.
 
 ## Command Map
 
@@ -26,6 +26,11 @@ ktx
     validate <sourceName>
     query
   status
+  mcp
+    start
+    stop
+    status
+    logs
   dev
     init [directory]
     schema
@@ -73,4 +78,7 @@ ktx ingest --all
 # Search semantic-layer sources and wiki pages
 ktx sl search "revenue"
 ktx wiki search "revenue recognition"
+
+# Start the local MCP server for agent clients
+ktx mcp start
 ```
diff --git a/docs-site/content/docs/cli-reference/ktx-mcp.mdx b/docs-site/content/docs/cli-reference/ktx-mcp.mdx
new file mode 100644
index 00000000..9f0dd189
--- /dev/null
+++ b/docs-site/content/docs/cli-reference/ktx-mcp.mdx
@@ -0,0 +1,70 @@
+---
+title: "ktx mcp"
+description: "Run the KTX MCP HTTP server for agent clients."
+---
+
+`ktx mcp` starts, stops, inspects, and tails the local KTX MCP server for a KTX
+project. Use it when an agent client connects through MCP instead of generated
+CLI instructions.
+
+## Command signature
+
+```bash
+ktx mcp <subcommand> [options]
+```
+
+## Subcommands
+
+| Subcommand | Description |
+|-----------|-------------|
+| `start` | Start the KTX MCP HTTP server |
+| `stop` | Stop the KTX MCP daemon |
+| `status` | Show daemon status, URL, PID, token mode, and project path |
+| `logs` | Print the daemon log |
+
+## `mcp start` Options
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--host <host>` | Host to bind | `127.0.0.1` |
+| `--port <n>` | Port to bind | `7878` |
+| `--token <token>` | Bearer token for non-loopback binding | `KTX_MCP_TOKEN` |
+| `--foreground` | Run the server in the foreground | `false` |
+| `--allowed-host <host>` | Additional allowed Host header; repeatable | - |
+| `--allowed-origin <origin>` | Allowed browser Origin header; repeatable | - |
+
+## `mcp logs` Options
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--follow` | Follow log output | `false` |
+
+## Examples
+
+```bash
+# Start the daemon on localhost
+ktx mcp start
+
+# Check status
+ktx mcp status
+
+# Tail logs
+ktx mcp logs --follow
+
+# Run in the foreground on a custom port
+ktx mcp start --port 8787 --foreground
+```
+
+## Security notes
+
+The default host is loopback-only. If you bind to a non-loopback host, configure
+a bearer token with `--token <token>` or `KTX_MCP_TOKEN` and restrict allowed
+hosts and origins for browser clients.
+
+## Common errors
+
+| Error | Cause | Recovery |
+|-------|-------|----------|
+| No KTX project found | Current directory has no `ktx.yaml` and `KTX_PROJECT_DIR` is unset | Run from a KTX project or pass `--project-dir <path>` |
+| Non-loopback host rejected | The server needs token auth before binding beyond localhost | Pass `--token <token>` or set `KTX_MCP_TOKEN` |
+| Client cannot connect | Host, port, token, allowed host, or allowed origin does not match the client | Check `ktx mcp status`, then restart with explicit `--host`, `--port`, `--allowed-host`, and `--allowed-origin` values |
diff --git a/docs-site/content/docs/cli-reference/meta.json b/docs-site/content/docs/cli-reference/meta.json
index 46aafb4c..4103c025 100644
--- a/docs-site/content/docs/cli-reference/meta.json
+++ b/docs-site/content/docs/cli-reference/meta.json
@@ -9,6 +9,7 @@
     "ktx-sl",
     "ktx-wiki",
     "ktx-status",
+    "ktx-mcp",
     "ktx-dev"
   ]
 }