Yalnızca MCP kullanılan yapıdan çoklu taşımaya geçiş

Bir bakışta

Bir entegrasyonu Model Context Protocol (MCP) stdio taşımasından Representational State Transfer’a (REST) veya gRPC’ye taşıyın. Motor davranışı değişmez. Katalog, risk modeli ve onay kapısı aynı kalır. Üç şey değişir: wire protokolü, kimlik doğrulama ve eşzamanlılık modeli.

Kurulum

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

Kavramsal genel bakış

Bu paketin ilk belgeleri tek bir taşıma tanımlıyordu: stdio üzerinden MCP. Paket artık aynı araç kayıt defterini üç taşıma üzerinden sunar. Geçiş yapmak için ağ tabanlı bir taşıma seçin, ardından MCP çağrılarınızı bu taşımaya eşleyin. Belge mantığınızı yeniden yazmanız gerekmez.

Dağıtımınıza uygun taşımayı seçin:

• MCP’de kalın: tek bir yerel araç, en düşük gecikme (ağ sıçraması olmadan) veya yerel bir IDE yardımcısı gibi MCP’ye özgü bir istemci için.
• REST’e geçin: istemci başına API anahtarlarıyla çok istemcili erişim, kapsayıcı veya Kubernetes dağıtımı, istemci başına hız sınırlama, eşzamansız işler ya da herhangi bir dilde yazılmış istemciler için.
• gRPC’ye geçin: türlendirilmiş sözleşmeler, büyük PDF’ler için sunucu akışı ve karşılıklı TLS kullanan hizmetten hizmete dağıtımlar için.

API yüzeyi

Aynı kalanlar

• Araç kayıt defteri ve çalışma zamanına bağlı katalog (bkz. /connect/tool-catalog/).
• Dört düzeyli risk modeli ve onay kapısı (bkz. /connect/hitl-risk-tiers/).
• Belge modeli ve motor semantiği.

Değişenler

Yön	MCP (stdio)	REST	gRPC
Wire biçimi	stdio üzerinden JSON-RPC 2.0	HTTP üzerinden JSON	gRPC üzerinden Protobuf
Kimlik doğrulama	yok (yerel alt süreç)	Authorization: Bearer API anahtarı	çağrı meta verisinde bearer
Eşzamanlılık	tek süreç, tek çağrı	RoadRunner çalışan havuzu	RoadRunner gRPC havuzu
Eşzamansız	geçerli değil	iş uç noktaları	iş RPC’leri
Akış	geçerli değil	eşzamanlı gövde	sunucu akışlı RPC’ler

Kavram eşlemesi

Tipik bir MCP dizisi create_pdf ile başlar, içerik araçlarıyla devam eder ve output_pdf ile biter. REST’te bu, durumsuz tek bir POST /api/v1/render isteğine dönüşür; istek, sıralı bir operations dizisi taşır. Adımlar arasında duruma ihtiyacınız olduğunda, bunun yerine isteğe bağlı oturum uç noktalarını kullanın. gRPC’de eşdeğeri Render RPC’si veya parçalı teslimat için RenderStream’dir. Durum tutan derlemeler için CreateSession, SessionOperation ve SessionRender RPC’lerini kullanın.

MCP araç dizisi	REST	gRPC
create_pdf + içerik araçları + output_pdf	POST /api/v1/render	Render / RenderStream
Çağrılar arasında durum tutan derleme	POST /api/v1/sessions (+ oturum işlemleri)	CreateSession (+ SessionOperation)
Uzun süren işleme	POST /api/v1/jobs ardından sonucu yoklayın	SubmitJob ardından GetJobResult
Katmana göre kapılı işlem	POST /api/v1/<operation>	ExecuteCapability

Kod örneği — hızlı başlangıç

MCP çağrısı:

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

Bu çağrı şu REST isteğine dönüşür:

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

Kod örneği — üretim

