NextPDF Connect integration

At a glance

Integrate NextPDF Connect by running it as a server. You do not wire a library into a host application. Choose a transport, then configure authentication for any networked transport. The engine’s tools stay behind the confirmation gate.

Install

composer require nextpdf/server

The Composer constraint is nextpdf/core: ^3.0 with php: >=8.4 <9.0. For optional ext-redis and nextpdf/premium setup, see /connect/install/.

Conceptual overview

The package runs as a standalone service. You do not register a service provider, bundle, or container module in a host framework. The integration point is the process you run. Each transport has its own entry point and boots independently. See /connect/boot-and-discovery/.

API surface

Entry point	Transport	Profile
`bin/nextpdf-mcp`	MCP over stdio	(none — direct subprocess)
`bin/nextpdf-server`	REST over RoadRunner HTTP	`.rr.yaml`
`bin/nextpdf-grpc`	gRPC over RoadRunner gRPC	`.rr.grpc.yaml`
both networked transports	REST + gRPC	`.rr.full.yaml`

Boot and auto-discovery

The registry always discovers the core tier. It then adds the Pro and Enterprise providers when their classes resolve, followed by the bundled abstract syntax tree (AST) and mutation providers under environment gates. The enabled_tools security allowlist filters all of them, so the exposed catalog belongs to this deployment. See /connect/tool-catalog/ and /connect/boot-and-discovery/.

Container bindings

None. Each server factory builds its own object graph explicitly. The injectable seams support tests, not application wiring.

Publish config

The MCP server accepts an optional YAML file (--config=PATH, nextpdf_mcp section) and NEXTPDF_MCP_* environment overrides. The REST and gRPC servers read NEXTPDF_* environment variables. For details, see /connect/configuration/.

Transport availability (MCP / REST / gRPC)

All three transports serve the same registry:

MCP — local subprocess, JSON-RPC 2.0 over stdio, no API key, MCP revision 2025-06-18. See /transports/mcp/.
REST — RoadRunner HTTP worker pool, OpenAPI 3.1 contract, bearer API key, tier-gated routes. See /transports/rest/.
gRPC — RoadRunner gRPC worker pool, nextpdf.connect.v1 Protobuf service, server-streaming RPCs, bearer-in-metadata authentication, mutual TLS in the combined profile. See /transports/grpc/.

A transport is “available” when its entry point or RoadRunner profile is running. Transports do not start each other automatically.

HITL risk tier

Every tool declares one of four risk levels: safe, caution, review, approval_required. Tools at approval_required do not run on the first call. The confirmation gate issues a single-use challenge token that a human must authorize. A configuration override may only raise a tool’s risk, never lower an approval_required tool. The model applies the same way on every transport that drives tools. See /connect/hitl-risk-tiers/.

Confirmation gate JSON envelope

The gate check returns one of two JSON shapes. Allowed:

{ "allowed": true }

Challenge:

{
  "allowed": false,
  "challenge": "<human-readable text naming the operation, its description, an overwrite warning when applicable, and the re-invocation instruction>",
  "token": "confirm_<nonce>"
}

The token binds the tool name, a random nonce, and a 300-second TTL, not the arguments. To proceed, the caller invokes the same tool again with a _confirmation_token argument set to the issued token. The challenge is plain instructional text plus the token; it is not a cryptographically signed envelope. See /connect/hitl-risk-tiers/.

Service smoke test

./vendor/bin/generate-skills --dry-run --list-tools

This boots the registry and tier detection, then prints the exposed tools without serving traffic. Use it to confirm that the integration is wired and to check which catalog this install produces.

Edge cases and gotchas

No framework hooks. Do not look for a service provider or bundle. The running process is the integration.
A missing tier is not an error. The core-only install boots and serves its core catalog.
Networked transports require a key. Only /healthz and /readyz (REST) and the health RPCs (gRPC) are anonymous.

Performance

Boot cost is the registry scan and tier detection, once per process. Per-request cost is the engine operation. Size RoadRunner worker pools against observed render latency. See /connect/production-usage/.

Security notes

Networked transports authenticate with an npk_live_ bearer key validated in constant time; the gate enforces human confirmation for destructive operations regardless of transport. Terminate TLS in front of REST, and use mutual TLS for gRPC on untrusted networks. See /connect/security-and-operations/.

Conformance

Protocol and security citations are pinned on /transports/mcp/, /transports/rest/, /transports/grpc/, and /connect/security-and-operations/.

Commercial context

Install nextpdf/premium alongside the server to register the additional Pro and Enterprise tools in the same running server. No separate process is involved.