Notion Developer Platform — API, MCP и кастомные агенты

Notion Developer Platform объединяет командную строку, серверный код и интерфейсы для работы разработчиков и агентов с Notion. В связке с основным Notion API и Notion MCP платформа позволяет синхронизировать внешние данные, автоматизировать процессы внутри Notion, подключать AI-приложения вроде Claude, ChatGPT и Cursor, а также приводить в рабочее пространство внешних агентов, например Codex.

В руководстве собраны актуальные компоненты платформы, способы подключения, практические сценарии и признаки того, что интеграция работает правильно.

Какие компоненты входят в Developer Platform

Официальный состав платформы на 7 сентября 2026 года выглядит так:

Вместе с перечисленными компонентами используются основной Notion API, размещённый сервер Notion MCP и Custom Agents. В интерфейсе Notion можно включить Developer Mode: он показывает идентификаторы страниц, блоков, баз и источников данных, а также открывает доступ к connections, персональным токенам и Workers. Режим доступен в браузере и настольном приложении, но не на мобильных устройствах.

Notion API: страницы, блоки и источники данных

Что доступно через API

REST API позволяет работать со страницами, блоками, базами, источниками данных, комментариями, файлами, пользователями и поиском. Конкретный набор операций зависит от выбранного способа подключения и выданных прав.

В Developer Mode можно открыть connections и персональные токены доступа. Для продукта, который подключается к чужому рабочему пространству, отдельно настройте авторизацию и минимально необходимые права по документации Notion.

Токен передаётся в заголовке:

Authorization: Bearer YOUR_TOKEN

Секрет нельзя помещать в клиентский код, публичный репозиторий или текст страницы. Храните его в переменной окружения или менеджере секретов.

Data Sources и версия API 2025-09-03

Начиная с версии 2025-09-03, база данных рассматривается как контейнер, внутри которого может находиться несколько источников данных (data sources). API /v1/data_sources управляет отдельными источниками и их свойствами, а /v1/databases — контейнером базы.

Старые идентификаторы баз сохранились, но для операций со свойствами нужен идентификатор конкретного data source. Это особенно важно при миграции интеграций, написанных для прежней модели баз данных.

Breaking changes в версии 2026-03-11

Версия 2026-03-11 содержит три несовместимых изменения:

• в Append Block Children параметр after заменён объектом position;
• поле archived удалено из параметров запросов и ответов, вместо него используется in_trash;
• тип блока transcription переименован в meeting_notes.

При обновлении существующей интеграции проверьте формирование позиции новых блоков, логику корзины и обработку блоков заметок о встречах. Для новой интеграции сразу зафиксируйте используемую версию API в заголовке Notion-Version.

Rate limits и повтор запросов

Notion одновременно применяет два ограничения:

• на connection — в среднем три запроса в секунду, с допустимыми краткими всплесками;
• на рабочее пространство — общий лимит всех connections, зависящий от тарифа.

Превышение любого лимита возвращает HTTP 429 и код rate_limited. Причина находится в additional_data.rate_limit_reason.

Обработчик запросов должен также учитывать HTTP 529 с кодом service_overload. Для 429 и 529:

1. прочитайте заголовок Retry-After;
2. остановите новые запросы минимум на указанное число секунд;
3. повторите неудачный запрос;
4. при повторной ошибке 429 или 529 примените экспоненциальную задержку с небольшим случайным смещением;
5. ограничьте число попыток и сохраните финальную ошибку в журнале.

Поставьте исходящие запросы в общую очередь: всплеск от одной задачи не должен исчерпывать бюджет connection. Не создавайте независимый цикл повторов в каждом обработчике, иначе после задержки они могут одновременно дать новый всплеск.

Ограничения размера запроса

Для одного тела запроса действуют такие границы:

• до 1 000 элементов блоков и до 500 КБ на весь payload;
• массивы блоков, включая массивы rich text objects, — до 100 элементов;
• URL — до 2 000 символов;
• text.content одного rich text object — до 2 000 символов.

При превышении лимита API возвращает HTTP 400 с кодом validation_error. Большие операции разбивайте на пакеты до отправки, а не после получения ошибки.

Notion MCP: подключение ИИ-инструментов

Model Context Protocol, или MCP, — протокол, через который совместимый AI-клиент получает инструменты для чтения и изменения данных Notion. Notion предоставляет размещённый MCP-сервер, поэтому пользователю не требуется разворачивать собственный процесс.

Как подключиться

Есть три основных пути:

1. Выбрать приложение в Notion MCP Gallery.
2. Подключить Notion в настройках поддерживаемого клиента, например Claude, ChatGPT или Cursor.
3. Использовать пользовательское MCP-подключение по инструкции для конкретного клиента.

Подключение по пользовательской схеме подходит только клиентам, которые поддерживают MCP. Во время подключения пользователь проходит авторизацию. После этого MCP действует с его правами Notion и может получить доступ ко всему, что доступно этой учётной записи. Поэтому перед выдачей задания проверяйте, какие страницы и базы видит подключённая учётная запись.

На Enterprise-плане администраторы могут включить MCP Governance: разрешить отдельные клиенты, заблокировать остальные и управлять списком на уровне рабочего пространства. Эти правила не отменяют обычные разрешения Notion.

Что проверить после подключения

Минимальная безопасная проверка:

1. Попросите клиента найти тестовую страницу по точному названию.
2. Убедитесь, что результаты и действия соответствуют области доступа тестовой учётной записи, а MCP не открывает страницы, недоступные этой учётной записи.
3. Создайте отдельную тестовую страницу или добавьте безвредный блок, если у подключения есть право на запись.
4. Откройте Notion и проверьте содержимое вручную.
5. Удалите тестовые данные после проверки, если они больше не нужны.

