MCP Server

Schemix предоставляет MCP-сервер (Model Context Protocol) — стандартный интерфейс для управления платформой через AI-агентов: Claude Code, OpenClaw и любых других MCP-совместимых клиентов.

В отличие от JSON-RPC API (которое требует написания обвязки и явных вызовов), MCP позволяет AI-агенту самостоятельно обнаружить доступные инструменты и использовать их в диалоге с оператором.

---

Endpoint

POST https://api.schemix.ru/mcp/

Транспорт — Streamable HTTP (стандарт MCP). Один endpoint обслуживает все вызовы (initialize, list_tools, call_tool, …).

Аутентификация

MCP использует те же API-ключи, что и JSON-RPC.

Ключ передаётся в одном из двух форматов:

X-API-Key: sk_...

или

Authorization: Bearer sk_...

tenant_id определяется из ключа автоматически — все вызовы выполняются в контексте вашей организации.

---

Подключение

Claude Code

В файле ~/.claude/claude.json (глобально) или .claude/settings.json (в проекте) добавьте секцию mcpServers:

{
  "mcpServers": {
    "schemix": {
      "type": "url",
      "url": "https://api.schemix.ru/mcp",
      "headers": {
        "X-API-Key": "sk_ваш_ключ"
      }
    }
  }
}

Перезапустите Claude Code — сервер появится в /mcp. Проверка:

User: Покажи список процессов в Schemix
Claude: [вызывает process_list] У вас 3 процесса: A1 «Обработка обращений»
        (published), B1 «AI-ассистент» (published), C1 «Классификация» (draft).

OpenClaw

Аналогично — добавьте MCP-коннектор с URL https://api.schemix.ru/mcp и заголовком X-API-Key.

Другие клиенты

Любой MCP-клиент с поддержкой Streamable HTTP. Конфигурация сводится к указанию URL и HTTP-заголовка с API-ключом.

---

Доступные tools

Tool	Описание
process_list	Список определений процессов организации
process_start	Запустить процесс по буквенному коду (A, B, ...)
process_status	Статус запущенного экземпляра
instances_list	Список экземпляров процессов с фильтром
tasks_list	Inbox задач (фильтр по статусу)
task_complete	Завершить Human Task с результатом
conversations_list	Активные диалоги с клиентами
conversation_send	Отправить сообщение в активный диалог
kb_list	Список баз знаний организации
kb_search	Семантический поиск по KB (RAG)
analytics_overview	Сводная аналитика за период (today/week/month)
users_list	Пользователи организации

Параметры и возвращаемые значения

process_list() → list

Возвращает: id, process_id (буквенный), name, status, version, display_id.

process_start(process_id: str, variables: dict | None) → dict

Запускает последнюю опубликованную версию процесса по коду (например "A"). Возвращает: instance_id, status, definition_id, display_id.

process_status(instance_id: int) → dict

Возвращает: id, status, variables, started_at, completed_at, closed_at, closed_by, definition_id, display_id.

instances_list(status: str | None, limit: int = 20) → list

Фильтр по статусу: running, completed, cancelled, terminated. Возвращает: id, definition_id, definition_name, display_id, status, started_at.

tasks_list(status: str | None, limit: int = 20) → list

По умолчанию — активные задачи (pending + in_progress). Возвращает: id, type, status, assignee_id, node_instance_id, created_at, sla_at.

task_complete(task_id: int, result: dict | None) → dict

Завершает Human Task. result — JSON-объект с заполненными полями формы. Возвращает: id, status, completed_at.

conversations_list(status: str | None, limit: int = 20) → list

По умолчанию active. Альтернатива — closed. Возвращает: id, channel, external_chat_id, external_username, status, process_instance_id, created_at, closed_at.

conversation_send(binding_id: int, text: str) → dict

Отправка сообщения клиенту через мессенджер. Возвращает message_id.

kb_list() → list

Активные базы знаний организации с количеством документов. Возвращает: id, name, description, is_active, document_count.

kb_search(query: str, knowledge_base_id: int | None, top_k: int = 5) → list

Семантический поиск (RAG) с агрегацией по всем активным KB, если knowledge_base_id не указан. Возвращает: chunk_id, document_id, kb_id, content, score (0…1), metadata.

analytics_overview(period: str = "week") → dict

Период: today, week, month. Возвращает: period, conversations, tasks, sla, response_time.

users_list(limit: int = 50) → list

Возвращает: id, name, email, role, is_active.

---

Изоляция тенанта

Все tools автоматически отфильтровывают данные по tenant_id, привязанному к API-ключу. Передать tenant_id явно нельзя — это исключает риск случайного доступа к чужой организации.

Получение API-ключа

Администрирование → API-ключи → Создать ключ.

Назначьте ключу необходимые разрешения. Текущая версия MCP-сервера не проверяет permission'ы по отдельным tools — это будет добавлено в следующих версиях. Пока что ключ должен иметь доступ к нужным операциям на уровне организации.

Пример диалога

User:   Какие процессы есть в моём Schemix?
Claude: [process_list]
        У вас 3 процесса: A1 «Обработка обращений» (published),
        B1 «AI-ассистент» (published), C1 «Классификация» (draft).

User:   Запусти процесс A с переменными order_id=123
Claude: [process_start(process_id="A", variables={"order_id": 123})]
        Процесс A1 запущен, instance_id=45, статус running.

User:   Покажи аналитику за неделю
Claude: [analytics_overview(period="week")]
        За неделю: 23 обращения, 18 задач завершено,
        SLA compliance 94%, среднее время ответа 4.2 мин.

User:   Найди в базе знаний информацию про возврат денег
Claude: [kb_search(query="возврат денег", top_k=3)]
        Топ-3 фрагмента: …

---

Совместимость

• MCP протокол: 2024-11-05 и новее (Streamable HTTP).
• Тестовое окружение: Claude Code, OpenClaw.
• Если ваш клиент работает в режиме stdio — MCP-сервер Schemix не подходит, используйте JSON-RPC API напрямую.