Installation

The Animam MCP server is a remote server, reachable over HTTP (Streamable HTTP transport, POST /mcp; the legacy HTTP+SSE transport stays at /mcp/sse):

https://mcp.animam.ai/mcp

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).

Settings → Connectors → Add custom connector
URL: https://mcp.animam.ai/mcp
Authorize.

Claude Code / Claude Desktop / Cursor

These clients run local commands, so bridge to the remote server with the published mcp-remote shim. Add to your client’s MCP config (e.g. ~/.claude/settings.json for Claude Code):

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

Restart the client to load the server.

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.

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.

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:

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, port 3302). Run it with pnpm dev:mcp and point your client at http://localhost:3302/mcp. The deprecated HTTP+SSE transport is still served at /mcp/sse for older clients.

Getting Started

For AI Agents

Widget

Customization

MCP Server

WordPress

Guides

Prerequisites

claude.ai (web)

Claude Code / Claude Desktop / Cursor

Token scopes

Verification

Troubleshooting

401 Unauthorized

Tools missing

Local development

​Prerequisites

​claude.ai (web)

​Claude Code / Claude Desktop / Cursor

​Token scopes

​Verification

​Troubleshooting

​401 Unauthorized

​Tools missing

​Local development

Prerequisites

claude.ai (web)

Claude Code / Claude Desktop / Cursor

Token scopes

Verification

Troubleshooting

401 Unauthorized

Tools missing

Local development