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

Notion долго оставался «закрытым» продуктом: данные внутри, интеграции через сторонние сервисы. В мае 2026 года появился Developer Platform — полноценная инфраструктура для разработчиков. Внутри: API, MCP-сервер для ИИ-агентов, Workers для серверного кода, Custom Agents со скриптовой песочницей и внешние агенты как участники воркспейса.

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

Что входит в Notion Developer Platform

Платформа состоит из пяти частей, каждая из которых решает свой класс задач:

Всё это объединяется CLI-инструментом ntn, через который можно создавать проекты, деплоить Workers и управлять конфигурацией.

Notion API: фундамент платформы

Что можно делать

REST API покрывает практически все операции с воркспейсом:

• Страницы — создание, чтение, обновление, удаление, архивация
• Базы данных — управление схемой, data sources, свойствами
• Блоки — работа с контентом страниц на уровне отдельных блоков
• Пользователи — получение списка и информации о членах воркспейса
• Комментарии — создание и чтение дискуссий на страницах
• Поиск — полнотекстовый поиск по воркспейсу

Авторизация

API поддерживает три типа токенов:

1. Internal connection — бот с фиксированным набором прав, привязанный к конкретному воркспейсу. Самый простой вариант для внутренних инструментов
2. Public connection — OAuth-интеграция для продуктов, которые подключаются к чужим воркспейсам
3. Personal Access Token (PAT) — токен, который действует от имени конкретного пользователя

Токен передаётся в заголовке Authorization: Bearer {TOKEN} с каждым запросом. При использовании JavaScript SDK токен задаётся один раз при инициализации клиента.

Rate limits

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

• На подключение (интеграцию) — в среднем 3 запроса в секунду, с короткими всплесками выше среднего
• На воркспейс — общий для всех подключений воркспейса, масштабируется в зависимости от тарифа

Это не жёсткий лимит в реальном времени: можно отправить пачку запросов за секунду, но потом нужно замедлиться. При превышении любого из лимитов приходит ошибка rate_limited и HTTP 429, а в поле rate_limit_reason указано, какой лимит сработал.

Практические ограничения, о которых важно знать:

• Создание страницы — не более 1 000 блоков за один запрос
• Массив блоков — не более 100 элементов
• Размер запроса — до 500 КБ
• Вложенность блоков при создании — до 2 уровней

При ответе 429 Too Many Requests стоит реализовать экспоненциальный backoff или использовать очередь с задержкой.

Data Sources — новая абстракция

С версии API 2025-09-03 появился объект Data Source. Раньше свойства (properties) были на уровне базы данных, теперь — на уровне data source. Одна база данных может содержать несколько data sources. Это важно для интеграций, которые подключают внешние данные в Notion-базу.

Следующая версия API — 2026-03-11 — добавила ещё три breaking change: изменилось добавление дочерних блоков (параметр after), поменялась семантика архивации и корзины (поле archived) и появился новый тип блока transcription. Если пишете интеграцию с нуля, берите за основу 2026-03-11; при апгрейде существующей — проверьте эти три места.

Notion MCP: мост между ИИ-агентами и воркспейсом

Что такое MCP

Model Context Protocol — открытый стандарт, который позволяет ИИ-инструментам взаимодействовать с внешними сервисами через единый протокол. Notion предоставляет hosted MCP-сервер — не нужно ничего поднимать самостоятельно.

Схема простая:

• MCP-клиент (Claude Code, Cursor, VS Code, ChatGPT) отправляет запросы
• Notion MCP Server принимает запросы и выполняет операции через Notion API
• Пользователь управляет правами доступа через настройки интеграции

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

Notion рекомендует подключаться к удалённому hosted-серверу — не нужно возиться с токенами и JSON. В большинстве клиентов (Claude, ChatGPT, Cursor, VS Code) достаточно выбрать Notion в списке интеграций и пройти авторизацию через OAuth. Если клиент не из списка, но поддерживает MCP, укажите адрес сервера напрямую:

• Streamable HTTP (рекомендуется): https://mcp.notion.com/mcp
• SSE (для более старых клиентов): https://mcp.notion.com/sse

Локальный open-source сервер (@notionhq/notion-mcp-server) тоже существует, но постепенно уходит на второй план — Notion поддерживает именно удалённый вариант и не исключает, что локальный репозиторий со временем закроют. Если он всё-таки нужен, конфиг выглядит так:

{
  "mcpServers": {
    "notion": {
      "command": "npx",
      "args": ["-y", "@notionhq/notion-mcp-server"],
      "env": {
        "NOTION_TOKEN": "ваш_токен",
        "OPENAPI_MCP_HEADERS": "{\"Authorization\": \"Bearer ваш_токен\", \"Notion-Version\": \"2026-03-11\"}"
      }
    }
  }
}

