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

# Installation

> Connect a client to the Animam MCP server

The Animam MCP server is a **remote** server, reachable over HTTP (SSE transport):

```
https://mcp.animam.ai/mcp/sse
```

Authentication is a Bearer token (an Animam API token, or an OAuth access token). No package to install — point any MCP client at the endpoint.

## Prerequisites

* An Animam API token with the scopes you need — create one in the dashboard under **Settings → API tokens** (`https://app.animam.ai`). Tokens look like `ak_…`.
* An MCP client (Claude Code, Claude Desktop, Cursor, claude.ai, …).

## claude.ai (web)

Add a custom connector pointing at the endpoint; claude.ai runs the OAuth flow against `api.animam.ai` (the server advertises it via `/.well-known/oauth-protected-resource`).

1. **Settings → Connectors → Add custom connector**
2. URL: `https://mcp.animam.ai/mcp/sse`
3. Authorize.

## Claude Code / Claude Desktop / Cursor

These clients run local commands, so bridge to the remote server with the published [`mcp-remote`](https://www.npmjs.com/package/mcp-remote) shim. Add to your client's MCP config (e.g. `~/.claude/settings.json` for Claude Code):

```json theme={null}
{
  "mcpServers": {
    "animam": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://mcp.animam.ai/mcp/sse",
        "--header", "Authorization: Bearer ak_your_token"
      ]
    }
  }
}
```

Restart the client to load the server.

<Note>
  A first-party stdio package (`@animam/mcp`) is planned so you can run `npx @animam/mcp` directly instead of the `mcp-remote` shim. Until it ships, use the remote endpoint as shown above.
</Note>

## Token scopes

Scopes gate which tools a token can call. Create the token with what you need:

| Goal                     | Scopes                                          |
| ------------------------ | ----------------------------------------------- |
| Full access              | `*`                                             |
| Manage the bot & widget  | `settings:read`, `settings:write`               |
| Manage knowledge base    | `corpus:read`, `corpus:write`                   |
| Manage segments          | `segments:read`, `segments:write`               |
| Builder bots & analytics | `settings:write`, `corpus:write`, `stats:read`  |
| Read-only                | `settings:read`, `corpus:read`, `segments:read` |

A tool fails with a `Missing scope: …` message if the token lacks its required scope — see each tool's required scope in [MCP tools](/mcp/tools).

## Verification

Once connected, ask your client:

```
You: Show my Animam tenant configuration.
Claude: (calls get_tenant) Bot name "Aria", primary color #2563EB, …
```

or check the endpoint directly:

```bash theme={null}
curl https://api.animam.ai/tenants/your-slug \
  -H "Authorization: Bearer ak_your_token"
```

## Troubleshooting

### 401 Unauthorized

The token is missing, malformed, or revoked. Confirm the `Authorization: Bearer ak_…` header is set, and that the token is active in **Settings → API tokens**.

### Tools missing

The token lacks the required scope. For example, `update_tenant` needs `settings:write`; a `corpus:read`-only token won't see write tools. Re-issue the token with the right scopes.

### Local development

The server lives in the monorepo at `apps/mcp` (Express + SSE, port `3302`). Run it with `pnpm dev:mcp` and point your client at `http://localhost:3302/mcp/sse`.