# Working with your own AI

Claude, Codex, or any agent that can make web requests can work in
{{name}} for you:

- make new decks, or add and rewrite slides and questions in yours;
- restyle the whole look, or write the CSS for it;
- write slides, phone screens or a whole deck in HTML, with three.js, GSAP
  and more;
- design transitions of its own;
- start a session and move the slides while you talk;
- read what the room answered.

Every change it makes is saved as its own version in the deck's **History**,
so any change to a deck can be undone in one click.

## Connect it

In the app: **Your AI**. Make a key, then pick your agent. The page fills in
your address and key for you. In short:

**Claude Code**

```bash
claude mcp add --scope user --transport http {{slug}} https://YOUR-SITE/mcp --header "Authorization: Bearer YOUR-KEY"
mkdir -p ~/.claude/skills/{{slug}} && curl -s https://YOUR-SITE/api/v1/skill -o ~/.claude/skills/{{slug}}/SKILL.md
```

`--scope user` makes the tools work in every folder you open Claude Code in.

**Claude app**: Settings, Connectors, Add custom connector, address
`https://YOUR-SITE/mcp/t/YOUR-KEY` (the key is inside the address, so keep it private).

**Codex** (the ChatGPT desktop app and the Codex editor extension share its
setup). Codex reads the key from `{{ENV}}_TOKEN` each time it starts, so keep
the `export` line in your shell profile too:

```bash
export {{ENV}}_TOKEN="YOUR-KEY"
codex mcp add {{slug}} --url https://YOUR-SITE/mcp --bearer-token-env-var {{ENV}}_TOKEN
curl -s https://YOUR-SITE/api/v1/skill -o AGENTS.md   # optional: the guide in your project
```

**Cursor, VS Code, Gemini CLI and most other agents** add an MCP server by its
address: `https://YOUR-SITE/mcp`, with the header
`Authorization: Bearer YOUR-KEY`. Where a header cannot be added, use
`https://YOUR-SITE/mcp/t/YOUR-KEY` (keep it private).

**An agent that only makes web requests**: pick **Any other agent** on the
page. The note in step 3 then has your key written in, so it needs nothing
else.

## Asking it

Ask in your own words, the way you would ask an assistant. To tell it what
{{name}} is, paste the note from **Your AI** (step 3) into the same message,
before your request or after it. It says what {{name}} is, how to reach it
and where the guide is, and leaves what to do to your own words. If the note
comes alone, the agent asks you what you want.

The note does not assume you mean a deck you already have. Unless your
request names one, the agent makes a new deck. A deck you name, it changes
only in the ways you ask.

In the editor, **Ask your AI to work on this** gives the same note for that
one deck, with its id and link in it.

## What it reads

| Address | What |
| --- | --- |
| `/api/v1/guide` | The full guide, written for an agent, with your address in it. `?section=` reads one part. |
| `/api/v1/catalog` | Every layout, question type, field, transition and sticker, and the library kit, as JSON. |
| `/api/v1/skill` | The same guide as a Claude Code skill (also works as AGENTS.md). |
| `/api/v1/prompt` | The note from **Your AI**, with a place for your key. |

None of them need a key. They are generated from the code, so they never go
out of date.

## The MCP tools

`get_guide`, `get_catalog`, `get_transitions`, `list_decks`, `organize_deck`, `get_deck`,
`create_deck`, `duplicate_deck`, `patch_deck`, `replace_deck`, `validate_deck`, `add_slide`,
`add_question`, `list_versions`, `restore_version`, `save_image_from_url`,
`import_html_deck`, `upload_deck_file`, `list_deck_files`, `read_deck_file`,
`start_session`, `control_session`, `get_results`.

`get_guide` and `get_catalog` are long (about 50 and 70 KB). Some agents cut
long results short, so each can be read a part at a time: `section` and
`part`. Tools that only read are marked read-only, so agents that ask before
every change can run them without asking.

`create_deck` takes a whole deck in one call, and returns the link that opens
it. `duplicate_deck` copies a deck, with its files, to make something new from
it without touching the original.

`add_question` can also split the results by an earlier answer (`split_by`)
and ask only some people (`only_for`, `everyone_else`). `get_results` gives
those splits group by group. Words on phones can carry a person's name
(`{name|friend}`) or an earlier answer (`{craft}`).

`import_html_deck`, `upload_deck_file`, `list_deck_files` and `read_deck_file`
let it bring in or write full HTML: a whole coded deck, a custom slide, or a
sealed phone screen, each able to import the library kit (three.js, GSAP, more).
`control_session` can `broadcast` a live cue to every phone mid talk. The
[Coded decks](CODED-DECKS.md) guide and the catalog's `kit` list have the
detail.

The guide also tells it what a coded deck works with, so it does not need
to read any code: the shape of each question's live answers, where the
join badge and the reactions sit on the big screen, which keys a deck gets,
that the mouse reaches a coded slide only when the deck turns it on
(`settings.mouse`, or a slide's `stage.mouse`), the sticker pictures, and
what a sealed phone screen cannot do. A phone screen can greet the person by
name (`Room.me.name`), only ever their own, and only while the room shows
it. An answer it sends with a bad word is filtered, and waits for the
presenter, like any other.

Uploading a new version of a coded deck keeps each slide's phone view,
notes and title. So when it changes those in the file, it also patches them
into the deck.

It can design transitions of its own too: keyframes for how each slide
leaves and arrives, pieces that come in one by one, magic move, how phones
arrive. `get_transitions` gives it every built-in in full to start from and
checks a design before it saves one; [the deck format](DECK-FORMAT.md) explains
every field. For anything beyond that (a whole 3D world, a story the camera
flies through), it writes a coded deck, where its own code moves everything.

## The rules it follows

1. It does what you ask, and leaves your other decks as they are.
2. A new deck is built whole and saved in one go.
3. A deck you name is read before it is changed, in small patches. They merge
   with whatever you are doing in the editor at the same moment.
4. If a save is refused, it gets the exact path of each problem. It fixes
   those and tries again.
5. Pictures are copied in with `save_image_from_url`, never linked from
   somebody else's site.
6. It tells you what it made or changed, with the link to open it.

## Keys

- One key per agent. Name them, so you know which is which.
- **Your AI** shows when each key was last used. Remove any you stop using.
- A key works on your decks, files and live sessions, as you do. It can
  never make, list or remove keys, change your account or your password,
  delete for good (a deck, an upload, a session's answers), pair a phone as
  your clicker, link a computer for offline mode, or use the owner's powers.
  Those stay with you, signed in to the app.