NextPDF Connect — MCP-transport

In één oogopslag

Het Model Context Protocol (MCP)-transport draait bin/nextpdf-mcp als lokaal subproces. Het communiceert via JSON-RPC 2.0 over standaardinvoer en -uitvoer. De server implementeert de MCP-revisie met datumversie 2025-06-18.

Installatie

composer require nextpdf/server

Conceptueel overzicht

In het MCP-stdio-model start de client de server als subproces. De client wisselt newline-gescheiden JSON-RPC-berichten uit: één bericht per regel, geen ingesloten newlines, UTF-8. De server schrijft alleen geldige MCP-berichten naar standaarduitvoer en stuurt logs naar standaardfout. Deze implementatie stuurt de audit-logger naar standaardfout, zodat logregels de protocolstream nooit beschadigen. De officiële MCP-specificatie, revisie 2025-06-18, definieert deze framing. Die specificatie maakt geen deel uit van het afgeschermde corpus met standaarden en wordt daarom via URL geciteerd: https://modelcontextprotocol.io/specification/2025-06-18/basic/transports.

NextPDF Connect implementeert het stdio-transport. De MCP-specificatie definieert daarnaast een Streamable HTTP-transport. Volgens de specificatie moeten clients stdio waar mogelijk ondersteunen en mag een server uitsluitend stdio implementeren. Gebruik voor netwerktoegang tot dezelfde tools in plaats daarvan het REST- of gRPC-transport; zie /transports/rest/ en /transports/grpc/.

API-oppervlak

Methoden

Methode	Gedrag
`initialize`	Retourneert de protocolversie, mogelijkheden en serverinformatie
`notifications/initialized`	Een notificatie (geen `id`); geaccepteerd zonder antwoord
`tools/list`	Toont geregistreerde tools met een optioneel `params.category`-filter
`tools/call`	Voert een tool uit op basis van `params.name` met `params.arguments`

Voor elke andere methode retourneert de server method-not-found (-32601). Een bericht dat geen geldige JSON-RPC 2.0 is, retourneert invalid-request (-32600); niet-parseerbare invoer retourneert parse-error (-32700). Een herhaalde aanvraag met dezelfde id retourneert het eerder in de cache opgeslagen antwoord uit een buffer met 64 items, zonder de aanvraag opnieuw uit te voeren.

Het initialize-antwoord

Het resultaat van initialize retourneert protocolVersion 2025-06-18, serverInfo.name: NextPDF Connect en een capabilities-object. Naast de standaardmogelijkheid tools voegt de server een capabilities.nextpdf-blok toe:

tiers — live aantallen geregistreerde tools per niveau (core / pro / enterprise).
tool_count — het totale aantal geregistreerde tools, berekend bij runtime.
risk_model_version — de versie van het risicomodel die de server afdwingt.
hitl_enabled — true; de bevestigingspoort is actief.

tool_count is de gezaghebbende waarde voor deze implementatie. Het is een runtime-telling, geen gedocumenteerde constante; zie /connect/tool-catalog/.

Codevoorbeeld — Snelstart

./vendor/bin/nextpdf-mcp <<'EOF'
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"client","version":"1.0.0"}}}
{"jsonrpc":"2.0","method":"notifications/initialized"}
{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}
EOF

Codevoorbeeld — Productie

Een categoriefilter beperkt de catalogus tot één domein:

./vendor/bin/nextpdf-mcp --config=/etc/nextpdf/nextpdf-mcp.yaml <<'EOF'
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"client","version":"1.0.0"}}}
{"jsonrpc":"2.0","method":"notifications/initialized"}
{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{"category":"diagnostic"}}
EOF

Categoriewaarden komen uit de gedeclareerde categorie van elke tool (bijvoorbeeld document, diagnostic).

Randgevallen en valkuilen

Geen API-sleutel. Het stdio-transport heeft geen netwerklistener en geen bearertoken. Beschouw de procesgrens van het besturingssysteem als de vertrouwensgrens, conform het MCP-stdio-model. Koppel het niet aan een netwerk.
Bevestigingsuitdagingen verlopen in-band. Een ApprovalRequired-tool retourneert een geslaagd JSON-RPC-antwoord. De inhoud van het antwoord is de uitdagingstekst en een token voor eenmalig gebruik, geen fout. Zie /connect/hitl-risk-niveaus/.
Notificaties zijn stil. Een bericht zonder id levert geen antwoord op. De handshake bestaat uit initialize (met id), daarna de initialized-notificatie en vervolgens aanroepen met een id.

Prestaties

De MCP-server draait als één proces en verwerkt één aanvraag tegelijk via pipes. Er is geen netwerk-round-trip nodig; de latentie wordt bepaald door de onderliggende engine-bewerking.

Beveiligingsnotities

Het transport erft het vertrouwen van de client die het start. Houd het subproces lokaal. Tools met een hoog risico vereisen nog steeds menselijke bevestiging, ook al is er geen API-sleutel. Zie /connect/security-and-operations/.

Conformiteit

De stdio-framing en het initialize/lifecycle-gedrag voldoen aan de officiële Model Context Protocol-specificatie, revisie 2025-06-18:

Transports: https://modelcontextprotocol.io/specification/2025-06-18/basic/transports
Lifecycle: https://modelcontextprotocol.io/specification/2025-06-18/basic/lifecycle

De MCP-specificatie maakt geen deel uit van het afgeschermde corpus met standaarden en heeft daarom geen reference_id; de officiële URL’s hierboven vormen de gezaghebbende citatie.

Commerciële context

tools/list retourneert alleen Pro- en Enterprise-tools wanneer nextpdf/premium naast de server is geïnstalleerd. Het transport zelf is hetzelfde, ongeacht welke niveaus zijn geïnstalleerd.

Zie ook

/connect/quickstart/ — de uitvoerbare handshake
/connect/tool-catalog/ — wat tools/list retourneert en waarom de aantallen variëren
/connect/hitl-risk-niveaus/ — het formaat van de bevestigingsuitdaging
/transports/rest/ · /transports/grpc/ — alternatieven met netwerktoegang
/connect/migrating-to-multi-transport/ — een uitsluitend op MCP gebaseerde integratie overzetten naar REST/gRPC