MCP Server

Quick start#

You need a Public API key. Create one in the BusinessChat dashboard under Settings → Developer settings → API keys, and give it only the scopes the agent needs. The full key is shown once, at creation.

Claude Code#

Add the server from your terminal, with your key in place of bc_live_<id>_<secret>:

claude mcp add --transport http businesschat https://api.businesschat.io/mcp \
  --header "Authorization: Bearer bc_live_<id>_<secret>"

By default this is saved for you only, in the current project. Add --scope user to use it in all your projects. Don't use --scope project with the key written into the command: project scope is stored in a file meant to be shared with your repository.

This connects with the default tool groups. To choose groups, add ?groups= to the URL, for example https://api.businesschat.io/mcp?groups=contacts,sessions.

Checking the connection#

Start claude and run /mcp. businesschat should be listed as connected, with its tools. Claude Code names them mcp__businesschat__<tool>, for example mcp__businesschat__listContacts, and those are the names to use in its permission settings.

Then try a first prompt:

Using the businesschat tools, show me which scopes my API key has, then list my 5 most recent open sessions.

The first part calls getCapabilities, which every key can call. It's the quickest way to confirm the key works and to see what it can reach.

Other clients#

Any MCP client that supports remote servers over Streamable HTTP and lets you set a request header can connect. Most take a JSON configuration shaped like this one:

{
  "mcpServers": {
    "businesschat": {
      "type": "http",
      "url": "https://api.businesschat.io/mcp",
      "headers": {
        "Authorization": "Bearer bc_live_<id>_<secret>"
      }
    }
  }
}

Field names vary between clients. Check yours for where the URL, the transport (HTTP or Streamable HTTP) and custom headers go. A client that can only connect with OAuth sign-in can't use this server.

Authentication#

The MCP server uses the same API keys as the Public API, sent the same way:

Authorization: Bearer bc_live_<id>_<secret>

Every request to /mcp is authenticated on its own. A missing or invalid key gets 401 before any MCP handling (see HTTP errors).

A key belongs to one business and always acts as that business. Tools have no business argument: an agent can't pass one, and a tool call that tries is rejected as an unknown argument. Any resource constraints set on the key, such as a limit to certain teams, apply to tool calls exactly as they do to direct API calls.

Scopes#

The key's scopes decide which tools the agent gets:

• Listing tools returns only the tools your key has the scopes for. A key without topics:write never sees createTopic.
• Calling a tool checks the scopes again, and the API request it makes is checked again after that. A tool your key can't use is refused with insufficient_scope.

Grant the narrowest set that does the job. For an agent that should only look things up, grant :read scopes only: no write tools will appear at all.

Scopes can't be changed after a key is created. To change what an agent can do, create a new key and update the client's configuration.

Keeping the key safe#

• Create a separate key for each agent or person, named after it, so you can revoke one without breaking the others. Revoking takes effect on the next request.
• Keep the key in the client's local or user configuration. Don't commit it to a repository or put it in a shared config file.
• Don't paste the key into a chat with the agent. The client sends it as a header, and the model never needs to see it.
• Review write and destructive tool calls before approving them (see Read-only and destructive tools).

Tool groups#

The client loads every tool's name, description and input schema into the AI model's context. The full catalogue is large, and a long tool list takes up context and makes the right tool harder for the model to pick. Tool groups let you load only the part you need.

Choose groups with the groups query parameter on the server URL, as a comma-separated list:

https://api.businesschat.io/mcp                                 default groups
https://api.businesschat.io/mcp?groups=contacts,sessions        just these two
https://api.businesschat.io/mcp?groups=all                      every group

• No groups: the default set, capabilities, contacts, sessions, templates and work-items.
• groups=all: every group. Use all on its own, not combined with other names.
• An unknown name: the request is refused with an error that lists the valid groups.
• Calling a tool outside your groups: refused with an error that names the tool's group, for example Tool 'listProducts' is in the 'products' tool group, which this connection did not select. Add it to the MCP URL, for example ?groups=products.

Available groups#

Counts are for a key with every scope. Your key sees only the tools its scopes allow. Groups follow the sections of the API reference, and new API operations appear as tools in their group automatically.

The default groups hold 52 tools and all holds 127. There is no messages group: see Not available.

Choosing groups#

