NextPDF Connect — MCP transport

At a glance

The Model Context Protocol (MCP) transport runs bin/nextpdf-mcp as a local subprocess. It speaks JSON-RPC 2.0 over standard input and output. The server implements the date-versioned MCP revision 2025-06-18.

Install

composer require nextpdf/server

Conceptual overview

In the MCP stdio model, the client launches the server as a subprocess. The client exchanges newline-delimited JSON-RPC messages: one message per line, no embedded newlines, UTF-8. The server writes only valid MCP messages to standard output and sends logs to standard error. The implementation routes its audit logger to standard error so log lines never corrupt the protocol stream. The official MCP specification, revision 2025-06-18, defines this framing. That specification is not part of the gated standards corpus, so it is cited by URL: https://modelcontextprotocol.io/specification/2025-06-18/basic/transports.

NextPDF Connect implements the stdio transport. The MCP specification also defines a Streamable HTTP transport. The specification states clients should support stdio whenever possible, and a server may implement stdio alone. For network access to the same tools, use the REST or gRPC transport instead; see /transports/rest/ and /transports/grpc/.

API surface

Methods

Method	Behavior
`initialize`	Returns the protocol version, capabilities, and server info
`notifications/initialized`	A notification (no `id`); accepted with no response
`tools/list`	Lists registered tools with an optional `params.category` filter
`tools/call`	Executes a tool by `params.name` with `params.arguments`

Any other method returns method-not-found (-32601). A message that is not valid JSON-RPC 2.0 returns invalid-request (-32600); unparseable input returns parse-error (-32700). A duplicate request id returns the cached prior response from a 64-entry buffer without re-executing.

The initialize response

The initialize result returns protocolVersion 2025-06-18, serverInfo.name: NextPDF Connect, and a capabilities object. In addition to the standard tools capability, the server adds a capabilities.nextpdf block:

tiers — live registered-tool counts by tier (core / pro / enterprise).
tool_count — the total number of registered tools, computed at runtime.
risk_model_version — the risk model version the server enforces.
hitl_enabled — true; the confirmation gate is active.

tool_count is the authoritative number for this deployment. It is a runtime count, not a documented constant; see /connect/tool-catalog/.

Code sample — Quick start

./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

Code sample — Production

A category filter narrows the catalog to one domain:

./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

Category values come from each tool’s declared category (for example document, diagnostic).

Edge cases and gotchas

No API key. The stdio transport has no network listener and no bearer token. Treat the operating-system process boundary as the trust boundary, per the MCP stdio model. Do not bridge it to a network.
Confirmation challenges are in-band. An ApprovalRequired tool returns a successful JSON-RPC response. The response content is the challenge text and a single-use token, not an error. See /connect/hitl-risk-tiers/.
Notifications are silent. A message with no id produces no response. The handshake is initialize (with id), then the initialized notification, then id-bearing calls.

Performance

The MCP server runs as a single process and handles one request at a time over pipes. There is no network round-trip; latency is dominated by the underlying engine operation.

Security notes

The transport inherits the launching client’s trust. Keep the subprocess local. High-risk tools still require human confirmation even though there is no API key. See /connect/security-and-operations/.

Conformance

The stdio framing and initialize/lifecycle behavior conform to the official Model Context Protocol specification, revision 2025-06-18:

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

The MCP specification is not in the gated standards corpus, so it has no reference_id; the official URLs above are the citation of record.

Commercial context

tools/list returns Pro and Enterprise tools only when nextpdf/premium is installed alongside the server. The transport itself is the same regardless of installed tiers.