# MCP server

URL: https://www.atmee.ai/docs/v2/agents/mcp-server

> Every tool the Atmee MCP server offers, how it signs you in, how paid calls are confirmed, and how to keep it safe.

The Atmee MCP server gives an agent the tools to make and change avatars, take your uploads,
generate portraits and voices, and run conversations. Its address:

```text
https://api.atmanity.us/mcp
```

The plugin connects it for you; to connect another client, see
[Install](/docs/v2/agents/mcp-server/install).

## Frequently used tools

Ask in your own words; the agent picks the tool. For example:

- `create_avatar`: "Make a receptionist avatar for our dental clinic from this photo and voice clip."
- `list_avatars`: "Which of my avatars are ready to talk?"
- `update_avatar`: "Have the product guide greet visitors in Spanish and mention the spring sale."
- `create_upload`: "I have the photo on my phone. How do I get it to you?"
- `get_balance`: "How many credits do I have left?"

## All tools

Tools marked **Paid** spend credits, **Per minute** start a session billed while it runs, and
**Moves credits** move credits between your account and an avatar. Every one of them asks you
first ([Paid calls](#paid-calls)).

### Account and balance

| Tool | What it does |
| --- | --- |
| `get_account` | Your plan, limits, prices and whether the account has v2 access. |
| `get_balance` | The credits you have to spend. |
| `get_earnings` | What your monetized avatars have earned. |
| `redeem_code` | Redeem a code, such as an invite that unlocks Atmee V2. |
| `get_api_key` | Who this connection acts as: you, or an API key and its limits. |

### Avatars

| Tool | What it does |
| --- | --- |
| `create_avatar` | Make an avatar from a name, a portrait and a voice sample. |
| `list_avatars` | List your avatars and their status. |
| `get_avatar` | One avatar's details, build progress and links. |
| `wait_for_avatar` | Wait until an avatar is ready, or needs you. |
| `update_avatar` | Change the name, persona, language, visibility or share card. |
| `delete_avatar` | Delete an avatar (asks first). |
| `replace_appearance` | Give the avatar a new portrait. |
| `replace_voice` | Give the avatar a new voice sample. |
| `replace_knowledge` | Replace the documents the avatar knows. |
| `replace_thumbnail` | Set the image on the avatar's Explore card. |
| `remove_thumbnail` | Remove the Explore card image (asks first). |
| `get_appearance` | A link to the current portrait. |
| `get_voice` | A link to the current voice sample. |
| `get_knowledge` | The avatar's facts, questionnaire and documents. |
| `get_monetization` | Whether the avatar can earn, and what it has earned. |

### Uploads

When you have a file the agent can't send by link, a photo on your phone or a recording on your
computer, the agent gives you an upload page. Open it, choose the file (or record your voice in the
browser), and the agent notices when it arrives.

| Tool | What it does |
| --- | --- |
| `create_upload` | A link where you upload a photo, recording or document for the agent. |
| `wait_for_upload` | Wait until your file arrives on the upload page. |
| `get_upload` | Check whether an upload has arrived. |

### Candidates and versions (v2)

A v2 avatar is made of takes: short talking clips, each with its own lip sync. You pick the one
the avatar uses. v2 is invite-only for now: `get_account` says whether your account has access,
and without it these tools answer `v2_access_required`. Give the agent your invite code and it
redeems it with `redeem_code`, or redeem it on the
[API page in Studio](https://www.atmee.ai/studio/api-keys). Without one, make a v1 avatar.

| Tool | What it does |
| --- | --- |
| `list_candidates` | The takes of a v2 avatar, each with a short talking preview. |
| `add_candidates` | Capture more takes to choose from. |
| `select_candidate` | Pick the take the avatar uses, or go back to an older one. |
| `delete_avatar_version` | Delete an older version for good (asks first). |

### Portraits, voices and clips

For an invented character, a photo that needs help, or a short video clip. The same v2 access
applies.

| Tool | What it does |
| --- | --- |
| `generate_portraits` | Portraits of an invented character from a description. (Paid) |
| `enhance_portrait` | Clean up or restyle your own photo. (Paid) |
| `design_voice` | Voice samples from a description of how it should sound. (Paid) |
| `generate_clip` | A video clip of up to 15 seconds from an image and a prompt. (Paid) |

### Sessions

| Tool | What it does |
| --- | --- |
| `start_session` | Start a conversation in a LiveKit room for your app. (Per minute) |
| `start_avatar_session` | Render the avatar into your own LiveKit room for your agent. (Per minute) |
| `get_avatar_session` | A session's state, why it ended and what it cost. |
| `end_session` | End a conversation now. |
| `end_avatar_session` | End a render session now. |
| `start_speech_session` | Start a voice-only conversation, with no video. (Per minute) |
| `get_speech_session` | A voice-only session's state, why it ended and what it cost. |
| `end_speech_session` | End a voice-only session now. |

### Conductor (v2)

| Tool | What it does |
| --- | --- |
| `set_conductor` | Give conversations an agenda: steps and when to move on. |
| `get_conductor` | Read the avatar's agenda. |
| `delete_conductor` | Remove the agenda (asks first). |

### Sponsoring

| Tool | What it does |
| --- | --- |
| `get_sponsor` | The avatar's sponsor pool and settings (API key only). |
| `update_sponsor` | Change sponsor settings (API key only). |
| `grant_sponsor` | Move credits into the avatar's pool (asks first). (Moves credits) |
| `withdraw_sponsor` | Move unused credits back to the account (asks first). (Moves credits) |

### API keys

| Tool | What it does |
| --- | --- |
| `list_api_keys` | The account's API keys. |
| `create_api_key` | Create a key for your app; the secret never enters the chat. |
| `update_api_key` | Change a key's name, scopes, avatar or caps (asks first). |
| `revoke_api_key` | Revoke a key for good (asks first). |

## Sign in

**OAuth.** The first time a client connects, it opens the "Connect an app to Atmee" page on
atmee.ai. Sign in and allow access; the client then acts as you, on your account.

**Several accounts.** If your login belongs to more than one account, tools answer
`account_ambiguous` with the list, and the agent asks you which one to use.

**API keys.** Clients that can't sign in send an API key in `X-Api-Key` instead. A key acts for
the account with only the scopes you gave it, so it can't manage keys or do what its scopes
don't allow. Give it the narrowest scopes, one avatar when it serves one, and a spend cap. See
[API keys](/docs/v2/api/api-keys).

## Paid calls

A tool that spends or moves credits, or deletes something, refuses to run until the agent passes
`confirm: true`. Before that, the agent tells you what the call costs and your balance, and waits
for your yes. Generation tools also take a `requestId`, so a retried call is never charged twice.

Prices are on the [pricing page](https://www.atmee.ai/pricing), and `get_account` returns the
current ones for your plan.

## Safety

* **Prompt injection.** When this server runs beside others, text from another tool (a web page,
  an email, a file) can try to instruct your agent. Keep paid and destructive actions behind a
  confirmation, and read what the agent asks you to approve.
* **Tool approval.** Leave your client's approval prompts on for tools that change or delete
  things, or spend credits.
* **Revoke an agent.** Every agent you've signed in is listed under **Connected agents** in your
  [account settings](https://www.atmee.ai/studio/account), the CLI included (as "Atmee CLI").
  Revoke stops it from signing in again, but access it already holds keeps working until it
  expires, at most an hour.
* **Keys outlive the agent.** Revoking an agent leaves any API key it created or used. Revoke those
  on the [API keys page](https://www.atmee.ai/studio/api-keys). `atmee logout` only removes the
  CLI's sign-in from that computer.