# 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-сервер на своём маршруте, поэтому внешний клиент подключает только нужные ему группы инструментов.

**Второй канал — WebMCP внутри страницы.** Отдельно от серверного MCP-интерфейса есть инструменты самой карточки задачи: страница регистрирует их у себя и отдаёт через браузерный интерфейс модели и тестовую точку `window.__1fTools`, без серверного маршрута и без PAT. Работают они от сессии пользователя и только при включённом ключе localStorage `1f.agentTools`; описание — в tasks/webmcp-card.md.

## Возможности

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`:

```json
{
  "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`.

Так же отвечает отказ по пустому телу запроса: параметр тела, объявленный обязательным, но пришедший пустым или отсутствующим, отклоняется до вызова действия с текстом «Тело запроса не может быть пустым». На HTTP-пути то же самое пустое тело у части действий даёт другой ответ, поэтому одинаковый вызов через MCP и напрямую в Admin API может закончиться по-разному. Проверка касается отсутствующего аргумента и явного `null` у ссылочного параметра тела без значения по умолчанию: явно переданные пустой объект `{}` и пустой список `[]` считаются значением и доходят до действия, а значимый nullable-параметр вроде `int?` не блокируется — `null` для него может быть осмысленным. Значение по умолчанию `null` допустимо только там, где действие при таком значении ничего не пишет и не меняет состояние (ранний выход или чистое чтение): если пустое тело может изменить данные, отсутствие аргумента и явный `null` отклоняются до вызова действия. Правило действует на MCP-вызове и не переносится автоматически на HTTP — там привязка модели и фильтры MVC образуют отдельный путь.

## Связанное

- **AI-агент Анфиса** — встроенный в платформу агент (отдельный канал, не MCP): [user-guide.md](https://help.1forma.ru/domains/ai/user-guide.md).