Migrando de uma integração apenas MCP para multitransporte

Visão geral

Mova uma integração do transporte stdio do Model Context Protocol (MCP) para Representational State Transfer (REST) ou gRPC. O comportamento do engine não muda. O catálogo, o modelo de risco e o portão de confirmação continuam os mesmos. Três coisas mudam: o protocolo de comunicação, a autenticação e o modelo de concorrência.

Instalação

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

Visão conceitual

A documentação inicial deste pacote descrevia um único transporte: MCP sobre stdio. O pacote agora expõe o mesmo registro de ferramentas por três transportes. Para migrar, escolha um transporte de rede e, em seguida, mapeie as chamadas MCP para ele. Não é necessário reescrever a lógica do documento.

Escolha o transporte que melhor se adapta à sua implantação:

• Permaneça no MCP quando houver um único agente local, necessidade da menor latência (sem salto de rede) ou um cliente nativo de MCP, como um assistente de IDE local.
• Migre para REST quando você precisar de acesso multicliente com chaves de API por cliente, implantação em contêiner ou Kubernetes, limitação de taxa por cliente, jobs assíncronos ou clientes em qualquer linguagem.
• Migre para gRPC quando você precisar de contratos tipados, streaming de PDFs grandes a partir do servidor e implantações serviço a serviço com TLS mútuo.

Superfície da API

O que permanece igual

• O registro de ferramentas e o catálogo que depende do runtime (consulte /connect/tool-catalog/).
• O modelo de risco de quatro níveis e o portão de confirmação (consulte /connect/hitl-risk-tiers/).
• O modelo de documento e a semântica do engine.

O que muda

Aspecto	MCP (stdio)	REST	gRPC
Formato de comunicação	JSON-RPC 2.0 sobre stdio	JSON sobre HTTP	Protobuf sobre gRPC
Autenticação	nenhuma (subprocesso local)	Authorization: Bearer chave de API	bearer nos metadados da chamada
Concorrência	um processo, uma chamada	pool de workers RoadRunner	pool gRPC RoadRunner
Assíncrono	não se aplica	endpoints de job	RPCs de job
Streaming	não se aplica	corpo síncrono	RPCs com streaming a partir do servidor

Mapeamento de conceitos

Em MCP, uma sequência típica é create_pdf, depois as ferramentas de conteúdo e, então, output_pdf. No REST, isso se torna uma única requisição POST /api/v1/render sem estado, com um array operations ordenado. Quando precisar de estado passo a passo, use os endpoints de sessão opcionais. No gRPC, o equivalente é o RPC Render, ou RenderStream para entrega em blocos. Para builds com estado, use os RPCs CreateSession, SessionOperation e SessionRender.

Sequência de ferramentas MCP	REST	gRPC
create_pdf + ferramentas de conteúdo + output_pdf	POST /api/v1/render	Render / RenderStream
Build com estado entre chamadas	POST /api/v1/sessions (+ ops de sessão)	CreateSession (+ SessionOperation)
Renderização longa	POST /api/v1/jobs e então consultar o resultado	SubmitJob e então GetJobResult
Operação restrita por tier	POST /api/v1/<operation>	ExecuteCapability

Exemplo de código — Início rápido

A chamada MCP:

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

torna-se a requisição 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

Exemplo de código — Produção

Execute os dois transportes durante uma migração em fases. O perfil combinado do RoadRunner serve REST e gRPC a partir de um único supervisor. A integração MCP antiga pode continuar em execução localmente onde ainda for adequada:

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

Não há estado compartilhado a migrar. Os transportes são processos independentes sobre o mesmo engine. Migre os clientes de forma incremental.

Casos extremos e armadilhas

• Adicione autenticação. O transporte MCP não tinha autenticação porque era um subprocesso local. Os transportes de rede exigem uma chave de API válida em toda requisição, exceto as de verificação de integridade. Provisione as chaves antes da transição. Consulte /connect/security-and-operations/.

• O portão de confirmação ainda é acionado. Uma ferramenta com approval_required passa pela verificação em REST e gRPC exatamente como passava em MCP. Leve o fluxo de confirmação para a nova integração. Não presuma que o portão seja exclusivo do MCP. Consulte /connect/hitl-risk-tiers/.

• A restrição por tier permanece inalterada. Uma operação Pro ou Enterprise precisa de nextpdf/premium instalado e de uma chave habilitada no novo transporte, exatamente como a ferramenta correspondente precisava do pacote no MCP.

• A idempotência é nova e útil. O REST adiciona um controle de idempotência que o transporte stdio nunca teve. Use-o para que o envio de jobs possa ser repetido com segurança. Consulte /connect/production-usage/.

Desempenho

O MCP roda em processo único e tem a menor latência para um único agente local. Os transportes de rede adicionam um pool de workers e um salto de rede. Em troca, eles escalam para muitos clientes simultâneos. Encaminhe renderizações longas para o fluxo de jobs assíncronos no novo transporte para que os workers não fiquem ocupados.

Notas de segurança

Migrar do stdio adiciona exposição à rede. Faça a terminação de Transport Layer Security (TLS) na frente do REST, use TLS mútuo para gRPC em redes não confiáveis, restrinja o escopo das chaves por cliente e mantenha enabled_tools no mínimo. O modelo sem credenciais do transporte MCP é seguro apenas porque ele é um subprocesso local. Não recrie essa exposição em uma rede. Consulte /connect/security-and-operations/.

Conformidade

Esta página fornece orientação de migração. As citações de protocolo e autenticação estão fixadas em /transports/mcp/, /transports/rest/, /transports/grpc/ e /connect/security-and-operations/.

Contexto comercial

As operações restritas por tier exigem nextpdf/premium independentemente do transporte. Migrar não altera o que pertence ao core em relação ao Premium. Altera apenas como você acessa o catálogo.

Veja também

• /transports/mcp/ — o transporte do qual você migra
• /transports/rest/ · /transports/grpc/ — os transportes para os quais você migra
• /connect/tool-catalog/ — o catálogo, idêntico entre os transportes
• /connect/hitl-risk-tiers/ — o portão, idêntico entre os transportes
• /connect/security-and-operations/ — a autenticação que você deve adicionar