Capabilities and permissions

ShipPDF gives your assistant tools to discover published templates, generate PDFs, and author reusable templates. Permissions are enforced by ShipPDF on every call. A prompt can guide the assistant’s behavior; the connection’s scopes and resource access determine what it is allowed to do.

API scopes and MCP tools

API tokens and OAuth connections use the same named scopes. Tools whose required scope is missing are hidden from the tool list and cannot be called. Resource access further limits which projects, templates, and documents an API token can reach.

API scope	MCP tool	What it does
`projects:read`	`list_projects`	List accessible projects and their IDs.
`templates:read`	`list_templates`	List accessible published templates.
`templates:read`	`get_template_metadata`	Read a published template’s name, description, revision, and data schema.
`templates:read`	`get_template`	Read published metadata and the full template document.
`documents:create`	`generate_document`	Queue PDF generation from a published template; spends a generation credit.
`documents:read`	`get_document`	Read generation status, failure details, and the completed PDF URL.
`templates:write`	`get_authoring_guide`	Read the authoring workflow, layout rules, and worked example.
`templates:write`	`describe_schema`	Read the JSON Schema for a template document or a named definition.
`templates:write`	`create_template`	Create a template draft in an accessible project.
`templates:write`	`get_draft_template`	Read the current draft, lock version, validation problems, and preview URL.
`templates:write`	`edit_template`	Apply ordered operations to part of a draft.
`templates:write`	`update_template`	Rename a template or replace its entire draft document.
`templates:write`	`publish_template`	Publish the draft as an immutable revision for future generation.
`templates:write`	`import_asset`	Import a public PNG, JPEG, or WebP image into workspace assets.

For API tokens, * grants every scope within the token’s resource access. webhooks:manage has no MCP tool. OAuth accepts only the five named scopes above. See the API reference for each REST endpoint’s required scope; template authoring tools are available through MCP rather than equivalent public REST endpoints.

Reading a draft requires templates:write, even though get_draft_template does not modify it. Reading a published template requires templates:read.

Choose permissions for your workflow

Workflow	Scopes
Browse published templates	`templates:read`; add `projects:read` to browse by project.
Generate and retrieve PDFs using a known template ID	`documents:create`, `documents:read`.
Discover templates, then generate PDFs	`templates:read`, `documents:create`, `documents:read`.
Create and publish templates in a known project	`templates:write`; add `projects:read` to discover projects.
Author templates and generate PDFs from them	`templates:write`, `documents:create`, `documents:read`; add read scopes for discovery.

Publishing changes the revision used by future generations. Granting authoring access lets the assistant both edit and publish; there is no separate publish scope. Your client may also require confirmation for write calls.

Help the assistant work accurately

Give the assistant the intended workspace, project or template ID when you know it, the source data, and the outcome you need. Ask it to use tool results to resolve IDs and schemas.

Before generation: call get_template_metadata to inspect the actual data schema. Match field paths and types, and ask for missing values instead of inventing them.
Before authoring: call get_authoring_guide, then describe_schema for unfamiliar document structures. These provide ShipPDF’s supported layout rules and input shapes.
Before editing: read the draft with get_draft_template. Use its node IDs and latest lock_version rather than remembered values.
Before publishing: inspect publishable and problems, and review the preview with representative sample data. A valid schema alone does not establish that the layout looks right.
After generation: poll get_document. Report success only when its status is completed and a PDF URL is available.

For example:

Use ShipPDF’s invoice template. Read its metadata first, show me any required data I have not provided, then generate one PDF. Reuse the same idempotency key if the request needs a retry, and return the completed PDF link.

For authoring:

Read ShipPDF’s authoring guide and build an A4 invoice draft in project proj_example. Use the attached invoice data as sample data. Show me the preview and fix reported problems. Leave it as a draft for my review.

MCP resources

Clients that support resources can read the same reference material without a tool call:

Resource URI	Content	Scope
`shippdf://recipe/authoring`	Authoring guide.	`templates:read` or `templates:write`
`shippdf://schema/template-document/{version}`	Template document JSON Schema.	`templates:read` or `templates:write`
`shippdf://templates/{template_id}`	Published template document.	`templates:read`

Use the concrete URIs returned by the server’s resource list; braces above mark variable parts.

Next: Generate a PDF or Author a template with AI.