• Leave groups off for everyday support work: contacts, sessions, templates and work items.
• Pick the groups for your task when it's narrower or different, for example ?groups=work-items,work-items-setup to set up a work item type, or ?groups=teams,users to review team membership.
• Use all only if your client handles many tools well, for example by loading tool definitions on demand.

The groups are part of the server URL, so changing them means changing the URL in your client and reconnecting. In Claude Code, run claude mcp remove businesschat and add it again with the new URL.

How tools work#

Each tool maps one-to-one to a Public API operation and is named after its operation id: listContacts, getSession, transitionWorkItem. The tool's description is the operation's description from the API reference. Parameters, fields and error codes are documented there, under the API tab.

Arguments#

The agent fills in tool arguments from each tool's input schema. They map onto the API request like this:

For example, a call to createTopic looks like this:

{
  "idempotency_key": "create-topic-vip-2026-09-14",
  "body": { "name": "VIP", "color": "#1d4ed8" }
}

An argument the tool doesn't define is rejected, not ignored. The error lists the arguments the tool accepts, so the agent can correct the call. A missing required argument is rejected the same way.

Read-only and destructive tools#

Every tool carries hints that clients can use to decide when to ask you before running it:

• Read-only: every GET operation (list and get tools).
• Destructive: every DELETE operation, and archive actions such as archiveTopic.
• Idempotent: GET, PUT and DELETE operations.

Every other tool changes data. How hints are used depends on the client; Claude Code asks for permission before it runs a tool, unless you've allowed it.

Results#

A successful call returns the API response body as JSON text, exactly as the API would return it. Lists use the API's usual envelope, so the agent pages by passing next_cursor back as the cursor argument.

A failed call returns a tool result marked as an error (isError: true) containing HTTP <status> and the API's error body, so the agent can read the error code and react. See Tool errors.

Not available#

Sending WhatsApp messages is not available, over MCP or through the Public API.

The server offers tools only. It has no MCP resources or prompts.

Limits & behaviour#

Rate limits#

Two limits apply, both per minute:

The MCP message limit is set higher so that connecting and listing tools never run out before tool calls do. In practice the API limit is the one you'll hit.

• Over the API limit: the tool call returns a tool error such as HTTP 429: rate limit exceeded. Retry after 12 seconds (Retry-After: 12). The agent should wait that long and retry.
• Over the MCP message limit: the /mcp request itself gets HTTP 429 rate_limit_exceeded with a Retry-After header. /mcp responses carry X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset for this limit.

Timeouts & response size#

• A tool call has 150 seconds in total. A slower one returns the tool error The BusinessChat API did not answer in time. Retry, or narrow the request.
• A tool result can be up to 16 MB. A larger response returns The BusinessChat API response is too large to return. Narrow the request, for example with a smaller limit.

Filters and a smaller limit fix both. List operations clamp limit to their maximum rather than rejecting it.

No sessions#

The server is stateless. Each message is a single POST /mcp answered with one JSON response. There is no session id, no event stream (GET /mcp returns 405) and no notifications from the server, so reconnecting loses nothing. Batched JSON-RPC requests aren't supported: send one message per request.

An Idempotency-Key header on the /mcp request itself is ignored. To make a write safe to retry, use the tool's idempotency_key argument.

Browser clients#

Requests that carry a browser Origin header are refused with 403 Forbidden: Origin not allowed. This protects your key against malicious web pages. Connect from a command-line, desktop or server-side client, which don't send Origin. Your key shouldn't be in a browser anyway.

Errors#

A problem shows up in one of three places, depending on how far the request got.

HTTP errors#

The request was refused before MCP handling. Clients usually report these as a failed connection.

JSON-RPC errors#

The request reached the server, but it refused the tool list or the tool call itself, so no API request was made. These come back with HTTP 200 and a JSON-RPC error:

Tool errors#

The tool ran but didn't succeed. The result is a normal tool result with isError: true, and the agent sees the text and can usually correct itself.

Reporting a problem#

Every /mcp response carries an X-Request-Id header. Quote it to BusinessChat support, and we can find that request and the API request its tool call made. If your client doesn't show response headers, send the time (with time zone), the tool name and the name of the key you used instead. Never send the key itself.

Troubleshooting#

To test the key and URL outside your client, list the tools with curl:

curl -X POST 'https://api.businesschat.io/mcp' \
  -H 'Authorization: Bearer bc_live_<id>_<secret>' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

A 200 with a tools array means the key and URL work, and the problem is in the client's configuration.