NextPDF Connect server overview

At a glance

NextPDF Connect is the nextpdf/server package, a long-lived service that exposes the NextPDF PDF 2.0 engine to AI agents and to HTTP clients. It uses three transports: Model Context Protocol (MCP) over stdio, a REST API, and gRPC. All three transports use one tool registry and one human-in-the-loop (HITL) confirmation gate.

Install

composer require nextpdf/server

The Composer constraint is nextpdf/core: ^3.0 with php: >=8.4 <9.0. For the complete procedure, see /connect/install/. That page also covers two optional add-ons: the ext-redis extension and the nextpdf/premium package.

Conceptual overview

nextpdf/server adapts the framework-agnostic NextPDF core into a service surface. It does not rebuild PDF generation. Instead, it wraps each engine capability as a named tool with its own schema, then serves that catalog over several wire protocols.

Three concepts carry the whole design:

The tool registry. NextPDF\Server\ToolRegistry finds and registers tools at boot. A core set ships with the package, and that core set is always available. Pro and Enterprise providers register more tools, but only when the matching packages are installed. The number of exposed tools is a runtime property of the deployment, not a fixed constant. See /connect/tool-catalog/.
The transports. The same registry is served three ways. MCP runs over stdio for local AI clients. REST runs over a PSR-15 middleware pipeline on a RoadRunner worker pool for networked clients. gRPC runs on a Spiral RoadRunner gRPC worker for typed, streaming clients. Each transport is its own process with its own entry point. See /transports/mcp/, /transports/rest/, and /transports/grpc/.
The confirmation gate. Every tool declares a risk level. A tool at the highest level requires an explicit human confirmation before it runs. The gate issues a single-use challenge token. The agent must pass that token to a human, then call the tool again with the token. See /connect/hitl-risk-tiers/.

The diagram below shows how one registry reaches three transports. It also shows where the confirmation gate sits on the request path.

NextPDF Connect component architecture

The package is Apache-2.0 licensed, which matches nextpdf/core. The implemented MCP protocol version is the date-versioned 2025-06-18 revision. An OpenAPI 3.1 document describes the REST surface. The nextpdf.connect.v1 Protocol Buffers package describes the gRPC surface.

API surface

The public entry points are the three server classes. Each one has a command-line interface (CLI) wrapper:

Entry point	Class	Transport
`bin/nextpdf-mcp`	`NextPDF\Server\Mcp\McpServer`	MCP over stdio
`bin/nextpdf-server`	`NextPDF\Server\Http\HttpServer`	REST over RoadRunner HTTP
`bin/nextpdf-grpc`	`NextPDF\Server\Grpc\GrpcServer`	gRPC over RoadRunner gRPC
`bin/generate-skills`	`NextPDF\Server\Skills\SkillsDumper`	Tool catalog export

McpServer::create(), HttpServer::create(), and GrpcServer::create() each builds a fully configured server from environment and configuration input. The registry, the document store, the security policy, and the confirmation gate are shared concepts across all three servers.

Code sample — Quick start

The minimal MCP server needs one command. You write no PHP glue code:

./vendor/bin/nextpdf-mcp

The server reads JSON-RPC requests on standard input and writes responses on standard output. For a runnable initialize and tools/list exchange and the matching REST request, see /connect/quickstart/.

Edge cases and gotchas

The tool count is not 33, or any other fixed number. The server counts the tools at runtime as count(ToolRegistry::all()), after policy filtering and tier detection. Documentation that quotes a fixed total is stale. To get the authoritative count, query the running server. Use the MCP initialize response, or the REST /api/v1/capabilities endpoint.

The number of exposed tools depends on the installed packages and on the active policy. Read it from the running server at runtime. A fixed number in your code or documentation will fall out of date.
A missing Pro or Enterprise package is not an error. The registry checks for provider classes with class_exists(), then silently skips any tier that is absent. An open-source-only deployment boots and serves its core catalog normally.
The three transports do not share a process. Running the MCP server does not start the REST server or the gRPC server. The reverse is also true. A combined deployment runs the RoadRunner supervisor with a configuration that starts both worker pools, the HTTP pool and the gRPC pool. See /connect/deployment/.

Performance

Each transport is worker-based. A worker handles one request at a time. The REST and gRPC servers run on RoadRunner worker pools, and configuration sets the pool size. The default is four HTTP workers. The RoadRunner supervisor caps the memory of each worker. The performance_budget front-matter on this page describes a cold boot and discovery envelope. It is not a per-request target. The underlying engine operation drives most request cost.

Security notes

All networked transports authenticate with an application programming interface (API) key bearer token. The MCP stdio transport is a local subprocess that the launching client trusts, per the MCP transport model. High-risk tools stay gated behind human confirmation on every transport. For the full threat model, the authentication model, and the transport-security configuration, see /connect/security-and-operations/.

Conformance

This page makes architectural claims only. The normative protocol and security citations are pinned on the pages that specify the behavior: /connect/security-and-operations/, /transports/mcp/, /transports/rest/, and /transports/grpc/. The MCP lifecycle reference is the official specification at modelcontextprotocol.io (revision 2025-06-18). The transport pages record that reference with its URL, because the MCP specification is not part of the gated standards corpus.

Commercial context

The core catalog is complete for document creation, inspection, and diagnostics. Tools for signing, redaction, compliance certification, and forensic analysis appear only when nextpdf/premium is installed alongside the server. This is a packaging boundary, not a runtime upsell prompt. The server never emits marketing content.