---
title: Technical specs for agents
description: Dense build, runtime, and protocol specs written for agents that work with Charming.
sidebar:
  order: 1
---

These specs are written for agents and client implementers. You can read them, but they are dense and assume the reader can call MCP tools or make HTTP requests.

## Protocol references

- [REST API reference](/docs/reference): the OpenAPI contract rendered by operation.
- [MCP reference](/docs/technical-reference/mcp): the generated standard and ChatGPT MCP contracts, including every tool, prompt, resource, and schema.
- [Browser runtime API](/docs/technical-reference/browser-runtime): every app-author method and property on `window.charming`.
- [Authentication](/docs/technical-reference/authentication): token scopes, pairing, claims, recovery, and revocation.
- [External files and CSP](/docs/technical-reference/external-files-and-csp): uploaded files, remote origins, browser policy, and unsupported resource types.

## Task prompts

- Building a new app? Read [Build your first app with Charming](/docs/prompts/build-your-first-app).
- Working with an app that already exists? Read [Use a Charming app](/docs/prompts/use-an-existing-app).
- Building or changing an app's interface? Read [Charming design guide](/docs/prompts/design-an-app).
- Using a browser library? Read [Use JavaScript modules and libraries](/docs/guides/javascript-libraries).
- Keeping an app and its agent in sync? Read [Apps that work with their agent](/docs/guides/agent-connected-apps).

## Read docs through MCP

An agent connected to Charming can read public documentation with `read_docs`, using the same authenticated MCP connection as the app tools. It needs no browser access or second connector. The server reads from the same docs origin as this site; app data and source are still read through `query_app` and `get_app_source`.

1. The MCP client discovers `read_docs` through `tools/list`. Its description tells the agent when to use it. Connecting does not put the full docs into the agent's context; the agent calls the tool when it needs a reference.
2. Call `read_docs({})` to get the docs index. An empty `path` also opens the index. Choose a relevant page from its links. If the page path is already known, skip the index.
3. Pass the portion after `/docs/`, such as `read_docs({ path: "capabilities/data-storage.md" })`. A copied path with the `docs/` prefix also works. Do not pass the full URL, query string, or fragment. A page slug without `.md` also works.
4. Read the returned `markdown`. The response also includes the normalized `path`, canonical `url`, and `next_offset`. Each chunk contains at most 20,000 characters. When `next_offset` is not null, call again with the returned `path` and that value as `offset`; continue until it is null.
5. Apply the guidance, then use the app tools to complete the task. Reading docs does not create or change an app.

For example, an agent building a new app can read `build-mcp.md`, then `prompts/design-an-app.md`, before calling `create_app`. `llms-full.txt` is the full authoring reference. The existing `charming:app-guide` and `charming:design-guide` MCP prompts remain available in clients that support prompts; `read_docs` also works in clients that expose only tools. It reads an index or a page, rather than searching the docs by keyword.

Failed reads return `isError: true` with a stable error kind:

| Kind | Recovery |
| --- | --- |
| `invalid_request` | Use a doc path without a URL, query, or fragment. If the offset exceeds the document length, restart at offset 0. |
| `not_found` | Read the index again and choose an available page. |
| `operation_failed` | The docs could not be read. Retry shortly; do not guess what the missing page says. |
| `rate_limited` | Wait briefly, then retry. Each server process permits 60 reads per authenticated caller per minute. |

Reads time out after ten seconds and reject redirects and HTML responses. Each chunk fetches the current page and counts as one read, so a docs deployment between calls can shift offsets; restart at 0 if the content no longer lines up.

Found a bug or need a feature? [Tell us](/docs/capabilities/feedback) with `submit_feedback` or `POST /app/{id}/feedback`. Your feedback shapes what we build next.