# Docs for agents

URL: /start/docs-for-agents · Id: `page:start/docs-for-agents`

> How an agent reads these docs through the docs MCP server's three tools, /llms.txt, /asks.json and every page's Markdown twin.

An [Agent](/business/nouns/agent) reads these docs through the docs MCP server, [/llms.txt](/llms.txt), [/asks.json](/asks.json) and each page's Markdown twin, all read-only and keyless. Acting on a [Startup](/business/nouns/startup) goes through the MCP server of [api.sb](/code/platform/api-sb) instead.

## Connect
```bash
claude mcp add --transport http startupbuilder-docs https://startupbuilder.dev/mcp
```

Any MCP client that speaks streamable HTTP connects to `https://startupbuilder.dev/mcp`. The server holds no session: each `POST` carries one JSON-RPC message, or a batch, and gets JSON back. A notification gets `202`, and `GET` and `DELETE` get `405`, since the server never pushes.

It answers protocol `2025-06-18`, and `2025-03-26` or `2024-11-05` when a client asks for one.

`initialize` returns the server's instructions: use `guides` for what a founder asks, `search` for anything else, and `fetch` to read a page. Four rules follow, the same four that open /llms.txt and /asks.json:

```text
1. Offer only guides whose status is `live` or `beta`; say a `planned` one is planned.
2. Match the founder's words in [/asks.json](/asks.json), then call the guide's Verbs in order, with the founder's own values in place of each input its `examples` names; `find:` reads the record first, `$N` is step N's result.
3. Ask at most the plan’s one question, and stop at every exit and approval the guide declares.
4. Read any page as Markdown at its URL plus `.md`, and cite its id.
```

## Tools
| Tool | Takes | Returns |
| --- | --- | --- |
| `search` | `query` (string, required): The words to look for, such as "charge monthly" or "Offer".<br />`limit` (integer, optional, default 8, at most 20): How many results to return. | Up to `limit` results, each a guide (id, title, status, Markdown URL), a System (id, name, status, Markdown URL) or a page or heading (title, URL, Markdown URL). |
| `fetch` | `id` (string, or `url`): A page id, as pages and `/asks.json` cite them.<br />`url` (string, or `id`): A page URL or path on startupbuilder.dev. | The page's Markdown, with its URL and its Markdown URL. |
| `guides` | `phrase` (string, required): The founder's words.<br />`limit` (integer, optional, default 3, at most 10): How many guides to return. | Up to `limit` guides, best first, each with its score, Verbs, needs, approval, status and calls; or none, with a pointer to `search`. |

Every result names a Markdown URL that `fetch` returns, so an agent searches, then reads.

- `search` ranks a task guide that holds every word of the query first. A [System](/business/nouns/system) whose founder sentences hold them follows, then pages and headings.
- `fetch` takes a page id or a URL. An id names the record a page documents, such as `noun:offer`, `verb:Offer.create`, `system:billing` or `guide:charge-monthly`. Any other page is `page:` and its path, such as `page:code/mcp`.
- `guides` takes the founder's words and returns the closest guides, front shelf first among close matches.

## Find the guide for a request
A founder says "retry the payments that failed", and the agent calls `guides` with those words:

```json
{ "jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": { "name": "guides", "arguments": { "phrase": "retry the payments that failed", "limit": 1 } } }
```

The first guide is `retry-failed-payments`, shortened here:

```json
{
  "kind": "guide",
  "id": "retry-failed-payments",
  "title": "Retry the payments that failed",
  "status": "live",
  "shelf": "wakes",
  "program": ["Invoice.collect"],
  "needs": ["verb:Startup.claim", "guide:charge-monthly"],
  "approval": "mandate",
  "leaves": [],
  "wakesOn": { "event": "Invoice.overdue", "where": "a renewal payment failed", "first": true },
  "md": "/systems/finance/retry-failed-payments.md"
}
```

Each field tells the agent what to do:

