Migrasi dari hanya MCP ke multi-transport

Sekilas

Migrasikan integrasi dari transport stdio Model Context Protocol (MCP) ke Representational State Transfer (REST) atau gRPC. Perilaku mesin tidak berubah. Katalog, model risiko, dan gerbang konfirmasi tetap sama. Tiga hal yang berubah: protokol wire, autentikasi, dan model konkurensi.

Pemasangan

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

Gambaran konseptual

Dokumentasi awal paket ini menjelaskan satu transport: MCP melalui stdio. Paket ini kini mengekspos registry tool yang sama melalui tiga transport. Untuk bermigrasi, pilih transport berjaringan, lalu petakan panggilan MCP Anda ke transport tersebut. Anda tidak perlu menulis ulang logika dokumen Anda.

Pilih transport yang sesuai dengan deployment Anda:

Tetap di MCP untuk satu agen lokal, latensi terendah (tanpa lompatan jaringan), atau klien MCP-native seperti asisten IDE lokal.
Pindah ke REST untuk akses multi-klien dengan kunci API per klien, deployment kontainer atau Kubernetes, pembatasan laju per klien, job asinkron, atau klien dalam bahasa apa pun.
Pindah ke gRPC untuk kontrak bertipe, server-streaming untuk PDF berukuran besar, dan deployment service-to-service dengan mutual-TLS.

Permukaan API

Apa yang tetap sama

Registry tool dan katalog yang bergantung pada runtime (lihat /connect/tool-catalog/).
Model risiko empat tingkat dan gerbang konfirmasi (lihat /connect/hitl-risk-tiers/).
Model dokumen dan semantik mesin.

Apa yang berubah

Aspek	MCP (stdio)	REST	gRPC
Format wire	JSON-RPC 2.0 melalui stdio	JSON melalui HTTP	Protobuf melalui gRPC
Autentikasi	tidak ada (subproses lokal)	kunci API `Authorization: Bearer`	bearer pada metadata panggilan
Konkurensi	satu proses, satu panggilan	pool worker RoadRunner	pool gRPC RoadRunner
Asinkron	tidak berlaku	endpoint job	RPC job
Streaming	tidak berlaku	body sinkron	RPC server-streaming

Pemetaan konsep

Urutan MCP yang umum adalah create_pdf, lalu content tools, lalu output_pdf. Di REST, urutan ini menjadi satu permintaan POST /api/v1/render tanpa status dengan array operations yang berurutan. Jika Anda memerlukan status per langkah, gunakan endpoint sesi yang bersifat opt-in sebagai gantinya. Di gRPC, padanannya adalah RPC Render, atau RenderStream untuk pengiriman bertahap per bagian. Untuk build berstatus, gunakan RPC CreateSession, SessionOperation, dan SessionRender.

Urutan tool MCP	REST	gRPC
`create_pdf` + content tools + `output_pdf`	`POST /api/v1/render`	`Render` / `RenderStream`
Build berstatus lintas panggilan	`POST /api/v1/sessions` (+ operasi sesi)	`CreateSession` (+ `SessionOperation`)
Render panjang	`POST /api/v1/jobs` lalu polling hasilnya	`SubmitJob` lalu `GetJobResult`
Operasi yang dibatasi tingkat	`POST /api/v1/<operation>`	`ExecuteCapability`

Contoh kode — Mulai cepat

Panggilan MCP:

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

menjadi permintaan 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

Contoh kode — Produksi

Jalankan transport lama dan baru selama migrasi bertahap. Profil RoadRunner gabungan menyajikan REST dan gRPC dari satu supervisor. Integrasi MCP lama dapat tetap berjalan secara lokal bila masih sesuai:

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

Tidak ada status bersama yang perlu dimigrasikan. Transport-transport tersebut berjalan sebagai proses independen di atas mesin yang sama. Pindahkan klien secara bertahap.

Kasus tepi dan hal yang perlu diperhatikan

Tambahkan autentikasi. Transport MCP tidak memilikinya karena merupakan subproses lokal. Transport berjaringan memerlukan kunci API yang valid pada setiap permintaan non-health. Sediakan kunci sebelum peralihan. Lihat /connect/security-and-operations/.
Gerbang konfirmasi tetap aktif. Tool approval_required meminta konfirmasi di REST dan gRPC persis seperti di MCP. Bawa alur konfirmasi ke dalam integrasi baru. Jangan berasumsi bahwa gerbang itu hanya untuk MCP. Lihat /connect/hitl-risk-tiers/.
Pembatasan tingkat tidak berubah. Operasi Pro atau Enterprise memerlukan nextpdf/premium terpasang dan kunci yang memiliki hak pada transport baru, sama seperti tool terkait memerlukan paket tersebut di MCP.
Idempotensi adalah hal baru dan bermanfaat. REST menambahkan kontrol idempotensi yang tidak pernah dimiliki transport stdio. Gunakan kontrol ini agar pengiriman job aman saat dicoba ulang. Lihat /connect/production-usage/.

Kinerja

MCP berjalan sebagai satu proses dan memiliki latensi terendah untuk satu agen lokal. Transport berjaringan menambahkan pool worker dan lompatan jaringan. Sebagai imbalannya, transport-transport tersebut dapat diskalakan ke banyak klien secara bersamaan. Pindahkan render panjang ke jalur job asinkron pada transport baru agar worker tidak tertahan.

Catatan keamanan

Migrasi dari stdio menambah paparan jaringan. Terminasikan Transport Layer Security (TLS) di depan REST, gunakan mutual TLS untuk gRPC di jaringan yang tidak tepercaya, batasi cakupan kunci per klien, dan jaga enabled_tools tetap minimal. Model tanpa kredensial pada transport MCP hanya aman karena merupakan subproses lokal. Jangan menciptakan kembali paparan tersebut melalui jaringan. Lihat /connect/security-and-operations/.

Konformitas

Halaman ini menyediakan panduan migrasi. Sitasi protokol dan autentikasi mengacu pada /transports/mcp/, /transports/rest/, /transports/grpc/, dan /connect/security-and-operations/.

Konteks komersial

Operasi yang dibatasi tingkat memerlukan nextpdf/premium apa pun transportnya. Migrasi tidak mengubah apa yang termasuk core versus Premium. Migrasi hanya mengubah cara Anda mengakses katalog.

Lihat juga

/transports/mcp/ — transport asal migrasi Anda
/transports/rest/ · /transports/grpc/ — transport tujuan migrasi Anda
/connect/tool-catalog/ — katalog, identik di seluruh transport
/connect/hitl-risk-tiers/ — gerbang, identik di seluruh transport
/connect/security-and-operations/ — autentikasi yang harus Anda tambahkan