Aşamalı bir geçiş sırasında her iki taşımayı da çalıştırın. Birleşik RoadRunner profili, REST ve gRPC’yi tek bir denetleyici üzerinden sunar. Eski MCP entegrasyonu, hâlâ uygun olduğu durumlarda yerel olarak çalışmaya devam edebilir:

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

Aktarılacak paylaşılan bir durum yoktur. Taşımalar aynı motor üzerinde çalışan bağımsız süreçlerdir. İstemcileri aşamalı olarak taşıyın.

Uç durumlar ve dikkat edilecek noktalar

• Kimlik doğrulama ekleyin. Yerel bir alt süreç olduğu için MCP taşımasında kimlik doğrulama yoktu. Ağ tabanlı taşımalar, sağlık denetimi dışındaki her istekte geçerli bir API anahtarı gerektirir. Geçişten önce anahtarları hazırlayın. Bkz. /connect/security-and-operations/.

• Onay kapısı hâlâ devreye girer. Bir approval_required aracı, REST ve gRPC’de de tam olarak MCP’de olduğu gibi onay ister. Onay akışını yeni entegrasyona taşıyın. Kapının yalnızca MCP’ye özgü olduğunu varsaymayın. Bkz. /connect/hitl-risk-tiers/.

• Katman kapılaması değişmemiştir. Bir Pro veya Enterprise işlemi, tıpkı ilgili aracın MCP’de pakete ihtiyaç duyması gibi, yeni taşımada da nextpdf/premium kurulu olmasını ve yetkilendirilmiş bir anahtarı gerektirir.

• Eşgüçlülük yeni ve kullanışlıdır. REST, stdio taşımasında daha önce bulunmayan bir eşgüçlülük denetimi ekler. İş gönderimlerini güvenli biçimde yeniden denemek için bunu kullanın. Bkz. /connect/production-usage/.

Performans

MCP tek süreçlidir ve tek bir yerel araç için en düşük gecikmeye sahiptir. Ağ tabanlı taşımalar, bir çalışan havuzu ve bir ağ sıçraması ekler. Buna karşılık, çok sayıda eşzamanlı istemciye ölçeklenirler. Çalışanları meşgul etmemek için uzun süren işlemeleri yeni taşımadaki eşzamansız iş yoluna taşıyın.

Güvenlik notları

stdio’dan geçiş yapmak ağ maruziyeti ekler. REST’in önünde Transport Layer Security (TLS) sonlandırması yapın, güvenilmeyen ağlarda gRPC’de karşılıklı TLS kullanın, anahtarları istemci başına kapsamlandırın ve enabled_tools öğesini asgari düzeyde tutun. MCP taşımasının kimlik bilgisi içermeyen modeli, yalnızca yerel bir alt süreç olduğu için güvenlidir. Bu maruziyeti bir ağ üzerinden yeniden oluşturmayın. Bkz. /connect/security-and-operations/.

Uygunluk

Bu sayfa geçiş kılavuzu sağlar. Protokol ve kimlik doğrulama atıfları şu sayfalarda sabitlenmiştir: /transports/mcp/, /transports/rest/, /transports/grpc/ ve /connect/security-and-operations/.

Ticari bağlam

Katmana göre kapılı işlemler, taşımadan bağımsız olarak nextpdf/premium gerektirir. Geçiş yapmak, neyin core, neyin Premium olduğunu değiştirmez. Yalnızca kataloğa nasıl ulaştığınızı değiştirir.

Ayrıca bkz.

• /transports/mcp/ — geçiş yaptığınız kaynak taşıma
• /transports/rest/ · /transports/grpc/ — geçiş yaptığınız hedef taşımalar
• /connect/tool-catalog/ — katalog, taşımalar arasında aynı
• /connect/hitl-risk-tiers/ — kapı, taşımalar arasında aynı
• /connect/security-and-operations/ — eklemeniz gereken kimlik doğrulama