- `program` lists the [Verbs](/business/nouns/verb) to call, in order. `calls` holds the same program as the founder's words, an MCP `do` call and API requests.
- `needs` lists what must exist first, each typed: another guide, a Verb, a [Noun](/business/nouns/noun), a System, a [Capability](/business/nouns/capability) or a [Process](/business/nouns/process).
- `approval` says who says yes first: `none`, `ask` (the founder approves each run) or `mandate` (an agent acts within a standing [Mandate](/business/nouns/mandate) and its [Limit](/business/nouns/limit)).
- `leaves` names each point where the founder leaves the chat: `stripe-onboarding`, `registrar` or `oauth`.
- `shelf` says when to offer it. A `front` guide belongs to the first 90 days of an idea-stage Startup. A `wakes` guide waits for its `wakesOn` [Event](/business/nouns/event) in the Startup's own records, and a `reference` guide for the founder to ask.

[/asks.json](/asks.json) holds every public guide in this shape, plus each step's inputs, its plans per [Lifecycle](/business/nouns/lifecycle) state, its follow-up asks and its calls. Its `systems` list adds what a founder says to reach each System, so a sentence with no guide still finds its System. [/asks.txt](/asks.txt) is the same file as plain text.

An input naming a record an earlier step returns reads `$1.$id`, the `$id` step 1 returns, never a hard-coded id. The calls pass it on: `offer.$id` in the SDK and MCP, `$OFFER` read with `jq` in the API and CLI.

An input naming a record that exists before the guide runs reads `find:`: `find:site` is the Startup's own [Site](/business/nouns/site), and `find:lead where status = new` the first new [Lead](/business/nouns/lead). The calls list it first, `$.Site.list({ limit: 1 })`, and pass its `$id` on. Any other id is a record the founder names, such as the [Approval](/business/nouns/approval) they ask about: read its id before the call.

## Read any page as Markdown
Every page reads as Markdown at its URL plus `.md`: `/business/nouns/offer` is `/business/nouns/offer.md`, and the home page is `/index.md`. A request to the page's own URL with `Accept: text/markdown` gets the same twin.

A twin opens with the page's title, its URL, its id and its description, then its body with every generated table in place. A Verb's twin also says how to call it and, last, the Verbs that follow it in a guide. Each code window's tabs read as labelled blocks: **Ask**, **API**, **SDK**, **CLI**, **MCP**.

A URL with no page answers `404` in Markdown, with the closest pages listed.

A guide page's twin spells out each section: what it needs, what you get, the calls in each [Interface](/business/nouns/interface), follow-up asks and what runs underneath. A block under the lead names who approves the run and where it leaves the chat.

Above its calls, the twin's agent block lists each Verb with every input it takes, its type and the guide's value. Then it shows what the last call returns and what to offer next.

[/ids.json](/ids.json) maps every page id to its URL, so an agent that holds `system:billing` reads `/systems/billing.md` without a search. An id outlives a move: it names the record, and the old URL answers with a `301` to the new one.

## The site map
[/llms.txt](/llms.txt) is the map, under 2,000 tokens. Its first lines say how to use this server, /asks.json and the twins, then give the four rules above. What [StartupBuilder](/code/builders/startup) builds and where to start come next, then one section per header tab with that tab's core pages.

Its last section links each tab's full file, such as `/code/llms.txt`, and [/llms-full.txt](/llms-full.txt), every page in one file. It leaves out the generated operation and Event pages, which `/openapi.json` and `/startup-builder.d.ts` hold. An agent that writes code reads `/openapi.json` for the API and `/startup-builder.d.ts` for the SDK's types.

## Cite and trust what you read
Cite a page by its id, such as `guide:charge-monthly`, and quote the founder the sentence it holds. An answer that names its id lets the founder, or the next agent, read the same page.

Every page, /llms.txt, /asks.json and this server come from one build of one registry. A guide's Verbs, its status and its page therefore never disagree, and a guide that changes changes everywhere at once.

Every code block passes the example verifier before the site builds. Each SDK call, MCP program, CLI command and JSON body names only Verbs, fields and values the registry defines. An example copied from a page runs against [api.sb](/code/platform/api-sb).

What changed since your last read is in the [Changelog](/changelog).

## Next
- [What you can ask for](/start/what-you-can-ask-for) lists every System by the sentence that reaches it.
- [Connect an agent](/code/mcp/guides/connect-an-agent) to a Startup's own MCP server, which acts.
- [Guides](/start/guides) lists every task guide by the sentence a founder says.