MCP Tools — API Reference

Каталог MCP tools що Brama експортує. Reference для AI-агентів і integration developers.

Заповнюється по мірі того як integrations ship’аться. Поточна v0.1 — scaffold-only. Перші tools у brama_ringostat_* namespace будуть додані з Ringostat integration.

Tool naming convention

brama_{vendor}_{action}

Vendor	Tools (planned)
ringostat	get_missed_calls, get_call_recording, create_callback_task, get_agent_stats
binotel	TBD (v0.2 candidate)
bas	TBD (v0.2 candidate)

Request format

Standard MCP request з Bearer auth:

POST https://api.brama.work/mcp/{tenant_id}
Authorization: Bearer {tenant_api_key}
Content-Type: application/json

{
  "method": "tools/call",
  "params": {
    "name": "brama_ringostat_get_missed_calls",
    "arguments": {
      "date": "2026-05-13",
      "idempotency_key": "<uuid>"
    }
  }
}

Response shape

{
  "result": {
    "content": [
      { "type": "text", "text": "<JSON-encoded structured payload>" }
    ]
  }
}

Structured payload schema — per tool у відповідній integration page.

Errors

Error code	Meaning	Retry safe?
rate_limited	Vendor rate limit hit	yes, з exponential backoff
invalid_token	Tenant vendor token expired/revoked	no — re-auth у admin
vendor_5xx	Vendor API transient error	yes
tenant_not_found	Tenant suspended або terminated	no

Idempotency

Write operations (анти-pattern: create_*, update_*, delete_*) приймають idempotency_key (UUID). Brama зберігає (tenant_id, key, result_hash) у Supabase — повторні calls з тим самим key повертають cached result без vendor API call.

Read operations natively idempotent — idempotency_key ігнорується якщо переданий.