После подключения ИИ-ассистент может:

• Искать страницы и базы данных в воркспейсе
• Создавать и редактировать страницы
• Работать со свойствами и содержимым баз данных
• Читать комментарии и дискуссии

Когда это полезно

• Кодинг с контекстом — Claude Code или Cursor читают техническую документацию из Notion и обновляют статусы задач
• Автоматизация контента — ИИ создаёт черновики страниц на основе данных из баз
• Анализ данных — агент извлекает данные из Notion-баз, анализирует и записывает результаты

С версии 2.0.0 MCP-сервер перешёл на API 2025-09-03 с поддержкой data sources. А инструменты чтения и правки страниц в Markdown (retrieve-page-markdown, update-page-markdown) работают через версию 2026-03-11 — сервер сам подставляет нужную версию под каждую операцию.

Notion Workers: серверный код без серверов

Концепция

Workers — это TypeScript-программы, которые Notion хостит и запускает в изолированной среде (Vercel Sandbox). Один Worker — один файл src/index.ts, в котором регистрируются «возможности» (capabilities).

Три типа capabilities:

Syncs — синхронизация данных

Синки забирают данные из внешних API (Salesforce, Stripe, GitHub, любой REST API) и записывают их в Notion-базы по расписанию (по умолчанию каждые 30 минут). Notion сам управляет схемой базы данных — вы описываете её в коде:

import { Worker } from "@notionhq/workers";

const worker = new Worker();
export default worker;

worker.sync("customersSync", {
  database: {
    properties: {
      name: { type: "title" },
      email: { type: "email" },
      plan: { type: "select", options: ["free", "pro", "enterprise"] },
    },
  },
  async execute({ pacer }) {
    const customers = await pacer.fetch("https://api.example.com/customers");
    return { records: customers, hasMore: false };
  },
});

Tools — инструменты для Custom Agents

Tools делают Custom Agents по-настоящему мощными. Вы пишете функцию, агент вызывает её по запросу пользователя. Пример: агент просит «создай тикет в Jira» — Tool обращается к Jira API и возвращает результат. Схема входных параметров описывается билдером j из @notionhq/workers, а логика — в функции execute.

worker.tool("createJiraTicket", {
  title: "Create Jira ticket",
  description: "Creates a Jira ticket",
  schema: j.object({
    summary: j.string().describe("Ticket title"),
    priority: j.string().describe("Priority: high, medium or low"),
  }),
  async execute({ summary }) {
    const response = await fetch("https://your-org.atlassian.net/rest/api/3/issue", {
      method: "POST",
      body: JSON.stringify({ fields: { summary } }),
    });
    return { ticketUrl: response.url };
  },
});

Webhooks — приём внешних событий

Workers принимают HTTP-события от GitHub, Stripe, Zendesk и любых сервисов, поддерживающих вебхуки. При событии выполняется ваш обработчик, который может создать или обновить страницы в Notion.

Деплой и жизненный цикл

# Установка CLI
curl -fsSL https://ntn.dev | bash

# Создание проекта
ntn workers new my-worker
cd my-worker

# Деплой
ntn workers deploy

# Тестирование
ntn workers exec sayHello -d '{"name": "World"}'

Workers работают в песочнице Node.js. Доступны HTTP-запросы, секреты (переменные окружения через CLI), OAuth-авторизация для сторонних сервисов и встроенный Pacer для rate-limiting исходящих запросов.

Во время бета-периода Workers бесплатны — кредиты начинают списываться с 11 августа 2026 года. Сами Workers дешевле агентов: около 0,0023 доллара за один запуск (примерно 4 300 запусков на 1 000 кредитов), потому что платят за фактическую работу, а не за «думанье» модели. После — $10 за 1 000 кредитов, общих с Custom Agents.

Custom Agents: ИИ-автоматизация внутри Notion

Что умеют

Custom Agents — это ИИ-агенты, которые живут в воркспейсе и работают автоматически. Они отличаются от персонального Notion Agent тем, что предназначены для командных workflow и запускаются по триггерам.

Агент состоит из:

• Instructions — страница с инструкциями, которая определяет поведение агента
• Connections — подключения к данным и сервисам (Notion-страницы, базы данных, MCP-серверы, Slack, Google Drive и другие)
• Triggers — условия запуска (создание/обновление страницы в базе, расписание, нажатие кнопки, упоминание агента)

Scripting Sandbox

