Managing Mavra via MCP

Mavra is a CRM + AI-agent platform. This skill lets you manage a Mavra account by chatting with your AI client, through the Mavra MCP server.

1. Connect (once)

The Mavra MCP server lives at https://mcp.maiacompany.io/mcp (development: https://mcp-dev.maiacompany.io/mcp). It uses OAuth: the client opens a browser, the user signs in to Mavra and approves access, and the client handles tokens from then on. Never ask the user for their password, and never put credentials in tool arguments.

Register the server by running the bundled script with Node (macOS, Windows, Linux):

node "${CLAUDE_SKILL_DIR}/scripts/connect.mjs"        # production
node "${CLAUDE_SKILL_DIR}/scripts/connect.mjs" --dev  # development

${CLAUDE_SKILL_DIR} is set by Claude Code. The script replaces an existing mavra server, so it also moves older setups off the legacy api.maiacompany.io/mcp URL.

Other clients: add a remote (HTTP / streamable HTTP) MCP server with the URL above. On claude.ai or Claude Desktop that is Settings → Connectors → Add custom connector. Leave the OAuth client ID/secret empty, because the server registers clients itself.

2. Sign in

• Claude Code: run /mcp, choose mavra, then Authenticate. A browser tab opens on the Mavra consent page. The user logs in (if needed) and clicks Allow.
• claude.ai / Claude Desktop / Cursor / ChatGPT: the client shows a Connect button the first time and runs the same browser flow.

Call whoami to confirm the connection and see the user's role and company.

Headless clients (CI, scripts, clients without a browser) can skip OAuth and send a Mavra API token as a header, Authorization: Bearer <API_TOKEN>. For Claude Code:

claude mcp add --transport http mavra https://mcp.maiacompany.io/mcp \
  --header "Authorization: Bearer <API_TOKEN>"

3. Recipes

Each recipe shows the exact arguments to pass. For the full list of tools, actions, typed request fields, and response shapes, read references/tools.md.

Create an AI agent

{ "action": "create",
  "title": "Sales Assistant",
  "customPrompt": "You are a helpful sales assistant.",
  "contextSize": 4000 }

Call manage_agents with the above. contextSize must be between 800 and 128000. The response includes the new agent's id (use it for get / update / delete). To turn on guardrails later, call manage_agents action: "update" with agentId plus guardrailsEnabled: true.

Important — the customPrompt has a special syntax. It is NOT just plain text: Mavra parses @-decorators and {{variables}} for flows, tool calls, CRM writes, transfers, follow-ups, and media. To write effective agents, read references/prompt-syntax.md. Quick taste:

@IF customer asks about pricing [price, cost]
@THEN @Tool(SendPricingGuide)
@ELSE Continue qualifying the lead.
@END
@updateCRM("Sales Pipeline", "status", "Mark 'Qualified' when budget is confirmed")

Add and find a CRM record

Create with manage_crm_records action: "create" (title required):

{ "action": "create", "title": "Acme Corp" }

The response returns recordId — use it for later get / update / delete. To search, call search_crm action: "search" with q: "acme".

List sessions and transfer one

manage_sessions action: "list" returns { items: [...] }. To move a conversation to another agent:

{ "action": "transfer",
  "channelId": "CHANNEL_ID", "sessionId": "SESSION_ID",
  "targetAgentId": "AGENT_ID" }

Configure a webhook

manage_webhooks action: "create" with name, url, and triggerTypes (a string array):

{ "action": "create",
  "name": "CRM events", "url": "https://example.com/hook",
  "triggerTypes": ["crm_record_created"] }

Channels & WhatsApp

Create/edit channels with manage_channels (requires name, type, identifier, defaultAgentId). Full WhatsApp (Meta Cloud API) setup is also supported: create a connection with manage_connections, the channel with manage_channels, then link them with manage_whatsapp action: "setup". See references/channels.md for the step-by-step flow.

4. When something goes wrong

• 401 / "Unauthorized" — the connection is not signed in or access was revoked. Ask the user to re-authenticate (Claude Code: /mcp → mavra → Authenticate; other clients: reconnect the connector). Do not ask for their password.
• 403 — the logged-in user's role can't perform this action.
• 429 — rate limited: wait the number of seconds in the error message, then retry.
• Validation errors — the message names the missing/invalid field; fix and retry.

Reference

Read these on demand for complete, typed detail:

• references/tools.md — every tool, action, typed request field, and response shape.
• references/prompt-syntax.md — the agent customPrompt @-decorator + {{variable}} language (essential for writing agents).
• references/agents.md — all agent fields, providers/models, guardrails, knowledge base, media, versioning, testing, feedback.
• references/crm.md — CRM records, custom field types, field groups, statuses, kanbans, filters, search.
• references/channels.md — channel types, contacts, and the WhatsApp connection setup flow (manage_connections + manage_whatsapp).
• references/chat-and-settings.md — sessions, messages (send vs send-as-agent vs human reply), chat notes, provider keys, webhooks + event types.