# Docs MCP server (/reference/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](/use/from-an-agent) shows.

## Connect the docs MCP server [#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 Code**

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

**Codex**

```bash
codex mcp add marfa-docs --url https://docs.marfa.so/mcp
```

The server is written to `~/.codex/config.toml`, under `[mcp_servers.marfa-docs]`.

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 [#search-from-a-terminal]

`marfa docs` reads this site from the [CLI](/reference/cli), for an agent that runs shell commands. It refuses `--url`, `--key` and `--socket`, so it can't send a credential anywhere.

```bash
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:

```bash
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](/reference/cli#exit-codes) lists them all. To read another copy of the site, set `MARFA_DOCS_URL`.

## Read a page as Markdown [#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.

```bash
curl -H "Accept: text/markdown" https://docs.marfa.so/quickstart
```

Output:

```text
# 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`](/llms.txt) | A summary of Marfa, then every page as the sidebar groups them, each linked to its Markdown copy |
| [`/docs-map.md`](/docs-map.md) | The same index, with links to the HTML pages |
| [`/llms-full.txt`](/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`](/changelog.md).

## Search over HTTP [#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 [#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](/run/telemetry).
