MCP server

Keebai exposes a Model Context Protocol server so an AI agent can use your account directly: send WhatsApp messages, search your knowledge base, read and write CRM records, manage contacts, look up products and sales, run the loyalty programme. It is the same API described in the rest of these docs, presented as tools an LLM can call. Authentication is the same Personal Access Token you use for REST, and each tool checks the same scope as its REST counterpart. There is nothing extra to provision.

Endpoint

POST https://api.keebai.com/v1/mcp

Transport is Streamable HTTP, stateless — every request carries its own auth and no session is kept between calls. GET and DELETE on this path return 405.

Connect a client

{
  "mcpServers": {
    "keebai": {
      "url": "https://api.keebai.com/v1/mcp",
      "headers": {
        "Authorization": "Bearer kbai_pk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

{
  "mcpServers": {
    "keebai": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://api.keebai.com/v1/mcp",
        "--header",
        "Authorization: Bearer kbai_pk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      ]
    }
  }
}

curl -X POST https://api.keebai.com/v1/mcp \
  -H "Authorization: Bearer kbai_pk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

The Accept header must list both application/json and text/event-stream. Streamable HTTP negotiates between them per response, and a client that offers only one gets a protocol error.

The fastest way to get a working token is the Servidor MCP page in the portal: it opens the create-key modal with every scope the server uses already ticked. You can untick the ones you do not want — see Least privilege below.

Scopes are enforced per tool, not per connection

This is the one behaviour that surprises people:

Every tool is always listed

tools/list returns all 101 tools regardless of what your token can do. The catalogue is not filtered by scope.

The check happens on call

tools/call verifies the scope for that specific tool.

A missing scope is a tool error, not an HTTP error

You get 200 OK with a tool result carrying isError: true. The agent sees the failure and can explain it; your transport does not break.

{
  "isError": true,
  "content": [
    {
      "type": "text",
      "text": "{\"code\":\"INSUFFICIENT_SCOPE\",\"required\":[\"crm:customers:delete\"]}"
    }
  ]
}

The practical consequence: an agent may attempt a tool it is not allowed to use and only find out afterwards. Mint the token with the scopes you actually want it to have, and treat the ones you leave out as a hard boundary rather than a hint.

Least privilege

The whole scope catalogue is on the Scopes page. Some useful shapes for an agent:

Read-only assistant

Answers questions about your data, changes nothing.knowledge:read, knowledge:query, contacts:read, crm:customers:read, crm:tickets:read, crm:tasks:read, crm:notes:read.

Support agent

Reads context, replies on WhatsApp, and logs what it did.knowledge:query, contacts:read, messages:send, crm:tickets:read, crm:tickets:write, crm:notes:write.

CRM operator, no deletes

Full read/write across the pipeline with destruction left out.All crm:*:read and crm:*:write, contacts:read, contacts:write.

Sales assistant

Answers questions about the catalog and past purchases, and nothing else.ecommerce:products:read, ecommerce:sales:read, contacts:read.

Knowledge maintainer

Keeps the knowledge base in step with an external source.knowledge:read, knowledge:write, knowledge:delete, knowledge:assign.

Loyalty concierge

Answers “how many points do I have” over WhatsApp. Reads balances, changes nothing.loyalty:read, contacts:read, messages:send.

Eleven of the 101 tools delete things permanently, and CRM and contact reads span your whole company, not just one project. Think about that before handing an agent a token with *:delete scopes — the tool catalogue marks every destructive tool.

What is not exposed

Not available	Why
`POST /v1/media/upload`	Multipart upload of up to 100 MB does not fit a JSON tool call.
`GET /v1/media/{id}/download`	Returns raw binary.
Scheduling, templates, channels, webhooks, tenants	Not exposed as tools yet. Use the REST API.

Everything else in the REST surface has a matching tool.

Operational notes

The MCP endpoint is not rate limited. The 300/minute and 1000/day caps apply to the REST API; tool calls do not consume them. An agent in a loop can generate a lot of upstream traffic, so put your own ceiling on it.
Every tool call is audited with the tool name, the token, the outcome, and the latency, the same way REST calls are.
Tools are stateless. Nothing carries over between calls — every tool takes the ids it needs as arguments.
Errors arrive as text, not as structured problems. A failed call returns isError: true with the message flattened into a string; the HTTP status codes documented for REST do not reach the agent.

Get started

Authentication

MCP

SDK

CLI

Agent Skills

Limits

Endpoint

Connect a client

Scopes are enforced per tool, not per connection

Least privilege

Read-only assistant

Support agent

CRM operator, no deletes

Sales assistant

Knowledge maintainer

Loyalty concierge

What is not exposed

Operational notes

Next steps

Tool catalogue

Create a token

​Endpoint

​Connect a client

​Scopes are enforced per tool, not per connection

​Least privilege

Read-only assistant

Support agent

CRM operator, no deletes

Sales assistant

Knowledge maintainer

Loyalty concierge

​What is not exposed

​Operational notes

​Next steps

Tool catalogue

Create a token

Endpoint

Connect a client

Scopes are enforced per tool, not per connection

Least privilege

What is not exposed

Operational notes

Next steps