AI конектори (MCP), очаквайте скоро

Адрес#

Сървърът е на https://api.console.citronos.com/mcp. Както при /graphql, адресът е без /v1. Работи с версия 2025-11-25 на протокола през streamable HTTP и не пази състояние: всеки POST получава JSON отговор, няма сесии, а GET и DELETE отговарят с 405.

След пускането ще могат да се свържат Claude (claude.ai, Claude Desktop и Claude Code), ChatGPT, Cursor, VS Code и всеки друг MCP клиент. Клиентите, които поддържат OAuth, влизат сами; останалите използват личен токен.

Свързване на клиент#

Claude Code#

Добавете сървъра, после изпълнете /mcp в Claude Code и изберете Authenticate. Отваря се браузър с екрана за одобрение в Citron. Ако не искате OAuth, подайте личен токен като заглавка.

claude mcp add --transport http citron https://api.console.citronos.com/mcp
# then, inside Claude Code: /mcp → citron → Authenticate

claude mcp add --transport http citron https://api.console.citronos.com/mcp \
  --header "Authorization: Bearer cmcp_pat_…"

Claude Desktop и claude.ai#

Отворете Settings → Connectors → Add custom connector, въведете https://api.console.citronos.com/mcp като адрес и изберете Connect, след което одобрете връзката в Citron. За да го пуснете локално с личен токен, добавете това в claude_desktop_config.json:

{
  "mcpServers": {
    "citron": {
      "command": "citron-mcp",
      "args": ["--base-url", "https://api.console.citronos.com"],
      "env": { "CITRON_MCP_TOKEN": "cmcp_pat_…" }
    }
  }
}

Cursor#

Добавете сървъра в ~/.cursor/mcp.json. Без headers Cursor влиза през OAuth вместо с токен.

{
  "mcpServers": {
    "citron": {
      "url": "https://api.console.citronos.com/mcp",
      "headers": { "Authorization": "Bearer cmcp_pat_…" }
    }
  }
}

ChatGPT#

Отворете Settings → Apps & Connectors → Advanced settings, включете Developer mode и изберете Create connector. Въведете https://api.console.citronos.com/mcp като адрес на MCP сървъра и изберете OAuth за удостоверяване.

Клиенти, които пускат само локални сървъри#

Малък локален stdio сървър, citron-mcp, препраща всяко извикване към отдалечения адрес. Още не е в npm, затова поискайте файла на пакета от нас и никога не инсталирайте пакет с това име от друго място. Приема личен токен чрез --token или в CITRON_MCP_TOKEN, а базовия адрес чрез --base-url или в CITRON_BASE_URL. Изисква Node 20 или по-нова версия.

# Node 20+. Not on npm yet: install the package file we send you
npm install -g ./citron-mcp-0.1.0.tgz

citron-mcp --base-url https://api.console.citronos.com --token cmcp_pat_…

# or with environment variables
CITRON_BASE_URL=https://api.console.citronos.com CITRON_MCP_TOKEN=cmcp_pat_… citron-mcp

Удостоверяване#

Има два вида достъп. OAuth е препоръчителният за клиентите, които го поддържат. Личните токени работят навсякъде другаде.

OAuth 2.1#

Клиентът открива всичко сам. Заявка без токен получава 401 със заглавка WWW-Authenticate, която сочи метаданните на защитения ресурс.

POST /mcp HTTP/1.1
Host: api.console.citronos.com
Content-Type: application/json

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://api.console.citronos.com/.well-known/oauth-protected-resource/mcp"

• Код за оторизация с PKCE. Приема се само методът S256.
• Регистрираните клиенти по подразбиране са публични. Поддържат се и client_secret_post и client_secret_basic.
• Вместо регистрация може да се ползва документ с метаданни на клиента (https адрес като client_id).
• Изпращайте индикатора на ресурса (RFC 8707) resource=https://api.console.citronos.com/mcp.
• Адресите за пренасочване трябва да са https. Обикновен http е разрешен само за localhost, 127.0.0.1 или [::1], на всеки порт. Разрешени са и схеми на приложения, например cursor://….
• Обхватите са mcp:read и mcp:write. Записът включва четене.
• Токените за достъп (cmcp_oat_…) са валидни 1 час. Токените за опресняване (cmcp_ort_…) са валидни 30 дни и се сменят при всяко използване.
• Код за оторизация, използван втори път, отменя всичко, което е издал.

