@docsxai/mcp
Standalone MCP server (stdio, plus an opt-in Streamable HTTP transport) over the docsxai engine. It lets any MCP-speaking host agent
(Claude Code, Codex, Cursor, a scripted client, …) drive the calibration workflow and introspect a
doc pack without shelling out to the docsxai CLI. The tools wrap the same engine functions
the CLI wraps; behaviour is identical by construction.
Boundary (load-bearing) vs. browxai
Section titled “Boundary (load-bearing) vs. browxai”This server exposes calibration meta-orchestration + read-only doc-pack introspection only.
It deliberately exposes no browser primitives: no click/fill/inspect on an arbitrary live
page. Live-page discovery during calibration is browxai's surface;
docsxai-mcp orchestrates the deterministic engine around it. Keeping the two surfaces disjoint is
what keeps docsxai run agent-free and reproducible.
Install / run
Section titled “Install / run”pnpm -r build # the bin runs from dist/node packages/mcp/dist/bin.js --workspace ~/docsxai/my-app--workspace <dir> sets the default workspace for tool calls that omit the workspace argument;
every tool also accepts an explicit workspace per call. Logs go to stderr; stdout is the MCP
wire.
Client config snippet
Section titled “Client config snippet”{ "mcpServers": { "docsxai": { "command": "docsxai-mcp", "args": ["--workspace", "/absolute/path/to/docsxai-workspace"] } }}(Or "command": "node", "args": ["<repo>/packages/mcp/dist/bin.js", …] when running from a
checkout.)
Streamable HTTP (opt-in, experimental)
Section titled “Streamable HTTP (opt-in, experimental)”stdio stays the default. For a host that connects over HTTP, start the server with serve --http:
export DOCSX_MCP_TOKEN="$(openssl rand -hex 32)" # or: --token-file <path>node packages/mcp/dist/bin.js serve --http --workspace-root ~/docsxai --workspace ~/docsxai/my-app# docsxai-mcp: listening on http://127.0.0.1:8765/mcp (bearer token required)Clients send Authorization: Bearer <token> on every request. The tool registry is the one stdio
serves; nothing is added or removed.
| Flag | Meaning |
|---|---|
--http | Required. Serve at /mcp over HTTP instead of stdio. |
--workspace-root <dir> | Required. Absolute path of an existing directory; every path a tool receives must resolve inside it. |
--port <n> | Port, default 8765. 0 picks a free one. |
--host <host> | Interface to bind, default 127.0.0.1. |
--token-file <path> | File holding the token. Wins over DOCSX_MCP_TOKEN when both are set. |
--allowed-host <h> | Extra hostname accepted in the Host and Origin headers. Exact names, repeatable. |
--allowed-origin <o> | Extra exact Origin (scheme://host[:port]), for a browser UI or a TLS proxy. Repeatable. |
--allow-remote | Required to bind anything but loopback. Terminate TLS in front of the server when you use it. |
What the server enforces:
- Workspace root. The server refuses to start without
--workspace-root. Every path a tool receives (workspace,init_workspace'sdir,zip_pack'sout) is resolved through symlinks and has to land inside the root, or the call fails. Relative paths start at the root, and a call that omitsworkspaceuses--workspace, then the root itself...and links that point out of the root are refused. Paths inside a workspace that a flow or config names are not re-checked, so keep the root free of workspaces you do not trust. stdio is unchanged. - Browser tools. Over HTTP,
run_flowsanddiagnose_haltrefusecdp,run_flowsrefuses abaseUrl(or a workspaceapp_url) that is not an http(s) URL or whose host is, or resolves to, a link-local or cloud-metadata address (and, withDOCSX_EGRESS_DENY_PRIVATEon, a loopback or private one), and every browser a tool starts gets the engine's request guard (DOCSX_EGRESS_GUARDset to0,falseornoswitches it off). The refusal message names no address. stdio is unchanged. - Token. Required, at least 32 printable ASCII characters with at least 8 distinct ones. It is
read from
DOCSX_MCP_TOKENor--token-file, never from an argument (--token ...is refused without echoing it), compared in constant time, and never logged. A token file that group or other can access is refused on POSIX;chmod 600it. The variable is deleted from the server's environment once read, so the processes tools spawn (the viewer build, a browser) do not inherit it. The process's initial environment block can still be readable to the same user on some systems, so prefer--token-file: the variable is a fallback, and the initial environment stays readable to other processes of the same user. On Windows the file's permissions cannot be checked, and the server prints one warning to stderr. The server refuses to start without a token. - Bind. Loopback only. A non-loopback
--hostis refused unless--allow-remoteis passed. The server speaks plain HTTP, so put a TLS-terminating proxy in front of any remote bind. - DNS rebinding. The
Hostheader must be a plainhost[:port](IPv6 in brackets; userinfo, paths and spaces are refused) naming a loopback host, the bound host or an--allowed-host. A request with anOriginheader must name one of the same hosts on the port the server is bound to, or match an--allowed-originentry exactly. A page onhttp://localhost:5173is therefore refused unless you pass--allowed-origin http://localhost:5173. Both checks fail with 403 before the token is checked. - Limits. 1 MiB per request body (413), 16 concurrent sessions (429), and a session closes after
30 minutes with no request. The limits are
startHttpServeroptions, not flags. - Errors. 401, 403, 404, 405, 413 and 429 carry a fixed
{ "error": "<code>" }body and nothing else.
A client config for a host that takes a URL and headers:
{ "mcpServers": { "docsxai": { "url": "http://127.0.0.1:8765/mcp", "headers": { "Authorization": "Bearer <token>" } } }}| Tool | Kind | What it does |
|---|---|---|
init_workspace | orchestration | Scaffold a new docsxai workspace (flows/, docs/, auth/strategy.yaml, .docsxai.json). |
run_flows | orchestration | Deterministic execution: flow filter, startFrom/stopAfter prefix runs, CDP attach, bounded concurrency. Per-flow ok / halt cause / artifact paths. The merged flow's environment (frozen clock, locale, viewport, …) is passed into the Playwright session. |
render_viewer | orchestration | Build the static viewer by spawning the docsxai-viewer bin (engine's resolution order). |
lint_flows | introspection | Static lint rules (R001-R017) plus plugin-contributed extraRules when the workspace's plugin set resolves. |
flow_tree | introspection | The extends graph: roots, descendants, orphans, resolution issues. |
diagnose_halt | orchestration | Halt context for one step + recommendations; optional live actionable() probe over CDP. Never edits the flow-file. |
style_check | orchestration | Init/validate docs/style.yaml, rederive the JSON, scan write-ups for jargon leaks. |
zip_pack | orchestration | Deterministic hand-off archive of the doc pack. |
push_pack | orchestration | Push the doc pack as a new backend revision (content-addressed screenshot blobs). |
pull_pack | orchestration | Pull a revision's artifacts back into the workspace files. |
list_flows | introspection | Every flow's name, steps, extends parent, environment summary. |
get_annotations | introspection | A flow's annotations.json, schema-validated. |
get_run_artifacts | introspection | Artifact paths only (annotations, screenshots, halt shots, write-ups, viewer index). |
plugins_list | introspection | Resolve + load the workspace's plugin set; status/trust/artifacts per plugin. |
Every result is structured JSON: { "ok": true, … } on success, { "ok": false, "error": "…", "hint": "…" } on failure. run_flows reports per-flow ok so one halted flow doesn't mask the
others, and returns ok: true for a run in which a flow halted: read allOk and flows[].ok.
Each tool's description says what it does, when to use it, what it returns and how it fails, and every argument is described in the schema. The server also sends usage instructions (the usual tool order and the result convention) with the tool list.
Arguments are camelCase and follow the CLI: flow is --flow, baseUrl is --base-url,
startFrom and stopAfter are --start-from and --stop-after, out is --out, includeViewer
is --include-viewer. workspace is the CLI's <workspace-dir>; init_workspace calls the same
thing dir. Not every CLI flag has an argument (variant for matrix flows, --pause and
--verify-determinism have none), and style_check scans by default where docsxai style needs
--check.
The tools do not expand a flow's matrix:: run_flows reports such a flow as failed (runFlow
refuses an unexpanded matrix) and diagnose_halt has no variant argument. Run those flows with
docsxai run, and diagnose them with docsxai diagnose --variant <id>.
Environment variables
Section titled “Environment variables”| Var | Used by | Meaning |
|---|---|---|
DOCSX_VIEWER_BIN | render_viewer | Explicit path to the viewer bin (overrides package/PATH resolution). |
DOCSX_TOKEN | push_pack, pull_pack | Backend bearer token (when not using the OAuth token file). |
DOCSX_MCP_TOKEN | serve --http | Bearer token clients must send, at least 32 characters. Required. |
DOCSX_EGRESS_GUARD | run_flows over HTTP | On unless 0, false or no: the engine's request guard. |
DOCSX_EGRESS_DENY_PRIVATE | run_flows over HTTP | 1, true or yes also refuses loopback and private-network hosts. |
DOCSX_* creds | run_flows (auth strategies) | Per-role credential env vars named in auth/strategy.yaml. |
pnpm -C packages/mcp test. The HTTP suite (test/http-server.test.ts) binds an ephemeral loopback
port and drives it with raw requests and the SDK's StreamableHTTPClientTransport. The scripted-client suite drives the whole surface through an
in-process linked client/server pair (the SDK's InMemoryTransport), a non-Claude MCP client as
the acceptance evidence. The run_flows rows run against the engine's toy-site fixture over real
Chromium and are skipped when no Chromium binary is installed
(pnpm -C packages/engine exec playwright-core install chromium).
Limitations
Section titled “Limitations”Not on npm yet: run it from a source checkout. The HTTP transport has no rate limiting on failed tokens and no TLS of its own.