Developer API

The Loomira MCP server

Manage Loomira from Claude, Cursor or any MCP client. The Model Context Protocol (MCP) is an open standard that lets AI assistants call external tools — Loomira ships a native MCP server exposing the same curated surface as the REST API: agents, calls with embedded transcripts, knowledge sources, webhooks and their delivery log. There are deliberately no call-placing tools — calls are initiated from the portal or by real callers, never by an AI assistant.

Endpoint & authentication

The server lives at https://api.loomira.ai/mcp and speaks streamable HTTP (the current MCP transport). Authenticate with your Loomira API key as a bearer token: Authorization: Bearer lmk_.... Note the contrast with REST — REST requests carry the key in X-Api-Key, MCP carries the same key in the Authorization header, and both draw from the same per-key rate budget. Keys are minted in the portal under Developer → API keys; MCP access, like the REST API, requires the Scale plan or above.

Connect your client

Claude Desktop

Claude Desktop launches MCP servers as local commands, so remote HTTP servers connect through the mcp-remote bridge. Add this to claude_desktop_config.json (Settings → Developer → Edit Config), then restart Claude Desktop:

claude_desktop_config.json

{
  "mcpServers": {
    "loomira": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.loomira.ai/mcp",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer lmk_your_api_key"
      }
    }
  }
}

The header value rides in an env var with no space after Authorization: on purpose — some clients split argument strings on spaces.

claude.ai (web)

Open Settings → Connectors and choose Add custom connector.
Name it Loomira and set the remote MCP server URL to https://api.loomira.ai/mcp.
Provide your API key as the bearer token (Bearer lmk_... in the Authorization header) in the connector's authentication settings.
Save, then enable the connector in a chat via the tools menu.

Cursor

Cursor connects to streamable-HTTP servers directly. Create .cursor/mcp.json in your project (or ~/.cursor/mcp.json globally):

.cursor/mcp.json

{
  "mcpServers": {
    "loomira": {
      "url": "https://api.loomira.ai/mcp",
      "headers": {
        "Authorization": "Bearer lmk_your_api_key"
      }
    }
  }
}

Any other MCP client that speaks streamable HTTP works the same way: point it at the endpoint and send the bearer header.

The tool surface

Fourteen curated tools, mirroring the REST API one-to-one. Each tool requires the listed API-key scope — a key without it gets a per-tool insufficient_scope error, so a read-only key is safe to hand to an assistant that should only inspect, never change.

Agents

Tool	Scope	What it does
list_agents	`read`	All agents in the workspace, paginated.
get_agent	`read`	One agent with its full definition document and updated_at.
create_agent	`write`	Create a draft agent; the definition is a partial deep-merged over platform defaults.
update_agent	`write`	Full-document replace. Pass get_agent’s updated_at as expected_updated_at to refuse lost updates.
activate_agent	`write`	Put a draft agent live (Scale entitlement + compliance gate).

Calls

Tool	Scope	What it does
list_calls	`read`	Call history, newest first; filter by agent and status.
get_call	`read`	One call in full — the complete transcript is embedded, no separate transcript tool.

Knowledge

Tool	Scope	What it does
list_knowledge_sources	`read`	All knowledge sources with their ingestion status.
add_knowledge_source	`write`	Add inline text or a public website; ingestion runs async (pending → ready).

Webhooks

Tool	Scope	What it does
list_webhooks	`read`	All outbound webhook endpoints.
create_webhook	`admin`	Create an endpoint — the response includes the HMAC signing secret, returned exactly once.
update_webhook	`admin`	Partial update: url, events, enabled, per-agent binding (agent_id / clear_agent_id).

Deliveries

Tool	Scope	What it does
list_webhook_deliveries	`read`	Delivery log, filterable by endpoint, agent, status and event; dead rows are the DLQ.
redeliver_webhook_delivery	`write`	Revive a dead delivery with a fresh attempt budget.

update_agent is a full-document replace: fetch with get_agent, edit, send the whole definition back — and pass the fetched updated_at as expected_updated_at so a concurrent edit is refused (412 precondition_failed) instead of silently lost. create_webhook returns the HMAC signing secret exactly once — relay it to whoever operates the receiving system immediately; it can never be listed or fetched again.

Troubleshooting

401 Unauthorized: Missing or invalid Authorization header. MCP uses "Authorization: Bearer lmk_..." — NOT the X-Api-Key header the REST API uses. Check the key was copied in full (it is shown exactly once at creation).
403 Forbidden: The key is valid but not eligible: API/MCP access requires the Scale plan or above. Inside a session, "insufficient_scope" tool errors mean the key lacks the scope a tool needs (read / write / admin) — mint a key with the right scopes in the portal.
429 Too Many Requests: Per-key rate limit exhausted. MCP requests draw from the SAME budget as REST calls made with that key, so heavy REST traffic can starve an MCP session (and vice versa). Back off and retry, or use separate keys per integration.

Tutorial: build an agent via the API REST quickstart & webhooks