<!-- https://stage.app.deskgenie.studio/developers/docs/ -->

# Desk Genie for developers

Desk Genie characters are AI characters with their own voice, personality and limits. Developers can reach them several ways.

| Option | What it does | Status |
|---|---|---|
| [Claude Code plugins](claude-code.md) | The main way to use Desk Genie. A Mac app plugin and a hosted plugin, from VS Code or the terminal. | Private testing |
| [Hosted MCP server](mcp.md) | Any MCP client (VS Code, Cursor, Claude Code) lists characters and talks to them with your access token. | Private testing |
| [Website embed](embed.md) | Put a published character on your own site or Wix page. | Private testing |
| [Mac app MCP server](desktop.md) | The Desk Genie Mac app exposes its own local MCP server for Claude and other local agents. | Preview |
| [Use it from code](sdk.md) | Call the hosted server from your own program with the official MCP client. | Private testing |
| Browser embed API | Programmatic control of an embedded character. | Follows in a later release |

Desk Genie is in private testing. You need an invitation and the access code that came with it. Then [create an access token](tokens.md) and follow the [quickstart](quickstart.md).

For coding agents, the docs are also available as plain text: [`/llms.txt`](/llms.txt) lists every page and [`/llms-full.txt`](/llms-full.txt) has all of them in one file.

---

<!-- https://stage.app.deskgenie.studio/developers/docs/quickstart/ -->

# Quickstart

This takes about five minutes.

1. Accept your invitation, sign in and enter your access code. Your account page shows your tier.
2. Open [Access tokens](/developers/tokens), name a token after the editor you will use, and copy it. It is shown once.
3. Put the token in an environment variable:

    ```bash
    export DESK_GENIE_TOKEN="dg_..."
    ```

4. Connect your MCP client. For Claude Code, the [plugin](claude-code.md) is the simplest way. To add only the MCP server:

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

    The [MCP page](/developers/mcp) has one-click installs for VS Code and Cursor.

5. Ask your agent to list Desk Genie characters, then to say hello to Pip.

---

<!-- https://stage.app.deskgenie.studio/developers/docs/claude-code/ -->

# Claude Code

Claude Code is the main way to use Desk Genie. Two plugins cover the two jobs, and you can install both.

| Plugin | What it does | Needs |
|---|---|---|
| `desk-genie` (Mac app) | Makes your character speak and animate on your Mac while Claude works, and shares the information you choose. Runs the MCP server `desk-genie`. | The Desk Genie Mac app, with Connect to Claude on. No token. |
| `desk-genie-hosted` (hosted) | Lists the characters on the Desk Genie service and talks to them from any computer. Runs the MCP server `desk-genie-hosted`. | An [access token](tokens.md). Each talk counts against your daily limit. |
| `desk-genie-hooks` (optional) | Silent character reactions to Claude Code activity. They animate only and never speak or open the microphone. | The Mac app plugin. |

The two servers have different names on purpose, so Claude Code keeps both. Tools appear under each server's name.

## Claude Code in the terminal

```bash
claude plugin marketplace add https://stage.app.deskgenie.studio/developers/plugins/marketplace.json
export DESK_GENIE_TOKEN="dg_..."
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 plugin install desk-genie-hooks@desk-genie
```

Install only the lines you need. The `server` option defaults to this service's address, so you only set it to use a different one. Claude Code stores the token in your system keychain.

Check the result with `claude mcp list`. `plugin:desk-genie-hosted:desk-genie-hosted` should show as connected. The Mac app server connects while the app is open.

## Claude Code in VS Code

The [Claude Code page](/developers/claude-code) has an install button for each plugin. A button opens Claude Code's install dialog in VS Code, and the hosted plugin asks for your token there. The extension and the command line share the same plugin settings, so the terminal commands above also work in VS Code's terminal. Start a new conversation after installing.

## Update and remove

```bash
claude plugin marketplace update desk-genie
claude plugin uninstall desk-genie-hosted@desk-genie
```

If you installed the Mac app plugin earlier from the preview archive (`desk-genie@desk-genie-local`), keep that one or switch, but do not run both: they register the same `desk-genie` server.

The Mac app plugin and the reactions plugin come from the Desk Genie Mac app preview and are unsigned. See [Mac app MCP server](desktop.md) for what they share and how to pair a client.

---

<!-- https://stage.app.deskgenie.studio/developers/docs/claude-desktop/ -->

# Claude Desktop

