Aima MCP

The Aima MCP server lets AI assistants drive your AIMA Labs account — list agents, create campaigns, dispatch calls, connect WhatsApp, and more — without leaving the chat. It exposes the same capabilities as the CLI and the /api/cli REST API, packaged as Model Context Protocol tools.

Every request is scoped to a single organization via an API key. There is no cross-tenant access.

Endpoint and authentication

API keys are organization-scoped. Create one under Settings → Organization → Developers → API keys. Keys use the api_… prefix.

The MCP server and CLI share the same key type. A key that works for aima status works for MCP.

Connect your client

Setup snippets also appear on the dashboard under Settings → Organization → Developers in the Use Aima from Claude card.

Claude (web)

1. Open Claude → Customize → Connectors.
2. Click Add custom connector.
3. Paste https://app.aimalabs.io/api/mcp as the connector URL.
4. Authenticate with your API key when prompted.

Claude Code

claude mcp add --transport http aima https://app.aimalabs.io/api/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"

Cursor

One-click: use the Add to Cursor deeplink on the Developers page (pre-fills the endpoint).

Manual: add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "aima": {
      "url": "https://app.aimalabs.io/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

After editing mcp.json, reload the Cursor window so new servers are picked up.

Codex

export AIMA_API_KEY="YOUR_API_KEY"
codex mcp add aima --url https://app.aimalabs.io/api/mcp --bearer-token-env-var AIMA_API_KEY

Or add to ~/.codex/config.toml:

[mcp_servers.aima]
url = "https://app.aimalabs.io/api/mcp"
http_headers = { Authorization = "Bearer YOUR_API_KEY" }

How tools work

Each MCP tool maps to one agent action in the AIMA backend — the same handler the CLI calls. Tool names use dotted notation (for example agents.list). Input parameters match the action's typed schema; responses are JSON.

Errors from the platform surface as MCP tool errors with the same detail message you would see from the CLI or REST API.

Currently exposed tools

The hosted server is rolling out tool-by-tool. Today these read-only tools are live:

Call list_tools from your client to see the exact set enabled on your deployment.

Full catalog (mirrors CLI)

The MCP server is built from a single action registry shared with the CLI. As rollout completes, every tool below will be available over MCP with the same inputs and outputs as the matching CLI command.

Agents

Voices

Campaigns

Leads

Calls

WhatsApp

Phone numbers

Usage and stats

MCP vs agent tool integrations

AIMA uses MCP in two different ways. This page documents the control-plane server (/api/mcp) for operating your account from an external AI client.

The other use is agent tool servers — external MCP endpoints your voice or WhatsApp agents call mid-conversation to look up orders, check inventory, or trigger actions in your own systems. Those are registered under Integrations and bound per campaign. See Integrations.

Tips for AI agents

• Prefer read-only tools (agents.list, campaigns.list, leads.status) before mutating operations.
• calls.dispatch and leads.initiate place real outbound contact and consume quota — confirm with the user first.
• Cross-tenant IDs return 404 (not 403) by design; treat a missing resource as "not found or not yours."
• For scripting outside MCP, use the CLI with AIMA_OUTPUT=json for the same data shapes.

Related

• CLI reference — terminal access to the same capabilities
• Integrations — Google Calendar, agent MCP bindings, Leadsforce
• Getting Started — account and organization setup