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:

ToolInputAnswer
docs_searchquery, and an optional limit from 1 to 50The pages that match, best first, each with its title, path and snippets. Passages and links, never a written answer
docs_fetchpath, such as /files, and an optional sectionThe page as Markdown, or only the part under the heading section names
docs_list_topicsNoneEvery 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 1

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

Terminal
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:

FileWhat it holds
/llms.txtA summary of Marfa, then every page as the sidebar groups them, each linked to its Markdown copy
/docs-map.mdThe same index, with links to the HTML pages
/llms-full.txtEvery 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 its title, its path in url, and snippets. A blank q or a limit outside 1 to 50 answers 400, with invalid_query or invalid_limit in error. Each IP address may search 60 times a minute.
  • GET /api/docs/topics answers { "pages": [...] }, each with its title, url, description and breadcrumbs.

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.txt and docs-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 as claude-code, never an IP address, a cookie, a search query, a page's text or the User-Agent. A request refused with 429 isn't counted.

Marfa itself sends nothing unless its owner names a destination: see Send an instance's telemetry.

On this page