Claude Desktop uses extension files that end in `.mcpb`. There are two, and you can install either or both. They have different names, so they never replace each other.

| Extension | What it does | Needs |
|---|---|---|
| Desk Genie (hosted) | Lists the characters on the Desk Genie service and talks to them. Server name `desk-genie-hosted`. | An [access token](tokens.md). Each talk counts against your daily limit. |
| Desk Genie (Mac app) | Makes your character speak and animate on your Mac, and shares information you choose. Server name `desk-genie`. | The Desk Genie Mac app, open, with **Connect to Claude** on. No token. |

!!! warning "Before you start"
    - The files are **unsigned**. Claude Desktop shows a warning when you install them. Install only files you downloaded from this site, and check the SHA-256 in step 2.
    - Never unzip a `.mcpb` file. If your browser unpacked it into a folder, delete the folder and use the fix in [Download problems](#download-problems).
    - Never paste an access token into a chat. Claude Desktop asks for it in the extension's settings and stores it as a sensitive value.

## Install the hosted extension

1. Download `desk-genie-hosted.mcpb` from the [Claude Desktop page](/developers/claude-desktop). The saved file must end in `.mcpb`.
2. Check the file. In Terminal, run `shasum -a 256 ~/Downloads/desk-genie-hosted.mcpb`. The result must match the SHA-256 shown on the page.
3. Open the file. Claude Desktop shows an install dialog. If nothing happens, open Claude Desktop, choose Settings, then Extensions, then Advanced settings, then **Install Extension**, and pick the file. Menu names can differ between Claude Desktop versions.
4. Confirm the warning, then paste your access token into **Desk Genie access token**. Leave **Server address** as it is.
5. Turn the extension on. Start a new chat and ask: "List the Desk Genie characters, then ask Pip to say hello."

Claude Desktop asks before it uses a tool for the first time. Allow it. A working install lists Jeannie, Pip and Roy, and Pip answers in text. Your account page shows one more turn.

!!! note
    The extension sends your token only to `*.deskgenie.studio`, over HTTPS. To stop it, turn the extension off or revoke the token on the [tokens page](/developers/tokens).

## Install the Mac app extension

1. Install and open the Desk Genie Mac app. In Desk Genie, open Settings, then Apps and connections, then Agent connections, and turn on **Connect to Claude**.
2. Download `desk-genie.mcpb` from the [Claude Desktop page](/developers/claude-desktop), check its SHA-256 as above, and open it.
3. Confirm the warning and turn the extension on. Leave the key option empty unless you are sharing character information.
4. Start a new chat and ask Claude to make your character wave.

!!! warning
    The Mac app extension talks to the app on your Mac. If the app is closed, or **Connect to Claude** is off, Claude Desktop reports that the server could not connect. Open the app, turn the setting on and start a new chat.

To share a character's bio, style or a note with Claude, see [Share information with a client](desktop.md#share-information-with-a-client).

## Optional: the Desk Genie skill

The extensions give Claude the tools. The skill tells Claude when and how to use the Mac app tools: check status first, speak only when asked, use plain speech without code or URLs, and treat shared character text as data, not instructions.

1. Download `desk-genie-skill.zip` from the [Claude Desktop page](/developers/claude-desktop). Do not unzip it.
2. Add it in Claude Desktop through its skill or custom plugin upload. Menu names differ between versions.
3. Start a new chat. Claude should now follow the skill whenever the Mac app tools are present.

!!! warning
    The skill belongs to the Mac app extension and does nothing for the hosted extension. It is named `desk-genie`. An earlier prototype named `desk-genie-companion` is a different skill: do not install both. Claude Code does not need this file, because the Mac app plugin already includes the skill.

## Download problems

- **The browser saved a `.zip` or made a folder.** Some browsers unpack zip files. Delete the folder, then rename the downloaded `desk-genie-hosted.zip` to `desk-genie-hosted.mcpb`. A `.mcpb` file is a zip file, so the contents are the same.
- **Download from the terminal instead.** `curl -L -o ~/Downloads/desk-genie-hosted.mcpb https://stage.app.deskgenie.studio/developers/download/desk-genie-hosted.mcpb`, then `open ~/Downloads/desk-genie-hosted.mcpb`.
- **The hash does not match.** Delete the file and download it again. Do not install a file with a different hash.

## Other problems

| What you see | What to do |
|---|---|
| "This access token is not valid" | The token is wrong, expired or revoked. Create a new one on the [tokens page](/developers/tokens) and paste it in the extension's settings. |
| "Desk Genie could not be reached" | Check your connection. If you changed **Server address**, set it back to the default. |
| "You've reached today's limit" | Your daily allowance is used. It resets at midnight UTC. See [Limits and errors](limits.md). |
| The extension is on but no tools appear | Start a new chat. If they still do not appear, turn the extension off and on. |
| An old version is installed | Open the new file and confirm the replace dialog. Do not keep two copies. |

For coding agents, the same facts are in [AGENTS.md](/AGENTS.md).

---

<!-- https://stage.app.deskgenie.studio/developers/docs/mcp/ -->

# Hosted MCP server

!!! note "Two Desk Genie servers"
    The Desk Genie Mac app also runs a local MCP server named `desk-genie`, which speaks and animates your character on your Mac ([Mac app MCP server](desktop.md)). This hosted server is named `desk-genie-hosted` so both can be installed in the same client. Tools from each appear under their own server name. Keep the hosted name when you copy a configuration.

- Address: `https://stage.app.deskgenie.studio/api/mcp`
- Transport: Streamable HTTP. Each POST carries one JSON-RPC message and receives one JSON response. The server does not open event streams.
- Authentication: `Authorization: Bearer dg_...`, an [access token](tokens.md).

## Tools

| Tool | Arguments | Returns |
|---|---|---|
| `list_characters` | none | The characters you can talk to, as `{ id, name }`. |
| `talk` | `character` (an id from `list_characters`), `message` (1 to 4,000 characters) | The character's reply as text. Each call starts a new conversation. |
| `get_usage` | none | Today's turns, voice seconds and cost against your daily limit. |

Each `talk` call is one turn against your daily limit. Spoken replies are not returned over MCP.

## Client configuration

=== "Claude Code"

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

=== "VS Code"

    ```json
    {
      "servers": {
        "desk-genie-hosted": {
          "type": "http",
          "url": "https://stage.app.deskgenie.studio/api/mcp",
          "headers": { "Authorization": "Bearer ${input:desk-genie-token}" }
        }
      },
      "inputs": [
        { "type": "promptString", "id": "desk-genie-token", "description": "Desk Genie access token", "password": true }
      ]
    }
    ```

    VS Code asks for the token when it starts the server. The GitHub Copilot CLI reads the same `mcp.json` but cannot fill in `${input:...}`, so it sends that text as the token and the server answers 401. To use the CLI, replace the header value with `Bearer dg_...` and your token. The file is plaintext, so use a short-lived token and revoke it when you finish.

=== "Claude Desktop"

    Download the hosted extension and follow the [Claude Desktop guide](claude-desktop.md). It covers the install, the unsigned-file warning, the token prompt and download problems.

=== "Cursor"

    ```json
    {
      "mcpServers": {
        "desk-genie-hosted": {
          "url": "https://stage.app.deskgenie.studio/api/mcp",
          "headers": { "Authorization": "Bearer ${env:DESK_GENIE_TOKEN}" }
        }
      }
    }
    ```

The install buttons on the [MCP page](/developers/mcp) write these configurations for you. A request that carries an `Origin` header, which browsers add, is refused unless the origin is Desk Genie's own. No button or link ever contains your token: VS Code asks for it, and Cursor reads it from `DESK_GENIE_TOKEN`.

## Raw requests

```bash
curl -s https://stage.app.deskgenie.studio/api/mcp \
  -H "Authorization: Bearer $DESK_GENIE_TOKEN" -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"talk","arguments":{"character":"pip","message":"Hello"}}}'
```

## Errors

A missing or invalid token returns HTTP 401. A tool that cannot finish, for example at your daily limit, returns a result with `isError: true` and a message to show the user. See [Limits and errors](limits.md).

---

<!-- https://stage.app.deskgenie.studio/developers/docs/tokens/ -->

# Access tokens

An access token lets a program act as you with Desk Genie: list characters, talk to them and read your usage. Talking counts against your daily limit, exactly as on the website.

- Create tokens on the [Access tokens](/developers/tokens) page. You choose a name and a lifetime of 7, 30, 90 or 365 days.
- The token is shown once. Desk Genie stores only a SHA-256 hash of it, so it cannot show it again.
- Tokens start with `dg_`. The page lists each token by its first characters, creation date, expiry and last use.
- Revoking a token takes effect on its next request.
- A token stops working when your access is paused or revoked.

Keep tokens out of source code, shared configuration files and links. Use an environment variable or your editor's secret prompt.

---

<!-- https://stage.app.deskgenie.studio/developers/docs/embed/ -->

# Website embed

A published character runs on your own website or Wix page. It draws the character in 3D, speaks replies aloud and offers Talk and Text buttons.

1. In Desk Genie Studio on the Mac, open the character and choose **Publish to website**.
2. Connect your own Vercel project as the host. Studio uploads a reviewed release with an immutable address.
3. Copy the code Studio shows and paste it into your page. For Wix, use the Wix code, which allows the microphone in its frame.

Characters on the hosted service (Pip, Jeannie and Roy) appear on [stage.app.deskgenie.studio](https://stage.app.deskgenie.studio/talk) for signed-in testers. Hosted publishing from Studio is planned.

---

<!-- https://stage.app.deskgenie.studio/developers/docs/desktop/ -->

# Mac app MCP server

The Desk Genie Mac app runs a local MCP server named `desk-genie`. Claude and other local agents use it to make your character speak and animate on your Mac, and to read the information you choose to share. It runs on your computer and uses your own provider keys.

!!! note "Two Desk Genie servers"
    The [hosted MCP server](mcp.md) is a different server named `desk-genie-hosted`. It talks to characters on the Desk Genie service and needs an [access token](tokens.md), not the Mac app. Use either one, or both in the same client. Tools from each appear under their own server name.

Using the Mac app with your tester account and no provider keys follows in a later release.

## What it does

| Capability | Detail |
|---|---|
| Speak and animate | Your character speaks a reply or plays an animation while Claude works. |
| Share information | Claude reads a character's bio, speaking style and a note you write. Every item starts unchecked for each client. |
| Reviewed notes | You send Claude a note from Desk Genie after reviewing it. Notes and future conversation text each have their own checkbox per client. |
| Reactions (optional) | Silent attention, completion and failure animations from Claude Code. They never speak a tool result or open the microphone. |

## Before you start

1. Install and open the Desk Genie Mac app.
2. In Desk Genie, open Settings, then Apps and connections, then Agent connections, and turn on **Connect to Claude**.

## Install

=== "Claude Code"

    ```bash
    claude plugin marketplace add https://stage.app.deskgenie.studio/developers/plugins/marketplace.json
    claude plugin install desk-genie@desk-genie
    ```

    Start a new conversation and run `/mcp`. The server `desk-genie` should show as connected. The same steps are on the [Claude Code page](claude-code.md), which also covers the hosted plugin.

=== "Claude Code in VS Code"

    1. Open the [Claude Code page](/developers/claude-code) and choose **Install Mac app**.
    2. VS Code opens Claude Code's install dialog. Confirm the install.
    3. Start a new conversation and check that `desk-genie` is connected.

    If the button does nothing, run the two commands from the Claude Code tab in VS Code's terminal.

=== "Claude Desktop"

    Follow the [Claude Desktop guide](claude-desktop.md). It has the downloads, the SHA-256 check, the install steps for the Mac app extension, the optional skill, warnings and fixes for download problems. To share character information, see [Share information with a client](#share-information-with-a-client). The optional skill, `desk-genie-skill.zip`, is on the [Claude Desktop page](/developers/claude-desktop); Claude Desktop takes it through its own skill or custom plugin upload.

## Companion behavior

The current plugin gives Claude the character's tools and the information you share. It does not yet set how often the character animates or speaks while Claude works.

An earlier companion prototype, `desk-genie-companion`, defined that behavior as four modes: off, ambient, milestone and narrator. Milestone was the default. Claude animated once per turn, spoke only when a task finished, failed or needed you, kept speech under 40 words and never spoke a secret aloud. You switched modes in plain language, such as "Genie, go quiet". The modes, an animation map and per-session speech limits follow in a later release. Until then, do not install the prototype next to the current plugin: both would try to steer the same character.

## Share information with a client

1. In Desk Genie, choose the character and open **Share character information**.
2. Write the bio, speaking style and any note you want to share, then save. These are separate from the character's private prompt.
3. Under Agent connections, name the client, choose the fields it may read and create a connection key.
4. Paste the one-time key into the client's sensitive key option. Use a different key for each client, and never put a key in a prompt or a file.

Removing the client in Desk Genie stops future reads. Information the client already read can stay in its conversation.

## Reviewed notes

1. Type the exact note in Desk Genie, choose its recipient and choose **Send reviewed note**.
2. Or say "Tell Claude" followed by a note. Desk Genie opens a review where you choose the recipient, share, edit or cancel.

Claude collects notes by reading the inbox and then acknowledges what it used. Future transcripts need their own grant, are not available in Kids mode, and exclude screen turns and temporary conversations.

## Reactions (optional)

1. Install the hooks plugin: `claude plugin install desk-genie-hooks@desk-genie`.
2. Turn on **Enable silent reactions** in the plugin's options.
3. In Desk Genie, allow silent reactions for the paired client.

Reviewed notes on prompt submit are a separate option, **Add reviewed notes on prompt submit**, and need the inbox grant.

## Update, remove and recover

- Update by replacing the installed extension or plugin. Do not install a second copy, and check `/mcp` again.
- Remove the hooks plugin first to stop its callbacks. Then uninstall the main plugin or extension in Claude and remove its paired row in Desk Genie.
- If you installed the plugin earlier from the preview archive (`desk-genie@desk-genie-local`), keep that one or switch to this one, but not both.
- If Claude cannot find the app, open the installed app, turn on **Connect to Claude** and start a new Claude conversation.
- If a character shows the wrong version, select the character in Desk Genie and let Claude discover its resources again.

The extension and plugin archives are an unsigned preview. The connection stays on your Mac. Desk Genie cannot protect shared information from malware already running as your Mac user account.

---

<!-- https://stage.app.deskgenie.studio/developers/docs/sdk/ -->

# Use Desk Genie from code

Any program can reach Desk Genie characters through the [hosted MCP server](mcp.md). The official MCP client libraries handle the protocol, and your [access token](tokens.md) is the only credential.

## TypeScript

```bash
npm install @modelcontextprotocol/sdk
export DESK_GENIE_TOKEN="dg_..."
```

```typescript
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const client = new Client({ name: "my-app", version: "1.0.0" });  // the server reports itself as desk-genie-hosted
await client.connect(new StreamableHTTPClientTransport(
  new URL("https://stage.app.deskgenie.studio/api/mcp"),
  { requestInit: { headers: { Authorization: `Bearer ${process.env.DESK_GENIE_TOKEN}` } } },
));

const { tools } = await client.listTools();            // list_characters, talk, get_usage
const reply = await client.callTool({
  name: "talk",
  arguments: { character: "pip", message: "In one sentence, what do you help with?" },
});
console.log(reply.isError ? "Not sent:" : "Pip:", reply.content[0].text);
await client.close();
```

The hosted server answers every POST with one JSON response and opens no event streams, so the client needs no long-lived connection.

## Other languages

Use that language's MCP client with the Streamable HTTP transport and an `Authorization: Bearer` header. Without a library, each call is one HTTPS POST of a JSON-RPC message; the [MCP page](mcp.md) shows a `curl` example.

## What to handle

- A missing, expired or revoked token returns HTTP 401. A session already open when you revoke a token ends on its next request.
- A call that cannot finish, such as one at your daily limit, returns `isError: true` and a message you can show. See [Limits and errors](limits.md).
- A request from a web page carries an `Origin` header. The server refuses any origin that is not Desk Genie's own, so call it from a server or a local program, not from a browser page.
- `talk` starts a new conversation each time, and each call counts as a turn.

## Browser control

A browser API to place, speak through and animate an embedded character follows in a later release. Today the [website embed](embed.md) gives you the character with Talk and Text buttons.

---

<!-- https://stage.app.deskgenie.studio/developers/docs/limits/ -->

# Limits and errors

Every account has daily limits, reset at midnight UTC.

| Tier | Turns | Voice minutes | Dollars |
|---|---|---|---|
| Alpha tester | 40 | 20 | 3 |
| Investor preview | 60 | 30 | 5 |
| Source personality | 100 | 45 | 8 |

Desk Genie may set a different limit for your account; your account page shows the one that applies. A turn already in progress holds up to $0.45 and 114 voice seconds of your allowance until it finishes, so a turn can be refused when less than that remains. At 80% the website shows a notice. At 100%, talking pauses until midnight UTC.

Each conversation allows 20 turns and lasts at most 30 minutes.

| Message | Meaning |
|---|---|
| You’ve reached today’s limit. | Your daily allowance is used. |
| Talking is paused for everyone for the rest of today. | The service reached its daily ceiling. |
| This account does not have tester access yet. | Accept your invitation and enter your access code. |
| Your access is paused. | Desk Genie paused or revoked your account. |
| This access token is not valid. | The token is wrong, expired or revoked. |