Marionette documentation MCP#

Connect to https://mcp.marionettejs.com/mcp for public, read-only documentation retrieval. No server login, API key, subscription, or model inference is required. Your agent client's own access and model costs are separate.

The hosted Cloudflare Worker and the optional local, read-only stdio server share search_docs, get_doc, search_sections, get_sections, get_symbol, get_diagnostic, get_example, and marionette://catalog. Both serve the same verified package artifact and packaged records example. Website reading-copy edits and supplemental guides are excluded from MCP contracts. Links identify the immutable source revision. This integration is verified against the version and source revision reported by its catalog. Importing or building does not update the hosted endpoint: read its catalog before using it.

Bundled Markdown remains the installed-version reference. First inspect your application's installed package: docs-manifest.json is at the package root and Markdown is under docs/. Use the consumer skill helper if available. Use get_symbol for exact API signatures and contract section IDs, and get_diagnostic for an MN code’s remediation and retrievable document ID. Ambiguous symbol names support bounded pagination.

Compare its version and source revision with the MCP catalog. A custom build with the same version label may contain different code. If they do not match, use the installed docs; never substitute the hosted snapshot for another version.

Connect a supported client#

Use a client with Streamable HTTP support. The URL is an MCP protocol endpoint; opening it as an ordinary browser page returns 405 Method Not Allowed. There is no separate /sse endpoint and no authentication step.

Codex#

Add the server with the CLI:

codex mcp add marionette-docs --url https://mcp.marionettejs.com/mcp

Or add this to your Codex config.toml:

[mcp_servers.marionette-docs]
url = "https://mcp.marionettejs.com/mcp"

See Codex MCP configuration.

Claude Code#

From the application directory, add it to project configuration:

claude mcp add --transport http --scope project marionette-docs https://mcp.marionettejs.com/mcp

Use /mcp to inspect the connection. See Claude Code MCP setup.

VS Code#

Add this to .vscode/mcp.json, merging with existing servers:

{
  "servers": {
    "marionette-docs": {
      "type": "http",
      "url": "https://mcp.marionettejs.com/mcp"
    }
  }
}

Use MCP: List Servers to start and inspect it. See VS Code MCP configuration. Other clients may use a different configuration shape; use their documented Streamable HTTP settings rather than assuming these files are interchangeable.

After connecting, ask the agent:

Read marionette://catalog and compare its version and source revision with this
application's installed Marionette documentation. If they match, search for
Region ownership, then read the relevant document through every nextOffset.
Report the provenance and explain the contract. Do not modify the application.

Optional local stdio server#

Use Node.js 24 or newer. Clone and review the website source, then install its locked dependencies and build the package-specific MCP corpus:

git clone https://github.com/marionettejs/marionettejs.com.git
cd marionettejs.com
npm ci
npm run build
node mcp/server.mjs

The final command waits for an MCP client on stdin; silence is expected. It is not an interactive shell. This repository does not publish an npm MCP package.

Configure a client that supports local stdio servers with the following command and argument. Replace both absolute paths with your installed Node 24+ binary and cloned repository location. The server works independently of client cwd.

{
  "mcpServers": {
    "marionette-docs": {
      "command": "/absolute/path/to/node",
      "args": ["/absolute/path/to/website/mcp/server.mjs"]
    }
  }
}

This is the common mcpServers configuration shape; use your client's equivalent stdio settings if its configuration differs. Do not launch through npm run in a client command: npm's normal script banner would mix with protocol stdout. For a terminal smoke check, run npm run build && node --test test/mcp.test.mjs.

After updating the checkout or importing a new documentation snapshot, run npm ci and npm run build again and restart the MCP connection. The server reads the generated corpus once at startup and rejects mismatched snapshot or publication provenance.

Retrieval workflow#

1. Read marionette://catalog for the exact supported package version, provenance, document count, and example names.
2. Start with search_sections and get_sections for the specific API or workflow you need, with your exact installed version (and sourceRevision for a candidate snapshot). Bound the read with maxCharacters. See focused section retrieval below. For whole documents, call search_docs. Search ranks word matches in titles and Markdown, favors titles and multiple matching terms, and ignores common function words. Results report the terms that matched; they need not contain every query word. This is lexical search, so try an API name if a prose query returns nothing.
3. For whole documents, pass an id returned by search_docs to get_doc as path. Section IDs go to get_sections. Follow nextOffset until it is null to retrieve the complete contract. Search snippets are incomplete.
4. Call get_example with a catalog example name. Concatenate its chunks, then parse the resulting JSON for sourceFiles, sourceHashes and related docs. The packaged README supplies installation and test instructions. This source example is separate from the published browser workshops.

For this snapshot, a search call is:

{"query":"Region", "version":"<version from installed docs>", "sourceRevision":"<exact 40-character revision from installed docs>", "limit":5}

