Configure NextPDF Connect

At a glance

NextPDF Connect has two configuration surfaces. The Model Context Protocol (MCP) server reads a YAML file and NEXTPDF_MCP_* variables. The REST and gRPC servers read NEXTPDF_* environment variables. Configuration becomes immutable when the server boots.

Install

composer require nextpdf/server

Conceptual overview

The MCP server resolves configuration in a fixed priority order. The highest-priority source wins:

Environment variables (NEXTPDF_MCP_*).
The YAML configuration file’s nextpdf_mcp section.
Built-in defaults.

Pass the YAML file with --config=PATH. If you omit it, the server uses only defaults and environment variables. The resulting McpConfig is a readonly value object. No setting can change after boot.

The REST and gRPC servers read HttpConfig from the environment at boot. They support NEXTPDF_BIND, NEXTPDF_WORKER_COUNT, NEXTPDF_SESSIONS_ENABLED, and NEXTPDF_CORS_ENABLED as environment overrides. The remaining ceilings use safe defaults.

API surface

MCP configuration (`nextpdf-mcp`)

YAML file, nextpdf_mcp section:

nextpdf_mcp:
  enabled_tools: []          # empty/absent = all available tools allowed
  temp_directory: /tmp/nextpdf-mcp
  max_documents: 50
  document_ttl: 1800
  max_file_size_bytes: 104857600
  allow_file_output: true
  compress: true
  risk_level_overrides:
    fill_form: 3             # raise fill_form to ApprovalRequired (see below)

Environment overrides for the MCP server:

Variable	Config key	Default
`NEXTPDF_MCP_ENABLED_TOOLS`	`enabled_tools`	all tools allowed
`NEXTPDF_MCP_TEMP_DIR`	`temp_directory`	system temp + `/nextpdf-mcp`
`NEXTPDF_MCP_MAX_FILE_SIZE`	`max_file_size_bytes`	`104857600` (100 MB)
`NEXTPDF_MCP_MAX_DOCUMENTS`	`max_documents`	`50`
`NEXTPDF_MCP_DOCUMENT_TTL`	`document_ttl`	`1800` seconds
`NEXTPDF_MCP_TOOL_PARSE_PDF_ENABLED`	(gates `parse_pdf`)	unset (disabled)
`NEXTPDF_AST_TOOLS_ENABLED`	(gates AST tools)	enabled
`NEXTPDF_MUTATION_TOOLS_ENABLED`	(gates AST mutation tools)	unset (disabled)

REST and gRPC configuration

Variable	Default	Effect
`NEXTPDF_BIND`	`0.0.0.0:8080`	REST listen address
`NEXTPDF_WORKER_COUNT`	`4`	RoadRunner PHP worker count
`NEXTPDF_SESSIONS_ENABLED`	`false`	Enable stateful session endpoints
`NEXTPDF_CORS_ENABLED`	`false`	Enable CORS response headers
`NEXTPDF_API_KEYS`	unset	Inline API key definitions
`NEXTPDF_API_KEYS_FILE`	unset	Path to an API keys file
`NEXTPDF_JOB_STORE_PATH`	system temp	SQLite job store path
`NEXTPDF_REDIS_HOST`	unset	Enables Redis-backed stores when set

Redis is used by the REST server when NEXTPDF_REDIS_HOST is set and ext-redis is loaded:

Variable	Default
`NEXTPDF_REDIS_PORT`	`6379`
`NEXTPDF_REDIS_PASSWORD`	empty
`NEXTPDF_REDIS_DATABASE`	`0`
`NEXTPDF_REDIS_PREFIX`	`nextpdf:`
`NEXTPDF_REDIS_CONNECT_TIMEOUT`	`2.0` seconds
`NEXTPDF_REDIS_READ_TIMEOUT`	`2.0` seconds

Code sample — Quick start

Run the MCP server with an explicit configuration file:

./vendor/bin/nextpdf-mcp --config=/etc/nextpdf/nextpdf-mcp.yaml

Code sample — Production

Restrict the MCP catalog to an explicit allowlist, and raise a tool’s risk:

nextpdf_mcp:
  enabled_tools:
    - create_pdf
    - add_text
    - output_pdf
    - diagnostic.doctor
  temp_directory: /var/lib/nextpdf/tmp
  max_file_size_bytes: 26214400
  risk_level_overrides:
    add_text: 2          # upgrade add_text from caution to review

With a non-empty enabled_tools, the security policy admits only the listed tool names. The registry silently drops every other tool. An empty or absent list admits all available tools.

Edge cases and gotchas

The two critical tools cannot be downgraded. output_pdf and sign_pdf are approval-gated by design: a risk_level_overrides entry that lowers either tool below ApprovalRequired throws an InvalidArgumentException at load time, and the server refuses to boot. You can raise or lower every other tool’s risk level, so review any downgrade against your own threat model. See /connect/hitl-risk-tiers/.
enabled_tools filters, it does not add. Listing a Pro tool name while nextpdf/premium is absent does not make it appear. The allowlist is intersected with the tools that the registry actually discovered.
Environment beats YAML for the MCP server. A NEXTPDF_MCP_* variable overrides the same key in the YAML file. The REST and gRPC servers do not read the MCP YAML file at all.
parse_pdf is opt-in. The server registers the parse_pdf tool only when NEXTPDF_MCP_TOOL_PARSE_PDF_ENABLED is true or 1. It is absent by default, even in the core catalog.

Performance

Configuration is parsed once at boot. The max_documents and document_ttl settings bound the in-memory document store. Lowering them reduces peak memory, but shortens document lifetimes. Worker count and per-tier payload ceilings are deployment tuning controls, covered in /connect/deployment/.

Security notes

Treat enabled_tools as a deny-by-default control for least-privilege deployments: list only the tools that a given integration needs.
Never store API keys in the YAML file. Use NEXTPDF_API_KEYS_FILE with a file mounted as a Docker or Kubernetes secret. The server prefers a hot-reloading file store, so keys rotate without a restart. See /connect/security-and-operations/.
The temp_directory is the enforced base directory for file output. The server canonicalizes output paths and rejects anything that resolves outside it.

Conformance

This page describes configuration mechanics. Authentication and transport security conformance citations are pinned in /connect/security-and-operations/.

Commercial context

Per-tier payload and timeout ceilings (corePayloadLimit, proPayloadLimit, enterprisePayloadLimit, and the matching timeouts) apply to the REST transport according to the tier of the authenticated API key. They take effect only when Pro or Enterprise tools are installed and the key is entitled to them.