Внутри Custom Agents работает скриптовая песочница — изолированная среда, где агент может выполнять SQL-запросы к базам данных, вызывать функции для работы со страницами, отправлять уведомления и делать запросы к внешним API через MCP-инструменты.

Файл AGENTS.md — стандартная точка входа для конфигурации агентов в кодовых проектах. Тот же паттерн, который используют Claude Code и Codex для чтения контекста проекта. Notion адаптировал его для инструкций агентов внутри воркспейса.

Memories и стилевые инструкции

Агентам можно подключать страницы-инструкции с разными ролями:

• Memories — накопленный контекст: решения, предпочтения, важные факты. Агент читает их при каждом запуске и учитывает
• Стилевые инструкции — требования к формату, тону и структуре выходных данных
• Базы знаний — коллекции страниц, по которым агент может искать информацию

Autofill-агенты

Отдельный подтип — автозаполнение свойств в базах данных. Агент привязывается к конкретной базе и может массово заполнять определённые свойства на основе содержимого страниц или данных из подключений.

Пример: агент для триажа обратной связи

1. Создаёте базу с колонками: Feedback, Source, Priority, Category, Action
2. Настраиваете агент с триггером «при создании страницы в базе»
3. В инструкциях описываете логику: анализировать текст, определить приоритет по ключевым словам, категоризировать, предложить действие
4. Агент автоматически обрабатывает каждую новую запись

External Agents и Agent API

External Agents — это возможность привести в Notion агентов, построенных на других фреймворках. Claude, Codex, Decagon или ваш собственный агент появляются в списке агентов воркспейса как полноценные участники.

Для разработчиков доступен Notion Agents SDK (JavaScript/TypeScript, private alpha), который позволяет:

• Создавать треды и отправлять сообщения от имени агента
• Получать стриминговые ответы
• Работать в контексте внутренних интеграций

External Agents доступны в режиме private beta (по waitlist), но это ключевая часть стратегии Notion: воркспейс как единое пространство, где люди и агенты работают вместе с общими данными.

Notion CLI — ntn

CLI объединяет всё управление платформой в одном инструменте:

# Установка
curl -fsSL https://ntn.dev | bash

# Создание Worker-проекта
ntn workers new my-sync

# Деплой
ntn workers deploy

# Управление секретами
ntn workers secrets set API_KEY=sk-...

# Выполнение инструмента
ntn workers exec toolName -d '{"param": "value"}'

Ограничения и подводные камни

API

• Rate limit 3 req/s — для массовых операций нужна очередь с backoff
• Максимум 1 000 блоков при создании страницы, 100 элементов в массиве, 500 КБ на запрос
• Вложенность блоков при создании — не более 2 уровней
• Некоторые типы блоков (кнопки, синхронизированные блоки) имеют ограниченную поддержку

Workers

• Работают только с TypeScript/JavaScript
• Песочница эфемерная — постоянной файловой системы нет, долгоживущие процессы не поддерживаются
• В beta-периоде возможны изменения API
• Sync по умолчанию запускается каждые 30 минут (настраивается от 1 минуты до 7 дней, есть режимы continuous и manual) — для настоящего real-time всё равно не идеальный вариант

Custom Agents

• Доступны только на тарифах Business и Enterprise
• Потребляют AI-кредиты
• Не могут выполнять действия за пределами подключённых данных
• Scripting sandbox ограничен набором модулей — нельзя подключить произвольные npm-пакеты
• Отладка затруднена: нет логов в привычном смысле, приходится проверять результаты работы

MCP

• Привязан к тому же rate limit Notion API
• Не все MCP-клиенты поддерживают remote-серверы — некоторые работают только с локальными
• OAuth-авторизация может быть неочевидной при настройке

Что строить на этой платформе

Если вы solo-пользователь: подключите Notion MCP к Claude Code или Cursor — ИИ-ассистент сможет читать и обновлять ваш воркспейс через естественный язык.

Если вы в команде на Business-плане: начните с Custom Agents для типовых задач — триаж обратной связи, еженедельные отчёты, обновление статусов.

Если вы разработчик: Workers дают серверную логику без инфраструктуры. Sync для интеграции данных, Tools для расширения агентов, Webhooks для реакции на внешние события.

Если вы строите продукт на Notion: External Agent API (когда выйдет из waitlist) позволит встроить вашего агента прямо в воркспейсы клиентов.

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

По теме

• Статья: Как я собрал команду из трёх ИИ-агентов и автоматизировал разработку через Notion
• Блог: Notion открыла платформу для разработчиков — CLI, Workers и агентный SDK
• База знаний: Notion MCP — официальный сервер Notion для подключения ИИ-агентов

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

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