# MCP

Единственный адрес подключения: `https://mcp.kvantora.ai/mcp`. Это production MCP поверх stateless Streamable HTTP. Клиент передаёт `Authorization: Bearer <ключ>` и `Accept: application/json, text/event-stream`. GET и DELETE `/mcp` возвращают 405. `https://mcp.kvantora.ai/mcp/status` показывает доступность и инструменты этого ключа. Отдельного адреса или режима подключения для неопубликованных объектов нет.

Подключения создаются в общем кабинете `/app/mcp`: имя клиента, выбранные права, срок и дневной бюджет. Для каждого клиента создавайте отдельный ключ — его можно отозвать независимо от остальных. Секрет передаётся только в заголовке Authorization, не в URL.

Для чтения используйте отдельные права `mcp:models:read`, `mcp:balance:read`, `mcp:usage:read`, `mcp:storage:read`, `mcp:jobs:read`. Прежнее `mcp:read` сохраняет доступ к чтению API. Для text_generate/media_generate нужен обычный API-ключ с mcp:invoke и правом нужной операции. Старый MCP token не разрешает генерацию и автоматически не получает права на автоматизации.

Инструменты чтения: models_search, model_details, balance_get, usage_summary, routing_status, storage_list, storage_read, job_status. Storage возвращает только файлы владельца, а ссылки имеют срок до 5 минут. Storage_list принимает limit и after.

Text_generate принимает model, prompt, max_tokens и обязательный idempotency_key. Media_generate принимает operation, model, prompt/input/file_id, max_cost_microrub и idempotency_key. Они вызывают тот же адрес API, который доступен напрямую через API, и используют общий бюджет ключа.

Если администратор включил MCP автоматизаций, этот же адрес предоставляет инструменты `ap_*`. Получайте их актуальные названия и схемы через `tools/list`. Доступ проверяется также при каждом вызове, включая прямой вызов инструмента, отсутствующего в списке.

| Право | Действия |
| --- | --- |
| `mcp:automations:read` | Сценарии, интеграции, подключения без секретов, таблицы и история |
| `mcp:automations:develop` | Создание и изменение сценариев, шагов, ветвлений, создание из шаблона |
| `mcp:automations:run` | Тесты сценариев и действий, динамические параметры; возможны внешние эффекты и расходы |
| `mcp:automations:publish` | Публикация, включение и отключение |
| `mcp:automations:data` | Изменение таблиц и удаление объектов |

Изменяющие команды требуют `idempotency_key`. Для изменений существующего сценария передавайте `expected_revision` из последнего чтения; для таблиц — `expected_table_revision`. При конфликте прочитайте объект снова и подготовьте новую команду. При сетевой ошибке сохраняйте прежний ключ команды: новый ключ может создать вторую операцию.

Длительная команда возвращает `operation_id`. Проверяйте её через `automation_operation_status`. Статус `needs_reconciliation` означает неизвестный исход: сначала сверьте историю и результат, не запускайте платное действие заново автоматически.

Подключения бизнес-сервисов выбираются по идентификаторам из `ap_list_connections`; сохранённые пароли и токены агенту не выдаются. Для AI используется управляемое подключение Kvantora и каталог Kvantora (`ap_list_ai_models`). Прямые генерации расходуют бюджет клиентского API-ключа; сценарии — лимиты автоматизаций и управляемого ключа. Баланс организации общий.

Когда платформа ИИ-сотрудников включена для организации, этот же production MCP предоставляет инструменты `agent_*`. `agent_list` и `agent_get` охватывают активных, архивных и ещё не опубликованных сотрудников текущего проекта. `agent_update` позволяет корректировать каждый из этих статусов при совпадении `revision`. `agent_create` требует `idempotency_key`, а повтор с тем же ключом и данными возвращает того же сотрудника. Для активации новой конфигурации Core требует успешную проверку именно этой конфигурации через `agent_run_test`, затем отдельный `agent_publish`. Это внутренний защитный этап, не другой вариант MCP-подключения.

| Право | Действия с ИИ-сотрудниками |
| --- | --- |
| `mcp:agents:read` | Шаблоны, модели, возможности, список и конфигурации всех статусов, статус собственной проверки |
| `mcp:agents:develop` | Создание и корректировка конфигурации с проверкой версии |
| `mcp:agents:run` | Проверка с возможным расходом баланса; выдавайте это право только доверенному клиенту |
| `mcp:agents:publish` | Публикация прошедшей проверку конфигурации |
| `mcp:agents:data` | Архивирование, восстановление и удаление; удаление доступно только owner/admin |

Перед изменением вызовите `agent_get` и передайте полученную `revision`. После сетевой ошибки проверьте `agent_test_status` или `agent_run_status`, не запускайте платную проверку автоматически повторно с новым идентификатором. Набор видимых инструментов зависит от прав ключа, feature flag и текущего доступа его создателя; действующие права перепроверяются при вызове.

Для подключения нужен Bearer-ключ. OAuth и подключение без ключа только по ссылке не поддерживаются. Доступность инструментов автоматизаций проверяйте через `tools/list`; отсутствие Kvantora Flow не отключает инструменты моделей.

```javascript
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
const client = new Client({name: 'kvantora-production-example', version: '1.0.0'});
await client.connect(new StreamableHTTPClientTransport(
  new URL('https://mcp.kvantora.ai/mcp'),
  {requestInit: {headers: {Authorization: 'Bearer ' + process.env.KVANTORA_API_KEY}}}
));
console.log(await client.listTools());
console.log(await client.callTool({name: 'balance_get', arguments: {}}));
await client.close();
```

Для примера используйте `@modelcontextprotocol/sdk` версии `1.30.0`. Ваш MCP-клиент должен поддерживать Streamable HTTP и передачу заголовка Authorization.