MCP в 1Форме

1Форма экспонирует свой функционал внешним AI-агентам через Model Context Protocol (MCP) — открытый протокол, по которому LLM-ассистенты (Claude Desktop, Dify и др.) обращаются к инструментам платформы. Через MCP внешний агент управляет задачами, конфигурацией, автоматизацией и данными 1Формы на естественном языке пользователя. Документ описывает назначение MCP-интерфейса, состав возможностей и подключение внешних клиентов. Для интеграторов, разработчиков MCP-инструментов и продакт-менеджеров.

Что такое MCP-интерфейс 1Формы

MCP-сервер 1Формы — это слой, который превращает API и действия платформы в набор инструментов (tools), понятных внешним AI-ассистентам. Агент, подключённый по MCP, видит каталог доступных инструментов с описаниями и схемами параметров и вызывает их, переводя запрос пользователя на естественном языке в конкретные действия с платформой.

Это отдельный канал, который не следует путать со встроенным агентом Анфисой: Анфиса работает внутри платформы, а MCP-интерфейс подключает к платформе внешний AI-инструмент. Реализован как multi-server: каждый набор возможностей — отдельный MCP-сервер на своём маршруте, поэтому внешний клиент подключает только нужные ему группы инструментов.

Возможности

MCP-интерфейс сгруппирован по областям — каждая представлена отдельным MCP-сервером:

Область	Назначение
Администрирование	Управление конфигурацией: разделы и категории, дополнительные параметры (ДП) — создание, дерево разделов, привязка типов
Пользовательские данные	Работа с задачами, комментариями, лентами как обычный пользователь — обёртка над пользовательским API платформы
Отборы данных	Получение данных через механизм отборов на естественном языке («задачи из категории X, где исполнитель — я»)
Smart Actions	Вызов стандартных действий автоматизации (~200 действий в ~20 группах: задачи, статусы, исполнители, комментарии, файлы, подписи, ДП, сообщения и др.)
Динамические инструменты	SmartScripts, настроенные в БД, автоматически становятся инструментами агента (набор обновляется на лету)
Логи	Анализ логов ошибок и автоматизации для диагностики (ExceptionsLog, AutomationScriptsLog)
Формы администрирования	CRUD по формам автоадминки (list, schema, data, insert, update, delete)

Доступ к административным, логовым и динамическим инструментам требует прав администратора. Пользовательские инструменты работают в рамках стандартной авторизации контроллера и прав конкретного пользователя — внешний агент не получает доступа сверх прав той учётной записи, от чьего имени работает.

Подключение внешних клиентов

Внешний AI-клиент подключается к MCP-серверу по HTTP с авторизацией через персональный токен (PAT) и идентификатор пользователя, от чьего имени выполняются действия.

Claude Desktop — через mcp-remote (npx). Пример конфигурации mcpServers:

{
  "mcpServers": {
    "1forma": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://<instance>/mcp-admin",
        "--header", "1F-Pat: <token>",
        "--header", "1f-real-user-id: <userId>"
      ]
    }
  }
}

Авторизация: - 1F-Pat — персональный токен (генерируется через /api/admin/pat/generate); - 1f-real-user-id — ID пользователя, в правах которого работает агент.

Другие клиенты (например, Dify) подключаются по тому же HTTP-протоколу. При самоподписанном сертификате на стенде клиенту может потребоваться отключить проверку TLS на своей стороне.

Авторизация по типу стенда. Заголовок авторизации зависит от площадки:

• HD/dev — 1F-Pat (PAT создаётся в профиле: ru.1forma.ru → Профиль → Токены → Создать, либо через /api/admin/pat/generate).
• Клиентская площадка — 1FormaAuth с JWT: сначала POST /api/auth/token-v2 с логином и паролем, затем заголовок 1FormaAuth: <jwt>. PAT с HD на клиентских стендах не работает — там своя база пользователей.

Заголовок 1f-real-user-id в обоих случаях задаёт пользователя, в правах которого работает агент.

Версия и порядок подключения. Discovery-сервер /mcp и его полный live-каталог GET /mcp/detailed-description доступны с версии платформы 2.268 (доступность уточняйте на конкретном стенде). Подключать весь каталог сразу не нужно: сначала подключить /mcp, взять из live-каталога список серверов и схему нужного инструмента, затем подключить только выбранный сервер. Назначение сервера по имени маршрута не угадывать — оно берётся из live-каталога (например, чтение задач и создание задачи опубликованы на разных серверах).

Каталог инструментов и справка

Корневой сервер (маршрут /mcp) предоставляет реестр всех подключённых серверов и инструмент get_tool_info — справку по любому инструменту из всех зарегистрированных серверов (имя, описание, параметры, серверный маршрут). При совпадении имён на нескольких серверах вызывающий уточняет нужный через serverPath.

Описания инструментов и схемы параметров генерируются автоматически из сигнатур методов и XML-документации контроллеров — внешнему клиенту не нужно обращаться к коду платформы, чтобы сформировать корректный вызов.

Помимо описаний и схем, инструменты передают клиенту аннотации readOnlyHint и destructiveHint (поле annotations в ответе tools/list) — они сообщают о природе инструмента: только чтение или изменение данных и является ли изменение разрушительным. Для инструментов на основе контроллеров признак выводится из HTTP-метода (GET — только чтение, DELETE — разрушительное изменение), для объявленных в коде тулов — из явных атрибутов ReadOnly / Destructive. MCP-клиент (например, Claude) использует эти подсказки, чтобы безопаснее обращаться с write- и destructive-инструментами — например, запрашивать подтверждение.

Ошибки вызова. Обращение к несуществующему инструменту (или к существующему, но по чужому маршруту) и вызов без обязательного аргумента возвращаются типизированным отказом — CallToolResult с IsError = true, а не серверной ошибкой; клиент должен обрабатывать такой ответ штатно. Настоящие серверные сбои и отказы авторизации отдаются иначе (пробрасываются). Чтобы не ошибиться с именем и обязательными параметрами, сверяйтесь с tools/list и get_tool_info.

Связанное

• AI-агент Анфиса — встроенный в платформу агент (отдельный канал, не MCP): user-guide.md.