> ## Documentation Index
> Fetch the complete documentation index at: https://docs.useanima.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Server

> Connect Anima to Claude Desktop, Cursor, VS Code, and other MCP clients via Model Context Protocol.

# MCP Server

Anima exposes its platform via the [Model Context Protocol](https://modelcontextprotocol.io) (MCP), giving AI assistants direct access to agent email, inboxes, vault, phone, voice calls, and more.

There are two ways to connect:

| | Endpoint / package | Tools | Best for |
| - | - | - | - |
| **Hosted (recommended)** | `https://mcp.useanima.sh/mcp` | 65 — the full surface, always current (includes inbox management) | Nothing to install or keep updated; native HTTP clients |
| **Local (stdio)** | [`@anima-labs/mcp`](https://www.npmjs.com/package/@anima-labs/mcp) via `npx` | 53 core tools | Clients without remote-MCP support; pinned/air-gapped configs |

## Quick Start

### Option A: Hosted (remote)

Point any client with remote-MCP support at the hosted endpoint and authenticate with your API key as a Bearer token:

```
https://mcp.useanima.sh/mcp
Authorization: Bearer ak_...
```

### Option B: Local (stdio)

Run the server locally via `npx`:

```bash theme={null}
ANIMA_API_KEY=ak_... npx -y @anima-labs/mcp
```

By default every tool group is registered. Use `--tools` to load a subset — fewer tools can improve the model's tool selection and reduce token usage:

```bash theme={null}
npx -y @anima-labs/mcp --tools=email,vault,phone
```

## Configuration

### CLI Setup (all clients)

The [Anima CLI](/install) auto-configures every detected MCP client (Claude Desktop, Claude Code, Cursor, Windsurf, VS Code):

```bash theme={null}
# Configure all detected clients (hosted gateway — the default)
anima setup-mcp install --all

# Use the local stdio server instead
anima setup-mcp install --all --mode stdio

# Check what got written, then validate it
anima setup-mcp status
anima setup-mcp verify --ping
```

### Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

**Hosted (remote via mcp-remote bridge):**

```json theme={null}
{
  "mcpServers": {
    "anima": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://mcp.useanima.sh/mcp",
        "--header", "Authorization:${ANIMA_TOKEN}"
      ],
      "env": {
        "ANIMA_TOKEN": "Bearer ak_..."
      }
    }
  }
}
```

**Local (stdio):**

```json theme={null}
{
  "mcpServers": {
    "anima": {
      "command": "npx",
      "args": ["-y", "@anima-labs/mcp"],
      "env": {
        "ANIMA_API_KEY": "ak_..."
      }
    }
  }
}
```

### Cursor

**Hosted (native HTTP):**

```json theme={null}
{
  "mcpServers": {
    "anima": {
      "url": "https://mcp.useanima.sh/mcp",
      "headers": {
        "Authorization": "Bearer ak_..."
      }
    }
  }
}
```

### Claude Code

```bash theme={null}
# Hosted
claude mcp add anima --transport http \
  --url https://mcp.useanima.sh/mcp \
  --header "Authorization: Bearer ak_..."

# Local
claude mcp add anima --env ANIMA_API_KEY=ak_... -- npx -y @anima-labs/mcp
```

### VS Code

Add to your user `mcp.json` (Command Palette → **MCP: Open User Configuration**):

```json theme={null}
{
  "servers": {
    "anima": {
      "type": "http",
      "url": "https://mcp.useanima.sh/mcp",
      "headers": {
        "Authorization": "Bearer ${input:anima-key}"
      }
    }
  },
  "inputs": [
    {
      "id": "anima-key",
      "type": "promptString",
      "description": "Anima API Key",
      "password": true
    }
  ]
}
```

## Environment Variables (stdio)

| Variable | Required | Description |
| - | - | - |
| `ANIMA_API_KEY` | Yes | Agent API key (`ak_...`) |
| `ANIMA_MASTER_KEY` | No | Master key (`mk_...`) — unlocks admin tools |
| `ANIMA_API_URL` | No | API base URL (defaults to `https://api.useanima.sh`) |

## Tool Groups

All groups load by default; pass `--tools=<group,...>` to the stdio server to load a subset.

| Group | Covers |
| - | - |
| `workspace` | Account overview and usage rollups |
| `agent` | Agent CRUD and address/identity management |
| `email` | Email send/receive, threads, drafts, attachments |
| `domain` | Custom sending domains: DNS, verification, zone files |
| `phone` | Phone number provisioning and release |
| `phone_call` | Outbound calls, transcripts, recordings, voices |
| `sms` | SMS/MMS send and conversation history |
| `vault` | Credential vault management and TOTP |
| `webhook` | Webhook subscription management and testing |

## Example Usage

Once connected, ask your AI assistant natural language questions:

* "Send an email from my agent to [user@example.com](mailto:user@example.com)"
* "Store my CRM login credentials in the vault"
* "Text me now from my agent's number"
* "Make a voice call to +1-555-0123"

For editor-specific setup, see [Connect your AI client](/integrations).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.