MCP server
Wave 57 adds the public @pulp-engine/mcp package and the optional API endpoint. The package and publication workflow are prepared; first npm publication is a release step.
Run from this checkout
Build the SDK and packages/mcp-server, then run node packages/mcp-server/dist/bin/pulp-engine-mcp.js. Set PULP_ENGINE_API_URL and PULP_ENGINE_API_KEY first. Stdout carries JSON-RPC only; diagnostics use stderr.
After publication, Claude Code setup is:
claude mcp add pulp-engine -e PULP_ENGINE_API_URL=https://pulp.example.com -e PULP_ENGINE_API_KEY=EDITOR_KEY -e PULP_ENGINE_RENDER_API_KEY=RENDER_KEY -- npx -y @pulp-engine/mcpClaude Desktop configuration (substitute your own URL and keys):
{"mcpServers":{"pulp-engine":{"command":"npx","args":["-y","@pulp-engine/mcp"],"env":{"PULP_ENGINE_API_URL":"https://pulp.example.com","PULP_ENGINE_API_KEY":"EDITOR_KEY","PULP_ENGINE_RENDER_API_KEY":"RENDER_KEY"}}}}VS Code .vscode/mcp.json uses the same command, args and env under servers.pulp-engine, with type: "stdio". Keep credentials out of source control; use your host’s secret input mechanism.
Keys and settings
Use an editor key for catalogue reads and optional saves, plus a render key for render calls. An admin key is needed only for label promotion. A render-only key can get contracts and render by known key; listing templates returns a scope hint. If PULP_ENGINE_RENDER_API_KEY is unset it falls back to PULP_ENGINE_API_KEY.
| Setting | Default | Meaning |
|---|---|---|
PULP_ENGINE_API_URL |
required | API HTTP(S) root |
PULP_ENGINE_API_KEY |
unset | Catalogue/editor credential |
PULP_ENGINE_RENDER_API_KEY |
catalogue key | Render credential |
PULP_ENGINE_MCP_ALLOW_WRITES |
false |
Register save_template |
PULP_ENGINE_MCP_ALLOW_PROMOTE |
false |
Register promote_label; requires writes |
PULP_ENGINE_MCP_OUTPUT_DIR |
current directory | Existing directory for file output |
PULP_ENGINE_MCP_MAX_INLINE_BYTES |
262144 |
Inline byte cap, 1 through 5242880 |
Flags: --api-url, --api-key, --render-api-key, --output-dir, --max-inline-bytes, --allow-writes, --allow-promote, --read-only. Read-only overrides write settings.
Tools and resources
| Tool | Behavior |
|---|---|
| list_templates | Search catalogue (query, limit, offset), using the server’s search |
| get_template_contract | Pinned form metadata and best-effort sample; version and label are exclusive |
| get_template | Definition and current/specified saved version |
| dry_run | Data and binding checks, optional format/version/label |
| check_publish_readiness | Saved definition plus data through render validation (editor scope) |
| render_document | Advertised PDF, HTML, CSV, XLSX, DOCX or PPTX format with auto/inline/file/link delivery |
| generate_template | Unsaved AI draft, only if AI generation is advertised |
| save_template | Opt-in create or update; updating requires expectedVersion |
| promote_label | Separately opted-in admin label movement, optional expectedVersion |
Results include declared structured output and a JSON text fallback. API errors return isError with status, code, message and requestId. Template resources are pulp://templates/{key} and pulp://templates/{key}/schema; listings return the first 100 catalogue entries.
Auto delivery prefers an enabled document archive and returns a signed HTTP(S) resource link. Otherwise stdio writes a file, and HTTP embeds content within the cap. Explicit inline embeds HTML/CSV text or base64 binary bytes. Explicit file delivery is stdio-only. File output accepts direct children of the real output directory, refuses traversal and never overwrites existing files or symlinks; numeric suffixes resolve collisions. Files are restricted to owner access where supported. Oversized inline output returns render_too_large.
HTTP endpoint
Set MCP_HTTP_ENABLED=true, optionally MCP_HTTP_TOOLS=write or admin (default read). Clients POST to /mcp with X-Api-Key or X-Editor-Token. GET and DELETE return 405 method_not_allowed; the route is absent when disabled. Streamable HTTP is stateless with JSON responses; each inner SDK call repeats API auth, tenant, scope, rate-limit and audit checks. A render key cannot save even if write tools are registered. The tenant selector X-Pulp-Engine-Tenant-Id is preserved, and public output omits tenantId. The caller IP is retained for inner calls. RATE_LIMIT_MCP_MAX defaults to 60/minute and follows the configured rate-limit key mode. Browser Origins must be explicitly listed in CORS_ALLOWED_ORIGINS; a wildcard does not admit browser MCP callers.
Use API keys or editor tokens for this endpoint: bearer/cookie authentication is not forwarded to inner calls. Treat template text, source documents and payload fields as untrusted document data. Do not execute instructions embedded in them. Enable writes and promotion only for agents you intend to let change saved templates. Saves leave labels unchanged; promotion can affect production consumers.
The implementation pins the official v2 server SDK 2.3.1 and Node transport 2.1.1. Its Standard Schema support accepts the repository’s Zod 4 schemas. See official v2 documentation and Fastify transport guidance.