Skip to content

MCP tools

@docsxai/mcp is a standalone MCP server over the engine (stdio, plus an opt-in HTTP transport). It is repo-only: private: true, not on npm, so you run it from a source checkout. 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, so behaviour is identical by construction.

The boundary is load-bearing: this server exposes calibration meta-orchestration plus read-only doc-pack introspection only. It deliberately exposes no browser primitives - no click, fill, or inspect on an arbitrary live page. Live-page discovery during calibration is browxai's surface; keeping the two disjoint is what keeps docsxai run agent-free and reproducible.

{
"mcpServers": {
"docsxai": {
"command": "docsxai-mcp",
"args": ["--workspace", "/absolute/path/to/docsxai-workspace"]
}
}
}

--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.

stdio is the default. docsxai-mcp serve --http --workspace-root <dir> serves the same fourteen tools at /mcp over Streamable HTTP, for a host that connects by URL. Nothing is added or removed; the server enforces more around them:

  • A bearer token is required. It comes from DOCSX_MCP_TOKEN or --token-file, never from an argument, and has to be at least 32 printable ASCII characters with at least 8 distinct ones. A token file that group or other can read is refused on POSIX.
  • It binds 127.0.0.1:8765. A non-loopback --host needs --allow-remote, and the server speaks plain HTTP, so terminate TLS in front of it.
  • Every path a tool receives has to resolve, symlinks included, inside --workspace-root, which is required.
  • run_flows and diagnose_halt refuse cdp. run_flows refuses a baseUrl (or a workspace app_url) that is not an http(s) URL or whose host is, or resolves to, a link-local or cloud-metadata address (with DOCSX_EGRESS_DENY_PRIVATE on, a loopback or private one too), and the browser it starts gets the engine's request guard.
  • Host and Origin are checked against an allow-list (403, before the token), and there are limits of 1 MiB per body, 16 sessions and 30 minutes idle.

The flags, the full list of checks and a client config are in the package page.

ToolKindWhat it does
init_workspaceorchestrationScaffold a new docsxai workspace (flows/, docs/, auth/strategy.yaml, .docsxai.json).
run_flowsorchestrationDeterministic 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_viewerorchestrationBuild the static viewer by spawning the docsxai-viewer bin (the engine's resolution order).
lint_flowsintrospectionThe static lint rules, plus plugin-contributed rules when the workspace's plugin set resolves.
flow_treeintrospectionThe extends graph: roots, descendants, orphans, resolution issues.
diagnose_haltorchestrationHalt context for one step plus typed recommendations; optional live actionable() probe over CDP. Never edits the flow-file.
style_checkorchestrationInit or validate docs/style.yaml, rederive the JSON, scan write-ups for jargon leaks.
zip_packorchestrationDeterministic hand-off archive of the doc pack.
push_packorchestrationPush the doc pack as a new backend revision (content-addressed screenshot blobs).
pull_packorchestrationPull a revision's artifacts back into the workspace files.
list_flowsintrospectionEvery flow's name, steps, extends parent, environment summary.
get_annotationsintrospectionA flow's annotations.json, schema-validated.
get_run_artifactsintrospectionArtifact paths only (annotations, screenshots, halt shots, write-ups, viewer index).
plugins_listintrospectionResolve and load the workspace's plugin set; status, trust, and artifacts per plugin.

Every result is structured JSON: { "ok": true, ... } on success, { "ok": false, "error": "...", "hint": "..." } on failure - the hint is the agent-actionable next step. run_flows reports per-flow ok, so one halted flow does not 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 this result contract) 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. workspace is the CLI's <workspace-dir>; init_workspace calls the same thing dir.

The tools do not expand a flow's matrix: run_flows reports a flow that has one as failed, and diagnose_halt has no variant argument. Use docsxai run and docsxai diagnose --variant <id> for those flows.

One call and result per tool family. Workspace paths are elided as ….

Execution (run_flows). A halted flow stays a per-flow result; the call itself still succeeds:

// call
{ "name": "run_flows", "arguments": { "flow": "publish-post" } }
// result
{
"ok": true,
"workspace": "…/docsxai/my-app",
"allOk": false,
"concurrency": 1,
"flows": [
{
"flow": "publish-post",
"ok": false,
"haltStep": "publish",
"haltCause": "target is covered by another element",
"error": "[target is covered by another element] step \"publish\" (click) failed at https://localhost:3000/editor/draft-7: … (halt screenshot: docs/publish-post/halts/publish.png)"
}
]
}

Introspection (list_flows). Read-only; never launches a browser:

// call
{ "name": "list_flows", "arguments": {} }
// result
{
"ok": true,
"workspace": "…/docsxai/my-app",
"flows": [
{
"name": "publish-post",
"file": "flows/publish-post.flow.yaml",
"extends": "login",
"stepCount": 5,
"steps": [
{ "id": "open-editor", "action": "click" },
{ "id": "write-draft", "action": "fill" },
{ "id": "publish", "action": "click" },
{ "id": "dismiss-confirm", "action": "click", "optional": true },
{ "id": "confirm-live", "action": "navigate" }
],
"environment": { "viewport": "desktop", "clock": "2030-01-02T03:04:05Z" }
}
]
}

Diagnosis (diagnose_halt). The same typed recommendations as docsxai diagnose --format json; pass cdp for the live probe:

// call
{
"name": "diagnose_halt",
"arguments": { "flow": "publish-post", "step": "publish", "cdp": "http://localhost:9222" }
}

Failure shape. Any tool that cannot proceed returns the error pair instead of throwing:

{
"ok": false,
"error": "no flow named \"publsh-post\"",
"hint": "list_flows shows the available flow names"
}
VariableUsed byMeaning
DOCSX_VIEWER_BINrender_viewerExplicit path to the viewer bin (overrides package/PATH resolution).
DOCSX_TOKENpush_pack, pull_packBackend bearer token (when not using the OAuth token file).
DOCSX_MCP_TOKENserve --httpBearer token clients must send, at least 32 characters. Required.
DOCSX_EGRESS_GUARDrun_flows over HTTPOn by default over HTTP; 0, false or no switches the request guard off.
DOCSX_EGRESS_DENY_PRIVATErun_flows over HTTP1, true or yes also refuses loopback and private-network hosts.
DOCSX_* credsrun_flows (auth strategies)Per-role credential env vars named in auth/strategy.yaml.

For install and test detail see the package page; for the endpoints behind push_pack / pull_pack see the backend API.

Made by KalebtecGitHubApache-2.0 licensed