MCP server

Keebai exposes a Model Context Protocol server so an AI agent can use your account directly: send WhatsApp messages and emails, search your knowledge base, read and write CRM records, manage contacts, look up products, manage stock, record sales and issue their tax documents, run the loyalty programme, book appointments. It is the same API described in the rest of these docs, presented as tools an LLM can call. Each tool checks the same scope as its REST counterpart. There are two ways to authenticate:

Sign in with OAuth — for Claude, ChatGPT and any MCP app that supports it. You paste the URL, sign in to Keebai, pick the company and approve permission groups. There is no token to create or copy.
A Personal Access Token — for clients without OAuth, scripts, and servers that run unattended.

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 with OAuth

Claude

claude.ai, Claude Desktop and Claude Code.

ChatGPT

As a custom MCP server.

Other MCP apps

Cursor, VS Code, Gemini CLI and the rest.

The app only needs the URL above. It discovers the sign-in from Keebai, opens accounts.keebai.com in your browser, and keeps its tokens fresh on its own. Each person connects with their own account, and what they can approve is limited by their Keebai role. You can see and disconnect every connected app in the portal under Developers › Connected apps (Desarrolladores › Apps conectadas). Building your own client? See the OAuth reference.

Connect with a Personal Access Token

Use a token when the client cannot sign in with OAuth, or when nobody is there to sign in.

{
  "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 every tool 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 — or, over OAuth, approve only the groups you want — and treat what you leave out as a hard boundary rather than a hint.

Least privilege

The whole scope catalogue is on the Scopes page. Over OAuth you approve groups rather than single scopes; with a token you can be as precise as you like. Some useful shapes for an agent:

Read-only agent

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 agent

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.

Booking agent

Finds an open slot and books it. Cancelling stays out, so it can never free someone else’s appointment.scheduling:branches:read, scheduling:services:read, scheduling:professionals:read, scheduling:availability:read, scheduling:appointments:create, scheduling:appointments:confirm.

Twelve 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.
`GET /v1/ecommerce/invoicing/documents/{id}/pdf`	Returns a PDF file, not JSON.
WhatsApp templates, channels, webhooks, tenants	Not exposed as tools yet. Use the REST API. Email senders and email templates do have tools.

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.

Next steps

Connect with Claude

Add Keebai as a connector and sign in.

Tool catalogue

Every tool with its required scope.

OAuth reference

Endpoints and errors for your own client.

Create a token

Mint a PAT and pick its scopes.

Get started

Authentication

MCP

SDK

CLI

Agent Skills

Limits

Endpoint

Connect with OAuth

Claude

ChatGPT

Other MCP apps

Connect with a Personal Access Token

Scopes are enforced per tool, not per connection

Least privilege

Read-only agent

Support agent

CRM operator, no deletes

Sales agent

Knowledge maintainer

Loyalty concierge

Booking agent

What is not exposed

Operational notes

Next steps

Connect with Claude

Tool catalogue

OAuth reference

Create a token

​Endpoint

​Connect with OAuth

Claude

ChatGPT

Other MCP apps

​Connect with a Personal Access Token

​Scopes are enforced per tool, not per connection

​Least privilege

Read-only agent

Support agent

CRM operator, no deletes

Sales agent

Knowledge maintainer

Loyalty concierge

Booking agent

​What is not exposed

​Operational notes

​Next steps

Connect with Claude

Tool catalogue

OAuth reference

Create a token

Endpoint

Connect with OAuth

Connect with a Personal Access Token

Scopes are enforced per tool, not per connection

Least privilege

What is not exposed

Operational notes

Next steps