# Desk Genie: instructions for coding agents

Desk Genie has AI characters (Pip, Jeannie, Roy) with voices and personalities. You reach them through two MCP servers that can run side by side. Read this file before you configure or call either one.

## The two servers

| Server name | What it is | Needs |
|---|---|---|
| `desk-genie-hosted` | The Desk Genie service at https://stage.app.deskgenie.studio/api/mcp. Tools: `list_characters`, `talk`, `get_usage`. | An access token that starts with `dg_`. |
| `desk-genie` | The Mac app's local server. Makes the user's character speak and animate on their Mac and shares information the user chose. | The Desk Genie Mac app, open, with Connect to Claude on. |

Never register the hosted server under the name `desk-genie`. That name belongs to the Mac app server, and clients report a conflict.

## Install for the user

Claude Code, plugins (preferred):

```bash
claude plugin marketplace add https://stage.app.deskgenie.studio/developers/plugins/marketplace.json
claude plugin install desk-genie-hosted@desk-genie --config token="$DESK_GENIE_TOKEN" --config server=https://stage.app.deskgenie.studio/api/mcp
claude plugin install desk-genie@desk-genie
```

Claude Code, hosted server only:

```bash
claude mcp add --transport http --scope user desk-genie-hosted https://stage.app.deskgenie.studio/api/mcp \
  --header "Authorization: Bearer $DESK_GENIE_TOKEN"
```

Claude Desktop uses `.mcpb` files from https://stage.app.deskgenie.studio/developers/claude-desktop. VS Code, Cursor and other clients are on https://stage.app.deskgenie.studio/developers/mcp. Full docs: https://stage.app.deskgenie.studio/developers/docs/ and https://stage.app.deskgenie.studio/llms-full.txt.

## Rules

- The user creates the token at https://stage.app.deskgenie.studio/developers/tokens. It is shown once. Read it from the `DESK_GENIE_TOKEN` environment variable. Never ask the user to paste it into chat, and never write it to a file you commit or a log.
- `talk` starts a new conversation each time and counts as a turn against the user's daily limit (alpha testers: 40 turns, 20 voice minutes, $3). Call it only when the user asks. `get_usage` is free.
- A token request from a web page is refused (the server rejects an untrusted `Origin`). Call the server from a local program, not from browser code.
- An answer with `isError: true` is a message for the user, for example the daily limit. Show it. Do not retry in a loop.
- Do not install the earlier `desk-genie-companion` prototype next to the shipped plugin. Both would steer the same character.

## Check your work

Run `claude mcp list`. `desk-genie-hosted` (or `plugin:desk-genie-hosted:desk-genie-hosted`) must show connected. Then call `list_characters`. It returns Jeannie, Pip and Roy.