Переход с MCP на несколько транспортов

Кратко

Перенесите интеграцию со stdio-транспорта протокола Model Context Protocol (MCP) на Representational State Transfer (REST) или gRPC. Поведение движка не меняется. Каталог, модель рисков и шлюз подтверждения остаются прежними. Меняются только три вещи: сетевой протокол, аутентификация и модель параллелизма.

Установка

composer require nextpdf/server
./vendor/bin/rr get-binary

Концептуальный обзор

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

Выберите транспорт, подходящий для вашего развёртывания:

• Оставайтесь на MCP, если у вас один локальный агент, важна минимальная задержка (без сетевого перехода) или есть клиент с нативной поддержкой MCP, например локальный ассистент в IDE.
• Перейдите на REST, если нужен доступ для нескольких клиентов с отдельным ключом API для каждого, развёртывание в контейнерах или Kubernetes, ограничение частоты запросов для каждого клиента, асинхронные задания или клиенты на любом языке.
• Перейдите на gRPC, если нужны типизированные контракты, потоковая передача больших PDF с сервера и межсервисные развёртывания с взаимным TLS.

Состав API

Что остаётся неизменным

• Реестр инструментов и каталог, зависящий от среды выполнения (см. /connect/tool-catalog/).
• Четырёхуровневая модель рисков и шлюз подтверждения (см. /connect/hitl-risk-tiers/).
• Модель документа и семантика движка.

Что меняется

Аспект	MCP (stdio) транспорт	REST	gRPC
Формат передачи	JSON-RPC 2.0 поверх stdio	JSON поверх HTTP	Protobuf поверх gRPC
Аутентификация	отсутствует (локальный подпроцесс)	ключ API Authorization: Bearer	bearer-токен в метаданных вызова
Параллелизм	один процесс, один вызов	пул воркеров RoadRunner	gRPC-пул RoadRunner
Асинхронность	неприменимо	эндпоинты заданий	RPC для заданий
Потоковая передача	неприменимо	синхронное тело	RPC с серверной потоковой передачей

Сопоставление понятий

Типичная последовательность MCP: create_pdf, затем инструменты для содержимого, затем output_pdf. В REST ей соответствует один запрос POST /api/v1/render без сохранения состояния с упорядоченным массивом operations. Если требуется пошаговое сохранение состояния, используйте вместо этого подключаемые эндпоинты сеансов. В gRPC эквивалентом является RPC Render или RenderStream для доставки по частям. Для сборки с сохранением состояния используйте RPC CreateSession, SessionOperation и SessionRender.

Последовательность инструментов MCP	REST	gRPC
create_pdf + инструменты для содержимого + output_pdf	POST /api/v1/render	Render / RenderStream
Сборка с сохранением состояния между вызовами	POST /api/v1/sessions (+ операции сеанса)	CreateSession (+ SessionOperation)
Длительная отрисовка	POST /api/v1/jobs, затем опрос результата	SubmitJob, затем GetJobResult
Операция, ограниченная по тарифу	POST /api/v1/<operation>	ExecuteCapability

Пример кода — быстрый старт

Вызов MCP:

{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"add_text","arguments":{"text":"Hello"}}}

превращается в REST-запрос:

curl -sS -X POST http://localhost:8080/api/v1/render \
  -H "Authorization: Bearer $NEXTPDF_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"operations":[{"type":"add_text","text":"Hello"}]}' \
  --output hello.pdf

Пример кода — продакшен

Запускайте оба транспорта во время поэтапного перехода. Объединённый профиль RoadRunner обслуживает REST и gRPC из одного супервизора. Прежняя интеграция MCP может продолжать локально работать там, где она всё ещё уместна:

export NEXTPDF_API_KEYS_FILE=/run/secrets/api-keys
./vendor/bin/rr serve -c .rr.full.yaml

Общего состояния, которое нужно переносить, нет. Транспорты — это независимые процессы поверх одного и того же движка. Переводите клиентов постепенно.

Граничные случаи и подводные камни

• Добавьте аутентификацию. У транспорта MCP её не было, поскольку он был локальным подпроцессом. Сетевые транспорты требуют действительного ключа API для каждого запроса, кроме проверок работоспособности. Подготовьте ключи до переключения. См. /connect/security-and-operations/.

• Шлюз подтверждения по-прежнему срабатывает. Инструмент approval_required запрашивает подтверждение в REST и gRPC точно так же, как в MCP. Перенесите процесс подтверждения в новую интеграцию. Не считайте, что шлюз действует только в MCP. См. /connect/hitl-risk-tiers/.

• Ограничение по тарифу не изменилось. Операции уровня Pro или Enterprise требуют установленного пакета nextpdf/premium и ключа с соответствующими правами на новом транспорте — так же, как этот пакет требовался соответствующему инструменту в MCP.

• Идемпотентность — новая полезная возможность. REST добавляет управление идемпотентностью, которого никогда не было у транспорта stdio. Используйте её, чтобы повторная отправка задания была безопасной. См. /connect/production-usage/.

Производительность

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

Примечания по безопасности

Переход со stdio добавляет сетевую поверхность атаки. Завершайте Transport Layer Security (TLS) перед REST, используйте взаимный TLS для gRPC в недоверенных сетях, ограничивайте область действия ключей для каждого клиента и сохраняйте список enabled_tools минимальным. Модель транспорта MCP без учётных данных безопасна только потому, что он работает как локальный подпроцесс. Не воспроизводите такую модель в сети. См. /connect/security-and-operations/.

Соответствие

Эта страница содержит рекомендации по переходу. Ссылки по протоколам и аутентификации приведены на страницах /transports/mcp/, /transports/rest/, /transports/grpc/ и /connect/security-and-operations/.

Коммерческий контекст

Операции, ограниченные по тарифу, требуют nextpdf/premium независимо от транспорта. Переход не меняет, что относится к базовой версии, а что — к Premium. Он меняет только способ обращения к каталогу.

См. также

• /transports/mcp/ — транспорт, с которого вы переходите
• /transports/rest/ · /transports/grpc/ — транспорты, на которые вы переходите
• /connect/tool-catalog/ — каталог, одинаковый для всех транспортов
• /connect/hitl-risk-tiers/ — шлюз, одинаковый для всех транспортов
• /connect/security-and-operations/ — аутентификация, которую необходимо добавить