version is required for every tool. Candidate requests also require sourceRevision matching both your installed documentation and the catalog. Unsupported versions, including latest and next, return errors instead of silently choosing another release. Successful tool results contain snapshot version, revision, original content hash, publication edit hash, and generated corpus hash. Document results also include canonical links and the reading Markdown hash. Example results include the hash of the exact returned recipe JSON.

Search returns at most 10 results with 600-character snippets and supports result offsets. Document and example reads default to 8,000 characters and allow at most 12,000 per call. Their offsets count UTF-16 characters, not bytes. Use the returned nextOffset exactly. A requested limit never silently loses the rest of a document or example.

Boundaries and verification#

The tools only read the verified snapshot. Tool arguments cannot select filesystem paths, URLs, imports, or commands. The process reads fixed repository files during startup, makes no network requests, writes no files, and never executes recipe code. The MCP server does not run or certify the example's expected checks. The website workshop and browser tests do that work.

The hosted endpoint runs on Workers Free: no database, Durable Objects, persistent sessions, AI calls, or paid bindings. It accepts at most 16 KiB per HTTP request, including streamed bodies, and rejects JSON batches. Search queries are at most 200 characters; tool schemas reject extra fields. Retrieval results are bounded as described above. Host and browser Origin checks reject untrusted origins; origin-less native MCP clients work. Browser-origin requests are allowed from Marionette's website hosts and localhost; other browser integrations need review.

The published service uses stateless MCP HTTP. It also accepts the initialization sequence used by 2025 Streamable HTTP clients through the SDK's stateless adapter. Neither mode creates a session ID, replay buffer, subscription, or background task. The compatibility adapter is needed by current clients, including the SDK client's default mode; remove it when supported clients no longer need initialization.

Workers Free currently allows 100,000 requests per day across the account and 10 ms CPU per request, with 128 MB memory. Every protocol request and page counts; one agent task may make several calls. Traffic or abuse can exhaust the free allowance. There is no availability guarantee or automatic paid upgrade. Use the installed Markdown or local stdio server when the hosted service is unavailable. See Cloudflare limits.

Search uses an index prepared from the verified corpus at build time rather than retokenizing every document on each request. Local CPU measurements are estimates; Cloudflare's deployed CPU metrics are the evidence for the edge runtime. Maintainers must remeasure after corpus or SDK changes. Merge reviewed changes to main to deploy the website and MCP Worker together through the deployment workflow.

MCP retrieval and the browser workshop#

This endpoint retrieves documentation and recipe source. The website's WebMCP workshop exposes tools inside a compatible browser to build, operate, and inspect a running example. It does not use this remote endpoint. A successful MCP retrieval proves that the source was read; it does not prove that a recipe or consumer application works. Verify actual behavior in the application's own tests.

The local checkout and installed dependencies are executable developer tools. Neither transport reads application source or credentials. Hosted queries go to Cloudflare; do not include private application data in a documentation query. The Worker does not log request bodies or persist queries.

Verification and maintenance#

npm run check uses the official SDK client against both a stdio subprocess and local workerd HTTP. It checks discovery, search pagination, every complete document and recipe, content/provenance parity, version rejection, invalid inputs, request bounds, Origin checks, and shutdown. Startup/build checks reject stale provenance and modified Markdown. The HTTP test also checks the current MCP protocol.

For an explicitly selected endpoint, run:

node scripts/verify-mcp.mjs https://mcp.marionettejs.com/mcp

This performs bounded read-only requests and compares results against the locally built snapshot. The maintenance runbook lives in mcp/DEPLOYMENT.md in the website repository. Local builds and pull-request checks do not publish anything; the deployment workflow publishes both services after a reviewed merge to main.

Implementation references: official SDK web-standard HTTP, and SDK client compatibility.

Focused section retrieval#

Use search_sections with the exact package version to find headings, ancestry, source links and sizes. It uses the imported consumer skill's lexical ranking: identifier components, BM25 body scoring, heading weight and ancestor context. Each query returns up to five sections, scored from each heading's own text; section reads still include nested subsections. limit accepts 1–5 and offset accepts 0–5, paginating within that query's top five. total counts this bounded set; nextOffset becomes null when it is exhausted. An offset at or beyond total returns an empty page. Queries with no substantive terms return an empty set. search_docs separately paginates across all matching documents. Pass returned IDs to get_sections in priority order with maxCharacters (default 20,000, maximum 30,000). The budget counts UTF-16 content characters, not tokens or response metadata. Sections include their subsections; overlapping selections are deduplicated. IDs combine document ID and a rendered heading anchor, or @intro for an introduction without a heading, so a heading rename changes its ID. Resolve IDs from the current version instead of persisting them across documentation revisions.

The reader never truncates a section. Check omitted for contracts that did not fit; request them separately or use paginated get_doc for an oversized section. Search related APIs explicitly: lifecycle resource work may need event ordering, rendering, attachment, detachment and destruction contracts. Lexical ranking does not infer these dependencies or guarantee sufficient context. Full-document reading remains available when necessary.