@anima-labs/mcp

MCP (Model Context Protocol) server for Anima -- 58 tools across 10 categories for AI agent communication, identity, and security.

Hosted vs local (which one do I want?)

Anima runs a hosted MCP gateway at https://mcp.useanima.sh/mcp -- nothing to install, always current, and it carries the fullest tool surface (it adds inbox management and other tools beyond this package's 54). If your client speaks remote MCP (Cursor, VS Code, Claude Code --transport http), point it there with Authorization: Bearer ak_... and you're done. See the MCP docs.

This npm package is the stdio bridge for clients without remote-MCP support and for pinned/air-gapped configs. Same platform, same auth, smaller tool set.

anima setup-mcp install --all            # hosted gateway (default)
anima setup-mcp install --all --mode stdio  # this package

Installation

npm install @anima-labs/mcp
# or
bun add @anima-labs/mcp

Quick Start

# stdio mode (default -- for Claude Desktop, Cursor, Windsurf, etc.)
npx @anima-labs/mcp

# HTTP mode (for web integrations)
npx @anima-labs/mcp --http --port=8014

# Selective tool loading (only register specific groups)
npx @anima-labs/mcp --tools=email,vault,phone

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | ANIMA_API_URL | No | API server URL (default: https://api.useanima.sh) | | ANIMA_API_KEY | Yes | Agent API key (ak_ prefix) | | ANIMA_MASTER_KEY | No | Master key (mk_ prefix) for admin tools |

Selective Tool Loading

Use the --tools flag to load only the tool groups you need. This reduces the tool count exposed to the LLM, which can improve tool selection accuracy and reduce token usage.

npx @anima-labs/mcp --tools=email,vault,phone

Available tool groups:

| Group | Description | |-------|-------------| | 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 | | provisioning | Ask your human owner for a vault or phone number | | vault | Credential vault management and TOTP | | webhook | Webhook subscription management and testing |

If --tools is not provided, all groups are registered (current default behavior).

HTTP Mode

Run the MCP server over HTTP instead of stdio for web integrations:

npx @anima-labs/mcp --http --port=8014

The server listens at http://localhost:8014/mcp and expects a Bearer <api-key> authorization header on each request.

Configuration Templates

Claude Desktop

~/.config/claude/claude_desktop_config.json:

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

With selective loading:

{
  "mcpServers": {
    "anima": {
      "command": "npx",
      "args": ["-y", "@anima-labs/mcp", "--tools=email,vault,phone"],
      "env": { "ANIMA_API_KEY": "ak_..." }
    }
  }
}

Cursor

.cursor/mcp.json:

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

Windsurf

.windsurf/mcp.json:

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

Tool Reference

Workspace (2 tools)

| Tool | Description | |------|-------------| | account_overview | Single-call workspace snapshot: context, send-capability flags, inventory counts, and blockers | | usage_overview | Usage rollup for a billing period |

Agent (5 tools)

| Tool | Description | |------|-------------| | agent_create | Create a new agent, optionally with metadata and an initial address | | agent_get | Get full detail for an agent: settings, metadata, status, addresses, and identities | | agent_list | List agents in the current account context with cursor pagination | | agent_update | Update an agent's name or metadata, and add/update/delete an address | | agent_delete | Delete an agent by ID |

Email (13 tools)

| Tool | Description | |------|-------------| | email_send | Send a new outbound email from the agent mailbox | | email_get | Get full detail for a single email by ID, including metadata and body | | email_list | List emails newest-first with cursor pagination, optionally scoped to one agent | | email_search | Search email by meaning (semantic vector search) or literal keyword | | email_reply | Reply to an existing email thread with correct threading headers | | email_forward | Forward an existing email to another recipient | | email_thread_get | Fetch all messages in one or more email threads | | email_attachment_get | Get a temporary download URL for an email attachment | | email_draft_create | Create a new email draft (composed but not sent) | | email_draft_get | Get full detail for a single draft by ID | | email_draft_list | List email drafts with optional filters | | email_draft_send | Send a draft | | email_draft_delete | Discard a draft |

Domain (7 tools)

| Tool | Description | |------|-------------| | domain_create | Register a custom sending domain in the workspace | | domain_verify | Trigger a verification check after DNS records are configured | | domain_get | Get full detail for a domain, including verification and config state | | domain_list | List all domains connected to the current workspace | | domain_update | Update mutable configuration on a domain | | domain_delete | Delete a domain from the workspace | | domain_zone_file | Get the full DNS zone file for a domain |

Phone (3 tools)

| Tool | Description | |------|-------------| | phone_number_list | List provisioned phone numbers, optionally filtered by agent | | phone_number_provision | Provision a new phone number and assign it to an agent | | phone_number_release | Release a provisioned phone number back to the carrier pool |

Phone Call (6 tools)

| Tool | Description | |------|-------------| | phone_call_create | Initiate an outbound phone call from an agent (returns a callId immediately) | | phone_call_list | List phone calls with optional filters | | phone_call_get | Get full detail for a call: status, duration, participants, AI summary, and quality score | | phone_call_transcript_get | Get the full transcript with speaker labels, timestamps, and confidence scores | | phone_call_recording_get | Get a time-limited download URL for a call recording (WAV) | | voice_list | List available AI voices for placing phone calls |

SMS (5 tools)

| Tool | Description | |------|-------------| | sms_send | Send an SMS, or an MMS by passing mediaUrls | | sms_get | Get full detail for a single SMS by ID (includes its threadId) | | sms_list | List SMS messages with optional filters | | sms_thread_list | List SMS conversations | | sms_thread_get | Get a specific SMS conversation with message history |

Provisioning (4 tools)

An agent cannot provision its own vault or phone number -- vault_provision and phone_number_provision are master-key-only, and an MCP session is authenticated as the agent. These tools file the ask instead; the owner decides in the Anima console.

Approve and decline are deliberately NOT exposed as tools. An MCP tool is something the model can decide to call, and a prompt-injected agent able to approve its own request could grant itself a billable phone number -- exactly the escalation the flow exists to prevent.

| Tool | Description | |------|-------------| | provisioning_request_create | Ask your owner to provision a vault or phone number | | provisioning_request_list | List requests you have filed and their status | | provisioning_request_status | Check one request; a decline carries the owner's reason | | provisioning_request_cancel | Withdraw a pending request you no longer need |

Vault (8 tools)

| Tool | Description | |------|-------------| | vault_provision | Provision a credential vault for an agent | | vault_credential_list | List credentials in an agent vault with optional type filter | | vault_credential_get | Get a single vault credential by ID | | vault_credential_create | Create a new credential in an agent vault | | vault_credential_update | Update an existing vault credential by ID | | vault_credential_delete | Delete a credential from vault storage by ID | | vault_credential_search | Search vault credentials by keyword across names and content | | vault_credential_get_totp | Get the current TOTP code for a credential with a TOTP secret |

Webhook (5 tools)

| Tool | Description | |------|-------------| | webhook_set | Create or update a webhook subscription | | webhook_get | Get a webhook subscription by ID | | webhook_list | List webhook subscriptions with cursor pagination | | webhook_delete | Delete a webhook subscription by ID | | webhook_test | Send a test event to verify endpoint reachability and signature verification |

Contributing: the contract gates

Every tool here is a thin client over the Anima REST API, which makes two lies easy to ship and nearly impossible to notice — both return a green 200:

• a tool calling a route the API doesn't have, and
• a tool advertising a parameter its route ignores (the API validates with Zod, which strips unknown input, so the server answers as if nothing was wrong and the model believes its filter was applied).

Two CI gates in src/__tests__/integration/contract-parity.test.ts make both impossible. They check src/tool-routes.ts — where each tool declares the routes it calls and any param it handles client-side — against src/__tests__/fixtures/contract-routes.json, a snapshot of the real @anima/contracts route surface.

Adding or changing a tool means updating its entry in src/tool-routes.ts. If a gate fails, fix the tool: editing the declaration to match a lie, or parking a param in clientParams, re-opens the exact hole the gates close.

Refreshing the snapshot (needs a checkout of the anima monorepo — it is private, so CI cannot do this for you):

bun run contracts:refresh -- --anima ../anima   # rewrite the snapshot
bun run contracts:check   -- --anima ../anima   # diff only; non-zero on drift

Community

Join the Anima Discord to ask questions in #mcp, share what you're building in #showcase, and stay up to date with releases in #announcements.

License

MIT