---
title: "Working with an AI agent"
description: "An MCP server that answers from your actual build, and the AGENTS.md written into every project."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.rsc-kit.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Working with an AI agent

Two things ship for this, and they do different jobs.

`AGENTS.md` is written into your project by the scaffold. It is short on
purpose — it sits in an agent's context on every turn, so it states the rules
and nothing more.

The **MCP server** is for everything that does not fit in that budget: what your
build actually did, and the long-form answer to "how do I do X here".

## Connecting it

The scaffold already did. Every project gets a `.mcp.json` at its root:

```json title=".mcp.json"
{
  "mcpServers": {
"rsc-kit": { "command": "npx", "args": ["-y", "@rsc-kit/mcp"] }
  }
}
```

Claude Code reads that as project-scoped configuration and asks you to approve
it the first time it starts the server. Nothing is installed until then, and
nothing about your build or dev server changes — it is a file an agent reads.
Commit it; it is the same for everyone on the project.

For a project that predates the file, `create-rsc-kit init` writes it (and
leaves one that is already there alone), or add it by hand:

```sh
claude mcp add rsc-kit -- npx -y @rsc-kit/mcp
```

Any other MCP client takes the same entry — a stdio server, command `npx`,
arguments `-y @rsc-kit/mcp` — in its own file: `.cursor/mcp.json` under
`mcpServers`, `.vscode/mcp.json` under `servers`.

## What it answers about your app

Every build writes `build-report.json` — the same rows it printed, plus every
server action and whether a client built it. These read
it, so nothing runs a build or imports your code:

| tool | answers |
| --- | --- |
| `list_routes` | every route, what happened to it, what it ships |
| `explain_route` | why one url is stored or rendered per request |
| `what_is_dynamic` | the routes that are not stored, with reasons |
| `heaviest_routes` | what costs the browser most |

The reason a page is dynamic is **recorded, not guessed**:

```
/locale — a stored shell, with the rest rendered per request (from the last build, 5 minutes ago)
Rendered by app/locale/page.
Ships 85 kB of javascript, gzipped.

Why it is not stored whole: dynamic — called cookies(), headers()
```

That matters more than it sounds. Asked to "make this page faster", an agent
without this guesses at a cause and edits something. With it, the call that did
it is on the screen.

## What it answers about the framework

| tool | answers |
| --- | --- |
| `list_topics` | every topic it can explain |
| `how_to` | the short answer: forms, prefetch, validation, the action client, data with TanStack Query or SWR, Suspense, offline, pwa, no-javascript, api routes, authorization, why a page is dynamic |
| `list_guides` | every guide on this site, one line each |
| `read_guide` | the full text of one, exactly as published here — bundled with the server, so it matches the version installed |
| `search_guides` | every line in the guides mentioning a word, with the guide it is in |

`how_to` is the opinionated summary an agent should read first; `read_guide`
is for when the summary is not enough. Both come from the same source, and the
guides are copied in at build time, so what an agent reads is what this site
says for the version it has.

These exist because the patterns here differ from Next and plain React **in
ways that compile either way** — a check written in the component instead of the
action, a hand-parsed query string, `"use server"` at the top of a page. An
agent that has not been told writes those confidently.

## Two things worth knowing

**Every answer says how old it is.** It reports the last build, and your files
may have changed since — so `(from the last build, 5 minutes ago)` is on every
response. With no build at all it says to run one, rather than reporting that
there are no routes.

**It is read-only.** Nothing here edits, builds or deploys. Your agent already
has a shell for those, and a server that can change a project is one that can
change it while answering a question about it.

## The docs are markdown too

Every page on this site is also a markdown file at the same url with
`index.md` added — `/guides/forms/index.md` — and
[`/llms.txt`](/llms.txt) is an index of all of them, with
[`/llms-full.txt`](/llms-full.txt) as one document. An agent without the MCP
server, or one asked about a version other than the one installed, reads
those. `read_guide` is the same text, offline, at the installed version.

## Without an agent

`build-report.json` is an ordinary file. A CI step can assert on it — that
nothing stopped being prerendered, that no route crossed a size budget — which
is the check most likely to catch a regression nobody would otherwise see.

Source: https://docs.rsc-kit.dev/guides/mcp/index.mdx