Setup

Channels

How to turn on and check the HTTP API, Telegram (bot and groups), the widget and the incoming MCP channel, and which team a message goes to.

A channel is where messages come into the cradle from. There are four channels; the HTTP API works from the first start, the others are turned on. In the console the settings are on the team page: the Integrations tab → the channel's card.

1. Which team a message goes to

ChannelTeam
HTTP APIthe team of the key the request came with
MCP channelthe team of the key
Telegram, a groupthe team chosen for the group in the Telegram card
Telegram, a private chatthe "channel team"
Widgetthe "channel team"

The "channel team" is stored in the channel's own settings; by default it is the cradle's service team opencradle. In version 0.9.2 there is no screen or command to change it. While opencradle has no agents the console does not show it. For private Telegram chats and the widget to be answered by anybody, create an agent in that team:

cradle teams use opencradle
cradle agents create --template support --name "Support"

(an admin:* key is needed). Once the agent exists, the "OpenCradle" team is visible on the "Teams" page. For the HTTP API and MCP this is not needed: the key decides the team.

2. HTTP API

The channel is on at once and listens on 127.0.0.1:31416. The port and the listening address are set by the server flags --port and --bind (the variable CRADLE_BIND) at every start: the card does not override them. The "API key" field in the card is only there so the channel can start (at least 16 characters): at the first start the server puts a copy of the administrator key there, so do not show the card to outsiders. Requests are authorized with the keys from cradle keys.

  1. Issue a key for the team (Sign-in, people and keys):

    cradle keys create --name "site" --scopes messages:read,messages:write --team <team-id>
  2. Send a message:

    curl -sS -X POST http://127.0.0.1:31416/api/v1/messages \
      -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
      -d '{"text":"Hello","chatId":"test-1"}'

The answer has ok, mode, chatId, conversationId, messageId, ticketId (null if the reply went out without a human) and replies. The modes are sync (the default, the reply comes in the same request), async (a 202 answer and a drainUrl, the replies are collected with GET /api/v1/messages/<chatId>?wait=<ms>) and webhook (the field webhookUrl; the signature is the header X-Cradle-Signature: sha256=…, HMAC-SHA256 with the webhook secret or the channel key). To continue a conversation use the same chatId.

How to check. The answer is "ok":true. Without a model the reply is Запрос принят и передан оператору на проверку. Ответим в течение нескольких минут. (the request is accepted and passed to an operator for review; the server writes it in Russian), and ticketId is filled — the ticket waits for a human (Waiting for decision). The "HTTP API" card shows "requests: N".

If it did not work.

  • 401 unauthorized — the key is wrong; 403 with missing — messages:write is not granted.
  • 400 text length out of bounds (1..50000) — text is empty or too long.
  • 429 — more than 120 requests a minute from one address and key.

3. Telegram

  1. In Telegram create a bot with @BotFather and copy the token like 1234567890:ABC-....
  2. In the console: Integrations → Telegram → the "Bot token" field → Save → Start.

The bot works over long polling: no incoming port has to be opened.

How to check. The card says "Connected as @bot_name"; write to the bot in a private chat — a ticket appears in "Waiting for decision" of the channel team, or the bot answers itself. The state of all channels: cradle channels list (the RUNNING column).

If it did not work. The answer Failed to connect to Telegram: … — the token is wrong or the server has no way out to api.telegram.org.

Groups

Add the bot to a Telegram group: it reads everything written there and answers those who address it (an @bot mention, a reply to its message, a command). A "Группы" (groups) list with a select for every group appears in the Telegram card. Choose a team and press Save.

While a group has "Команда канала" (the channel team) selected, it is not bound: the bot answers once Меня сюда не подключили. Попросите администратора привязать группу к команде в Cradle. (I am not connected here; ask an administrator to bind the group to a team in Cradle) and then stays silent.

If the card shows "Privacy mode включён" (privacy mode is on), the bot receives only commands and mentions. For the bot to see everything: in @BotFather — /setprivacy → Disable, then remove the bot from the group and add it again (or make the bot an administrator of the group).

4. Widget

A floating chat with one <script> on your site. In the console: Integrations → Web Widget → Port (31415 by default), Accent color, API key (the Generate button gives a key like wk_...), Allowed origins (comma-separated; empty — any), Greeting → Save → Start. The ready code is in the "Embed snippet" field (Copy to clipboard):

<script
  src="https://<public-address>/widget.js"
  data-cradle-widget
  data-api-key="wk_..."
  async></script>

The widget listens on 127.0.0.1 only: for a page on the internet to see it, publish the port through a reverse proxy or a tunnel. Besides, the widget.js bundle is not part of the installer archive or the Docker image: on such a server GET /widget.js answers 503 "Widget bundle not built yet". Build it with bun run widget:build in a repository clone and run the server from there.

How to check. curl -i http://127.0.0.1:31415/widget.js gives 200 and application/javascript; the card says "Connections: N · Port: 31415".

If it did not work. 503 — the bundle is not built (see above); the widget does not open on the site — the site's domain is not in "Allowed origins".

5. The incoming MCP channel

Through it Claude Code, n8n or SmartNotes call the cradle as an MCP server. The channel is off by default. Turn it on in one of two ways.

At server start, with an environment variable (0.0.0.0 opens the channel to the network, the port is set by CRADLE_MCP_PORT, 31417 by default):

CRADLE_MCP_BIND=127.0.0.1 cradle-server …

On a running server there is neither a console screen nor a working CLI command (cradle channels start is a stub), so the channel is turned on with POST /api/v1/rpc/channels:start:

curl -s -X POST http://127.0.0.1:31416/api/v1/rpc/channels:start \
  -H "Authorization: Bearer $ADMIN_KEY" -H "Content-Type: application/json" \
  -d '{"args":["mcp-server"]}'

The address is http://127.0.0.1:31417/mcp (method POST), the key goes in the header x-api-key or Authorization: Bearer; every tool needs its own scope:

ToolScope
cradle_search_kb, cradle_list_kbskb:read
cradle_list_agentsagents:read
cradle_execute_agent, cradle_summarize_notesagents:execute
cradle_get_ticket, cradle_list_ticketstickets:read
cradle_submit_issuemessages:write
cradle_catalog, cradle_team_plan, cradle_team_exportteams:read
cradle_team_applyagents:write

How to check.

curl http://127.0.0.1:31417/health

The answer is {"ok":true,"running":true,"toolCount":12,…}.

If it did not work. ECONNREFUSED — the channel is not turned on; the tool answer unauthorized — no key or the scope is missing. The "MCP servers" card in the console is something else: through it agents call external servers, not the other way round.