Потребителят одобрява връзката на екран за одобрение в конзолата на Citron (/admin/connect/mcp), влязъл с обичайната си сесия. Там избира работното пространство и Само четене или Четене и запис.

Лични токени#

1. Създайте токенаВ конзолата отворете Настройки → Разработчици → AI конектори и изберете Нов токен.
2. Изберете име, достъп и срокДостъпът е Само четене или Четене и запис. Токенът изтича след 7, 30 или 90 дни, след 1 година или никога.
3. Копирайте го веднагаТокенът (cmcp_pat_…) се показва само веднъж. Citron пази само неговия SHA-256 хеш. Изпращайте го като Authorization: Bearer cmcp_pat_….

В списъка с токени се вижда кога всеки е използван за последно. Можете да отмените всеки от тях по всяко време.

От чие име действа връзката#

И двата вида достъп действат от името на члена на екипа, който ги е създал или одобрил, и само в това работно пространство. Използват текущите му права: промяна на ролята му или премахването му от екипа важи веднага. Нивото на достъп на токена ограничава това, което членът иначе би могъл да направи.

Политиките за записите (правила за полета и записи), ограниченията за достъп до колекции и включените модули важат точно както в конзолата.

Инструменти#

Инструментите са същите като тези на AI асистента в конзолата. Те покриват входящите съобщения и запитванията, формулярите, срещите, колекциите и записите със съдържание, медията, CRM, автоматизациите, таблата и още. Какво вижда клиентът зависи от правата на члена на екипа, модулите на работното пространство и достъпа на токена.

• Инструментите за четене (търсене, четене, обобщаване, заявка към табло) работят с всеки токен.
• Инструментите за запис се показват и изпълняват само с токен с достъп Четене и запис. През MCP записът се прилага веднага, без стъпка за потвърждение в конзолата. Минава през същите услуги като конзолата, записва се в одита и връща actionId. Когато промяната може да се отмени, инструментът undo_change я връща.
• Разрушителните инструменти (изтриване, архивиране, отмяна) изискват и аргумента confirm: true. Без него извикването връща CONFIRMATION_REQUIRED и нищо не се случва. AI трябва да го подава само след като потребителят се е съгласил.
• Промените по сигурността (роли, членове, API ключове, SSO, домейни) изискват ново влизане, затова никога не са достъпни през MCP и връщат UNAVAILABLE_OVER_MCP. Инструментите, които само навигират в конзолата, не се показват.
• Резултатите от инструментите отбелязват данните от записите като недоверени. Важат правилата на асистента за минимум данни: без имейл адреси и телефонни номера, а имена и текст на съобщения само когато работното пространство позволява на AI да чете входящите съобщения и CRM (Настройки → AI).
• Инструментите носят анотациите readOnlyHint и destructiveHint.

Грешки в инструментите#

Неуспешен инструмент връща резултат с isError: true. Текстът му започва с един от тези кодове.

{
  "content": [{ "type": "text", "text": "CONFIRMATION_REQUIRED: …" }],
  "isError": true
}

Ресурси#

Готови подсказки#

HTTP грешки и ограничения#

Адресите за OAuth връщат грешките във вида от RFC, { "error", "error_description" }. Грешките на публичното API са описани в грешки и ограничения.

Одит и отмяна на достъпа#

Всяко извикване на инструмент записва един ред mcp.tool.call в одита: инструментът, дали е успял или кодът на грешката, идентификаторът на токена, OAuth клиентът, нивото на достъп и имената на аргументите. Стойностите на аргументите никога не се записват.

Създаването и отмяната на токени и одобренията през OAuth също се записват, като mcp.token.create, mcp.token.revoke, mcp.oauth.approve, mcp.oauth.deny и mcp.oauth.grant.

Отменете токен или свързано приложение по всяко време в Настройки → Разработчици → AI конектори. Отмяната на OAuth приложение прекратява и неговия токен за опресняване.