Docs MCP server
Give an AI agent the current Marfa docs, over MCP, from the CLI or as Markdown, so it works from the pages instead of from memory.
An agent that builds on Marfa does better with the current pages than with what it remembers. Every way below reads only this site: none needs a Marfa instance or a credential, and none can reach anyone's data. To work with your data, an agent connects to your own instance, as Use Marfa with AI agents shows.
Connect the docs MCP server
The docs MCP server runs at https://docs.marfa.so/mcp, over the Streamable HTTP transport. Add it to your agent as a remote HTTP server:
claude mcp add --transport http marfa-docs --scope project https://docs.marfa.so/mcp--scope project writes it to the project's .mcp.json, for everyone in the project. Leave it out to add it for yourself, or use --scope user for every project.
The server gives three read-only tools, and tells the agent to search first, then read the page it needs:
| Tool | Input | Answer |
|---|---|---|
docs_search | query, and an optional limit from 1 to 50 | The pages that match, best first, each with its title, path and snippets. Passages and links, never a written answer |
docs_fetch | path, such as /files, and an optional section | The page as Markdown, or only the part under the heading section names |
docs_list_topics | None | Every page, with its title, path and description |
section names a heading by its text, in any case, or by its id, such as who-may-read-a-blob. A path with no page answers the error not_found, and a heading the page lacks answers section_not_found with the page's headings, so the agent can choose one.
Each IP address may make 120 requests a minute to the server. Over it, a client gets 429 and a Retry-After header in seconds.
Search from a terminal
marfa docs reads this site from the CLI, for an agent that runs shell commands. It refuses --url, --key and --socket, so it can't send a credential anywhere.
marfa docs search "sync a folder" --limit 1Each match prints the page's title, its path and a line that matched.
marfa docs topics lists every page, and marfa docs <page> prints one as Markdown. Name a page by its path, such as files, and add --section with a heading to print only that part:
marfa docs cli --section "Exit codes"With --json, each command prints JSON. marfa docs exits 1 when there's no such page or section, and 3 when the site can't be read or limits the request; Exit codes lists them all. To read another copy of the site, set MARFA_DOCS_URL.
Read a page as Markdown
Add .md to a page's path for its Markdown copy, such as /files.md, or ask for the page's own address with Accept: text/markdown. A browser, which ranks HTML higher, still gets the HTML page.
curl -H "Accept: text/markdown" https://docs.marfa.so/quickstart# Quickstart (/quickstart)
Install Marfa on your Mac or Linux computer, connect an agent to it, and save and find your first file.Three files cover the whole site:
| File | What it holds |
|---|---|
/llms.txt | A summary of Marfa, then every page as the sidebar groups them, each linked to its Markdown copy |
/docs-map.md | The same index, with links to the HTML pages |
/llms-full.txt | Every written page in one file, without the API operations and the changelog |
llms.txt links each API operation to its HTML page, because its Markdown copy holds only its title and description. The changelog has its own copy at /changelog.md.
Search over HTTP
For a program with neither MCP nor the CLI, two addresses answer JSON:
GET /api/docs/search?q=<query>&limit=<n>answers{ "hits": [...] }, each hit with itstitle, its path inurl, andsnippets. A blankqor alimitoutside 1 to 50 answers400, withinvalid_queryorinvalid_limitinerror. Each IP address may search 60 times a minute.GET /api/docs/topicsanswers{ "pages": [...] }, each with itstitle,url,descriptionandbreadcrumbs.
What this site sends
This site and the status page at status.marfa.so send counts to PostHog's EU Cloud. Neither sets a cookie or keeps anything in the browser, or builds a profile of a reader.
- In the browser: page views and leaves, and errors that break a page.
- For agents: a count of each request to the docs MCP server, the JSON addresses, the Markdown copies,
llms.txt,llms-full.txtanddocs-map.md. It holds the request's kind, method, status, path, MCP method and tool, and result count, and a coarse class of client, such asclaude-code, never an IP address, a cookie, a search query, a page's text or theUser-Agent. A request refused with429isn't counted.
Marfa itself sends nothing unless its owner names a destination: see Send an instance's telemetry.