Не начинайте с массового изменения базы. Сначала подтвердите область доступа и формат операций на отдельном объекте.

Workers: код для синхронизаций и автоматизаций

Notion Workers запускают пользовательский код, который связывает Notion с другими системами. Официально заявлены три основных применения:

• автоматизации;
• синхронизация внешних данных с базами Notion;
• пользовательские инструменты для Custom Agents.

Workers находятся в public beta и требуют Business- или Enterprise-план. Создание и управление выполняются через CLI ntn; состояние и журналы можно просматривать в Developer Mode.

Из-за статуса beta перед рабочим внедрением проверьте актуальные команды, доступные среды выполнения и ограничения в документации. Начинайте с тестовой базы и ограниченного набора записей, особенно если Worker меняет существующие данные.

Проверка Worker

У рабочего сценария должен быть наблюдаемый результат:

• синхронизация создала или обновила ожидаемую запись;
• автоматизация отработала на тестовом событии;
• инструмент агента вернул результат без расширения выданных прав;
• в журнале Worker нет необработанной ошибки.

Custom Agents: фоновые командные процессы

Custom Agents работают внутри Notion по инструкциям, расписанию и событиям. Они доступны на Business- и Enterprise-планах и предназначены для общих процессов команды.

Триггеры и доступ

Агент может запускаться:

• по расписанию;
• при добавлении комментария;
• при добавлении или удалении страницы из базы;
• при изменении свойства;
• после завершения AI Meeting Note;
• по событиям Slack, если интеграция настроена администратором.

Доступ к страницам, базам и внешним приложениям задаётся отдельно в Tools and access. Ссылка на страницу в инструкциях сама по себе не выдаёт агенту доступ. Веб-доступ также включается отдельным переключателем.

Custom Agent может передать часть работы другому агенту, если тот добавлен в список доступных инструментов. Такое разделение полезно для процессов с разными правами или контекстом, но каждая передача расходует кредиты и усложняет проверку результата.

Как отлаживать агента

У Custom Agents есть вкладка Activity, содержащая журнал запусков. По справке Notion, этот журнал виден пользователям с Full Access; в нём указаны источник запуска, выполненные действия, ошибки и объяснения неудачного запуска. Конфигурацию можно проверять во вкладках Chat и Settings, а прежнюю версию — восстановить через version history.

Практический цикл проверки:

1. Запустите агента вручную на тестовой записи.
2. Проверьте изменения страницы или базы.
3. Откройте Activity и изучите действия и ошибки.
4. Уточните инструкции, фильтры триггера или область доступа.
5. Повторите тест до публикации агента для команды.

External Agents API и Agent SDK решают разные задачи

External Agents API добавляет внешнего агента в рабочее пространство. Такой агент отображается как Custom Agent: с ним можно общаться, назначать ему работу и отслеживать выполнение. API находится в private beta.

Agent SDK работает в обратном направлении: внешняя система программно запускает Custom Agent. Например, CRM может инициировать подготовку сводки на основе страниц Notion. SDK находится в private alpha.

Обе возможности требуют раннего доступа. Не закладывайте их в критический рабочий процесс без подтверждённого доступа и плана на изменение интерфейсов.

Полезные сценарии

Личный помощник с доступом к Notion

Задача: искать документацию и обновлять рабочие страницы из Claude, ChatGPT или Cursor.

Подключите Notion MCP, выдайте доступ через нужную учётную запись и начните с тестовой страницы. Результат проверяется поиском по точному названию и появлением ожидаемого блока в Notion. Сценарий не подходит, если клиент не поддерживает MCP или политика организации запрещает такое подключение.

Триаж обратной связи

Задача: автоматически обрабатывать новые записи в базе обратной связи.

Создайте Custom Agent с триггером добавления страницы, дайте ему доступ только к нужной базе и опишите требуемые поля результата. После тестового запуска проверьте заполненные свойства и запись в Activity. Для чувствительных данных ограничьте доступ агента минимальным набором страниц и приложений.

Синхронизация внешней системы

Задача: переносить записи из CRM или другого сервиса в базу Notion.

Используйте Worker для синхронизации и сначала направьте результат в тестовую базу. Успех подтверждается ожидаемыми записями и отсутствием необработанных ошибок в журнале. Для процесса с минимальной задержкой заранее проверьте доступные режимы запуска и задержки текущей beta-версии.

Ограничения, которые влияют на архитектуру

• API требует очереди, обработки Retry-After и ограниченного числа повторов.
• Большие payload нужно заранее делить на пакеты.
• MCP действует с правами подключённого пользователя, поэтому ошибка в задании может затронуть все доступные ему данные.
• Custom Agents используют только явно предоставленные ресурсы, но доступ к общим страницам может сделать область работы широкой.
• Workers, External Agents API и Agent SDK остаются beta- или alpha-компонентами.
• Для Custom Agents доступны журналы активности, однако качество отладки зависит от точности инструкций, триггеров и выданного доступа.

Официальные источники

• Обзор Notion Developer Platform
• Изменения API по версиям
• Лимиты запросов Notion API
• Подключение Notion MCP
• Настройка Custom Agents

Следующий шаг

Notion MCP — официальный сервер Notion для подключения ИИ-агентов

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

Если захотите обсудить, как это применить у себя или в команде — пишите в Telegram @pimenov