Full parameter reference for the 12 tools of the Carbone MCP server, and for running the server itself. For setup, start with the README.
Document operations
- convert_document
- render_document
- get_render_result (async renders only)
Template management
- inspect_template
- list_templates
- list_categories
- list_tags
- upload_template
- update_template_metadata
- delete_template
- download_template
Discovery
- find_template_examples
- get_api_status
- get_capabilities
- Carbone Skill (
skill://carbone/SKILL.md)
Server
- File inputs
- Output & file delivery
- Async renders
- Transport modes
- Configuration
- Health endpoint
- Logs
- Supported output formats
Convert a document to another format without storing a template. This is a pure conversion: no data is sent, so Carbone tags such as {d.name} are kept as written (use render_document to fill them).
File input: absolute local path (stdio only), URL, or base64 string (see File inputs).
Accepted formats.
convert_documentandrender_documentuse the same Carbone endpoint and the same format validation, so they accept the same inputs: XML-based and text-based documents, plus PDF:DOCX,XLSX,PPTX,ODT,ODS,ODP,ODG,HTML,XHTML,XML,SVG,IDML,MD,TXT,CSV,RTF,DOC,XLSandPPTare rejected as input (415, errorw118) even though Carbone can produce them as output: re-save them asDOCX/XLSX/PPTXfirst.
Carbone tags are preserved. Converting a DOCX template to PDF shows the tags as written. That is how you proof a template's layout, or convert a template between formats (DOCX → ODT) while it stays a template. Use
render_documentto resolve tags into real values, orrender_documentwithkeepTagsto proof a stored template.
Convert /path/to/report.docx to PDF
Convert https://example.com/presentation.pptx to PNG
Convert this HTML to PDF: <h1>Hello</h1>
Render /path/to/report.pdf as a PNG thumbnail
Render this SVG chart as a sharp PNG (converter C, Scale 2) so I can check it
See the result: an image output (
png,jpg,webp) is returned inline, so the assistant can check the layout. HTML or SVG: converterC, withformatOptions: { "Scale": 2 }for sharp text (Carbone v5.17.0+). DOCX, PDF or PPTX: the default converter renders the first page or slide.
PDF as input: a PDF converts to
docx,odt,htmlortxt, to an image (png,jpg,webp), or is re-saved ashardRefreshfor you, without which Carbone would return the PDF unchanged).
| Parameter | Type | Required | Description |
|---|---|---|---|
file |
string | ✅ | Absolute local path (stdio only), URL, or base64 string (File inputs). Over HTTP, required unless attachedFile is given |
attachedFile |
object | ❌ | HTTP only. A file attached to the ChatGPT conversation (Chat attachments). Mutually exclusive with file |
convertTo |
string | object | ✅ | Target format (see Supported output formats) or advanced object. Valid outputs depend on the input format; doc, xls and ppt are output-only |
converter |
L | O | C | I |
❌ | Converter engine (default: L LibreOffice) |
reportName |
string | ❌ | Name of the delivered file, without extension: the server names it <reportName>.<ext> (attachment name, and the default saved file name in stdio). The server names the file itself: a conversion has no templating pass, which is where Carbone resolves reportName (the file would otherwise be report.<ext>). Used literally: tags are not resolved. Ignored with returnLink and outputPath |
hardRefresh |
boolean | ❌ | Run the converter even when the output format equals the input format, and recompute pagination and the table of contents. Needed for PDF → PDF: without it Carbone returns the PDF unchanged and formatOptions (password, permissions, watermarks, PDF/A…) are not applied. Set automatically when the input is a PDF, convertTo is pdf and formatOptions are given; pass false to opt out |
failOn |
string[] | ❌ | ["IMAGE_URL_ERROR"]: with converter C (Carbone v5.16.0+), an image (or another resource) of the HTML or SVG document that cannot be downloaded fails the conversion instead of being left out |
outputPath |
string | ❌ | stdio only: save the result to this local path (see Output & file delivery) |
asAttachment |
boolean | ❌ | Return the bytes as a downloadable attachment instead of inline |
returnLink |
boolean | ❌ | Return a public one-time download URL instead of the file |
egressAuthorization |
string | ❌ | Authorization header value Carbone adds when fetching protected external assets during conversion (e.g. a Chromium HTML→PDF fetching a secured image). Max 511 chars |
converter options (used whenever the format changes, not only for PDF):
L: LibreOffice (default), DOCX, XLSX, PPTX, ODT, ODS, ODP, ODG, MD, PDF; the only converter supporting all PDF optionsI: Carbone ICE, DOCX and ODT → PDF; Carbone's own engine, 3x to 300x faster, recommended overOfor DOCX from Carbone v5.15.0. A DOCX with tracked changes is rendered as its current version (changes accepted). It converts all content except WEBP and EMF/WMF images, SmartArt and complex charts (bar, line, area, pie and doughnut charts are drawn), comments, form fields, equations, bookmarks and endnotes: keep the defaultLfor documents with those. From ODT, tracked changes and footnotes are ignored too. A missing font is replaced by Noto Sans (Carbone's documentation)O: OnlyOffice, DOCX, XLSX, PPTX → PDFC: Chromium, HTML, XHTML → PDF, PNG, JPG, WEBP with full CSS/JS, and SVG → PDF, PNG, JPG, WEBP (Carbone v5.17.0+); 100 MB max. Image size and sharpness come fromformatOptions(see below)
PDF options: L supports all of them; O, C and I apply Security (passwords, permissions) and Watermarks.
Advanced convertTo object:
{
"formatName": "pdf",
"formatOptions": {
"EncryptFile": true,
"DocumentOpenPassword": "secret",
"RestrictPermissions": true,
"PermissionPassword": "owner",
"Watermarks": [{ "text": "CONFIDENTIAL", "size": 60, "opacity": 0.1, "rotation": -45 }],
"SelectPdfVersion": 2,
"PageRange": "1-5"
}
}formatOptions reference (common keys; full list in the Carbone documentation):
| Option | Format | Description |
|---|---|---|
EncryptFile |
Encrypt the PDF; requires DocumentOpenPassword |
|
DocumentOpenPassword |
Password to open the document | |
RestrictPermissions |
Restrict printing, copying and changes; use with PermissionPassword |
|
PermissionPassword |
Password to change the restricted permissions | |
Watermarks |
Up to 4 watermarks: text (required), size, opacity, rotation, anchor, color, … |
|
SelectPdfVersion |
PDF (L only) |
1–4 = PDF/A-1 to PDF/A-4; 15, 16, 17, 20 = PDF 1.5, 1.6, 1.7, 2.0 |
PageRange |
PDF (L only) |
Export specific pages, e.g. "1-5" |
UseTaggedPDF / PDFUACompliance |
PDF (L only) |
Tagged PDF / PDF/UA accessibility |
PixelWidth / PixelHeight |
PNG/JPG/WEBP | Output image size in pixels. With L (one page or slide): the image size. With C (HTML, SVG): PixelWidth is the layout width (default: the document width, at least 800), PixelHeight the height when FullPage is false (default 600); 1 to 16383 each |
FullPage |
PNG/JPG/WEBP (C only) |
true (default): capture the whole height of the document; false: crop to PixelHeight |
Scale |
PNG/JPG/WEBP (C only) |
Resolution factor, 0.1 to 4 (default 1): 2 doubles the width and height, text and SVG stay sharp. At most 16383 px per side and 25 million pixels in all |
Quality |
JPG/WEBP | Quality 1–100 (C: 0–100, default 90, 100 = lossless WEBP) |
fieldSeparator |
CSV | Custom column separator, e.g. ";" |
Generate a document by merging a Carbone template with JSON data.
Provide exactly one of: templateId or template (never both).
Generate an invoice using template abc123 with { "customer": "Acme", "total": 1500 }
Render /path/to/invoice.docx with { "customer": "Acme" } and convert to PDF
| Parameter | Type | Description |
|---|---|---|
templateId |
string | Template ID (64-bit) or Version ID (SHA-256) returned by upload_template |
template |
string | Absolute local path (stdio only), URL, or base64 (File inputs), uploaded and rendered in a single request |
attachedTemplate |
object | HTTP only. A file attached to the ChatGPT conversation, used like template (Chat attachments) |
| Parameter | Type | Description |
|---|---|---|
data |
object | array | string | Optional. JSON data injected into {d.field} tags. Accepts an object, a top-level array ({d[i].field}), or a string reference to a JSON file (see Pass JSON by reference). If omitted, {} is sent: templating still runs, so every tag resolves to an empty string; to keep the tags, use keepTags (or convert_document for a file) |
keepTags |
boolean | Skip templating entirely and leave every tag as literal text ({d.customer} stays {d.customer}). Use it to proof a stored template by templateId. Mutually exclusive with data: passing both is rejected |
convertTo |
string | object | Convert output to a different format (e.g. "pdf"); same values and formatOptions as convert_document |
converter |
L | O | C | I |
Converter engine (see convert_document) |
reportName |
string | Output filename without extension (Carbone appends it), supports Carbone tags (e.g. "{d.client}-invoice"). With keepTags (no templating pass), the server names the file <reportName>.<ext> itself, literally |
failOn |
string[] | Conditions that stop the render with an error (Carbone v5.15.0+). ["IMAGE_URL_ERROR"]: an image that cannot be downloaded from its URL fails the render instead of showing a broken-image placeholder |
preReleaseFeatureIn |
integer | Pre-release feature level for this render only (e.g. 5000000) |
outputPath |
string | stdio only: save the result to this local path (see Output & file delivery) |
asAttachment |
boolean | Return the bytes as a downloadable attachment instead of inline |
returnLink |
boolean | Return a public one-time download URL instead of the file. Ignored when webhookUrl is set |
| Parameter | Type | Description |
|---|---|---|
lang |
string | BCP-47 locale (e.g. "fr-fr", "en-us"): affects number/currency/translation formatting |
timezone |
string | IANA timezone for date formatting (e.g. "America/New_York") |
translations |
object | Translation map for {t(key)} tags: { "fr-fr": { "hello": "Bonjour" } } |
complement |
object | Extra data accessible via {c.field} tags (e.g. company info, logos) |
enum |
object | Enum map for the :convEnum formatter: with { "STATUS": { "1": "Active" } }, {d.status:convEnum('STATUS')} prints Active for 1 |
variableStr |
string | Predefined aliases, in the alias syntax {#name = path}: with "{#total = d.order.total}", the template writes {$total} for {d.order.total}. An alias is a shortcut to a tag, not a computed value |
currencySource |
string | ISO 4217 source currency (e.g. "EUR") |
currencyTarget |
string | ISO 4217 target currency (e.g. "USD") |
currencyRates |
object | Exchange rates: { "EUR": 1, "USD": 1.08 } |
hardRefresh |
boolean | Recompute TOC and pagination after render (requires convertTo) |
| Parameter | Type | Description |
|---|---|---|
async |
boolean | HTTP with async renders on only. Renders in the background (10-minute timeout) with this server's own webhook, and returns a job ID at once; get_render_result returns the download link. Works for batches (batchSplitBy). Mutually exclusive with webhookUrl |
webhookUrl |
string | Enables async rendering (10-minute timeout). The tool then returns only Carbone's acceptance message, never the document: Carbone POSTs { "success": true, "data": { "renderId": "…" } } to this URL, and the server behind it downloads the document from GET /render/{renderId} (one-time, no auth). The agent cannot fetch it. outputPath, asAttachment and returnLink are ignored |
webhookHeaders |
object | Additional headers sent with the webhook POST (e.g. auth headers) |
egressAuthorization |
string | Authorization header value Carbone adds to its outbound requests while rendering: external images ({d.imageUrl}), external PDFs (:appendFile/:attachFile), and webhooks. Max 511 chars. webhookHeaders.authorization overrides it for webhook calls only |
Batch rendering is always asynchronous: pass
async: truewhen the server runs async renders, or awebhookUrlthat receives the result as above. At most 100 objects per batch on Carbone Cloud.
| Parameter | Type | Description |
|---|---|---|
batchSplitBy |
string | One document per object of an array: "d" when data is itself an array, or "d.items" for a direct child array. At most 100 objects on Carbone Cloud |
batchOutput |
"zip" | "pdf" |
"zip" (default): one archive of all documents. "pdf": the PDFs concatenated into one file (requires convertTo: "pdf") |
batchReportName |
string | Name of each file in the ZIP, without extension, Carbone tags allowed (e.g. "invoice-{d.id}"). Ignored with batchOutput: "pdf". From Carbone v5.14, an index is appended to every file when two names collide |
The JSON-valued parameters (data, complement, translations, enum, currencyRates) can be given inline (an object, or an array for data) or as a string reference that the server reads and parses. This keeps large datasets (and big translation maps) out of the tool call, cutting token cost, especially for batch.
A string value is resolved as:
| Reference | Resolved as | stdio | HTTP |
|---|---|---|---|
"/data/invoices.json", "~/data.json" |
local file → parsed JSON | ✅ | ❌ refused (stdio only) |
"https://example.com/data.json" |
downloaded → parsed JSON | ✅ | ✅ |
| base64 of a JSON document | decoded → parsed JSON | ✅ | ✅ |
'{"customer":"Acme"}' / '[…]' |
parsed directly as inline JSON | ✅ | ✅ |
Render template T123 with the data in /data/invoices.json, output PDF
Render T123 with translations from https://cdn.example.com/i18n.json, lang fr-fr
A string is never ambiguous with inline JSON: inline data is passed as an object/array, so a string always means "reference". Same size guard (
CARBONE_MAX_FILE_BYTES) and URL timeout asfile/template.
List the Carbone tags a template uses and return a sample JSON dataset matching its structure. Use it before render_document when you don't know which data a template expects.
Provide exactly one of: templateId or template (never both).
Which data does template 1530905183164918624 expect?
List the Carbone tags of /path/to/invoice.docx and give me sample data for it
| Parameter | Type | Description |
|---|---|---|
templateId |
string | A stored template: Template ID (64-bit, inspects its deployed version) or Version ID (SHA-256, inspects that exact version) |
template |
string | A template that is not stored, in the same forms as render_document's template: absolute local path (stdio only), URL, or base64 (File inputs) |
attachedTemplate |
object | HTTP only. A file attached to the ChatGPT conversation, used like template (Chat attachments) |
Output: a text summary (the tags, then the sample as JSON), and structured output:
| Field | Type | Description |
|---|---|---|
tags |
string[] | The tags as written in the template, e.g. {d.customer.name}, {d.items[i].label}, {c.company}. {t()} translation tags are not listed |
sample |
object | data: a sample dataset matching the template's structure, with placeholder values. complement: the same for {c.} tags, present when the template uses them. Replace the placeholder values, then pass sample.data as render_document's data (and sample.complement as complement) |
signatures |
array? | The signature fields found in the template (electronic signatures). Present only when the template has any |
error |
object? | An error Carbone reported while inspecting the template. Present only when there is one |
The text summary also lists the signature fields and the error, when present.
Cost: inspecting runs one render on your Carbone account (counted like a document generation) and discards the document. The tool is read-only: it changes no template and writes no local file.
List stored templates with filtering, search, and pagination.
| Parameter | Type | Description |
|---|---|---|
id |
string? | Filter by Template ID (64-bit) |
versionId |
string? | Filter by Version ID (SHA-256) |
category |
string? | Filter by category (e.g. "invoices") |
origin |
number? | Upload origin: 0 = API, 1 = Carbone Studio, 2 = Salesforce, 3 = Odoo, 4 = HubSpot integration |
search |
string? | Fuzzy search on name, or exact match on Template ID / Version ID |
includeVersions |
boolean? | Return full version history (default: false) |
limit |
number? | Max results (default: 100) |
cursor |
string? | Pagination cursor from previous nextCursor |
List all template categories in your account. No parameters.
Returns an array of category name strings.
List all tags used across your templates. No parameters.
Returns an array of tag name strings.
Store a reusable template in Carbone.
Upload /path/to/invoice.docx as "Invoice Template", category "invoices"
| Parameter | Type | Required | Description |
|---|---|---|---|
template |
string | ✅ | Absolute local path (stdio only), URL, or base64 (File inputs). Over HTTP, required unless attachedTemplate is given |
attachedTemplate |
object | ❌ | HTTP only. A file attached to the ChatGPT conversation (Chat attachments). Mutually exclusive with template |
requestUploadUrl |
{ size, sha256 } |
❌ | HTTP with MCP_TICKET_SECRET only. Returns an upload URL for this file only, instead of uploading it (Upload URLs). Mutually exclusive with template and sample |
name |
string? | ❌ | Display name, max 200 chars. Recommended: list_templates shows it and its search matches it. Defaults to the file name of attachedTemplate |
id |
string? | ❌ | Existing Template ID to add this upload as a new version |
versioning |
boolean? | ❌ | Enable versioning (default: true). false returns only templateId (SHA-256) and templateExtension |
category |
string? | ❌ | Category (e.g. "invoices"), max 200 chars |
comment |
string? | ❌ | Free-text note about this version, max 200 chars |
tags |
string[]? | ❌ | Labels shown by list_tags and on each list_templates result (e.g. ["sales", "v2"]). Duplicates are removed and the list is sorted; the whole list is limited to 100 characters |
sample |
object[]? | ❌ | Sample data for Carbone Studio: at most one object, with the optional keys data, complement, translations, enum (no other keys) |
deployedAt |
number? | ❌ | Unix timestamp to set as deploy time. Use 42000000000 for "now". Future values are not allowed |
expireAt |
number? | ❌ | Unix timestamp at which the template is scheduled for deletion; 0 (default) = never. To delete now, use delete_template |
Response:
Template uploaded successfully!
Template ID : 1530905183164918624
Version ID : 929a…
Type : html
Size : 46 bytes
Deployed at : 0 (not explicitly deployed: if another version of this Template ID is deployed, renders by Template ID keep using it). To use this version, deploy it with update_template_metadata (templateId = this Version ID, deployedAt = 42000000000), or render it by its Version ID.
Name : Invoice Template
Structured output: id, versionId, type, size, createdAt, deployedAt (versioned mode) or templateId, templateExtension (versioning disabled), plus name when one was given. deployedAt is 0 when the version is not explicitly deployed.
Rename, re-categorise, tag, deploy, schedule the deletion of, or move one template version.
| Parameter | Type | Required | Description |
|---|---|---|---|
templateId |
string | ✅ | Template ID (patches only its currently deployed version) or Version ID (patches that exact version) |
moveToTemplateId |
string? | ❌ | Structural change: moves the patched version to this other Template ID (the API's id body field). Pass the Version ID as templateId; with a Template ID, its deployed version is moved and that Template ID falls back to its next most recent version |
name |
string? | ❌ | New display name, max 200 chars |
comment |
string? | ❌ | New free-text comment, max 200 chars |
category |
string? | ❌ | New category, max 200 chars |
tags |
string[]? | ❌ | New tags, replacing the existing ones entirely (same rules as upload_template) |
deployedAt |
number? | ❌ | Unix timestamp to activate this version. Use 42000000000 for "now". Future values are not allowed, and the deployed version's deployedAt cannot move back in time |
expireAt |
number? | ❌ | Unix timestamp at which the patched version is scheduled for deletion. 0 cancels a scheduled deletion; omit it to leave the expiration unchanged |
Response:
Template metadata updated for version 929a… (the currently deployed version of Template ID 1530905183164918624).
Updated fields: {"name":"Invoice v2"}
Structured output: versionId (the patched version) plus the updated fields echoed back by Carbone (id, name, comment, category, tags, deployedAt, expireAt).
Delete a template. Takes effect immediately: it is no longer listed, downloadable or renderable (404); the file itself is purged after the retention delay (Carbone Cloud: 24 hours).
| Parameter | Type | Required | Description |
|---|---|---|---|
templateId |
string | ✅ | Template ID (deletes all versions) or Version ID (deletes one version) |
To schedule a deletion instead, use update_template_metadata with expireAt set to a future Unix timestamp.
Download the original template file (DOCX, XLSX, etc.), or the JSON sample data stored with it.
| Parameter | Type | Required | Description |
|---|---|---|---|
templateId |
string | ✅ | Template ID (downloads deployed version) or Version ID (downloads exact version) |
sample |
boolean? | ❌ | true downloads the JSON sample dataset stored with the template (the sample passed to upload_template) instead of the template file, returned inline as JSON. Errors if the template has no sample |
outputPath |
string? | ❌ | stdio only: save the file to this local path |
asAttachment |
boolean? | ❌ | Return the file as a downloadable attachment instead of inline |
Offered only when the server runs async renders. Returns the result of a render_document call made with async: true.
| Parameter | Type | Required | Description |
|---|---|---|---|
jobId |
string | ✅ | The job ID render_document returned |
Output: the one-time download link once the document is ready, the render error if it failed (or no result after 10 minutes), or "still rendering" (call again a few seconds later). Results are kept 1 hour, and only the caller who started the render can read them.
Find a ready-to-run example from carbone.io/examples: a real template with its JSON data, the document it produces, and a page that explains its tags. There are two kinds: the gallery (complete business documents: invoices, labels, reports, e-invoices, slides...) and the format guides (one feature of one format, for beginners).
Show me what Carbone can do with an Excel budget
Find an invoice example with a barcode and generate it as a PDF
How do I make a loop in a PowerPoint template? Show me an example
All parameters are optional. Without any, the tool returns the newest examples and the list of use cases.
| Parameter | Type | Description |
|---|---|---|
query |
string | Keywords, e.g. invoice barcode, excel chart, shipping label. "Word", "Excel" and "PowerPoint" match their formats |
useCase |
string | finance, logistics, reports, compliance, tickets, planning, presentations, publishing |
templateFormat |
string | Template format, e.g. docx, xlsx, html |
resultFormat |
string | Generated format, e.g. pdf, xlsx, or a label such as edi |
level |
string | beginner, intermediate or advanced |
kind |
string | gallery or format-guide |
id |
string | One example, by its id |
limit |
integer | 1 to 25 results (default 8) |
Output: each example with its files (template, data, expected result, a preview image of the result), its page in Markdown, and renderArguments: the render_document arguments that fill the template with its data, to pass unchanged. The result keeps the template's format. The structured output has total (all matches) and examples.
Converting is optional. When the example shows another format (a DOCX template shown as a PDF), conversion says what to add for it, for information: convertTo, and a converter only when one is advised. The default converter, L (LibreOffice), has the widest compatibility; C (Chromium) is advised for HTML and SVG templates; from DOCX or ODT to PDF, I (Carbone ICE) is the fastest, and the result says so.
What the AI can do with an example:
- Try Carbone:
render_documentwith itsrenderArgumentsgenerates the document. Nothing is stored in your account (it counts as one document generation). Add a conversion only if you want another format. To just show what an example looks like, its preview image is enough: no render needed. - Fill it with your data:
inspect_templateon its template URL lists the tags and a sample dataset, the shape your data takes. - Learn a feature: search it (
barcode,chart,loop,translations), then read the example's page. - Proof the template:
convert_documenton its template URL shows it with its tags as written. - Make it yours:
upload_templatewith its template URL stores it in your account; edit it in Word, Excel or PowerPoint, then upload it again.
The catalog: the server downloads https://carbone.io/examples/examples.json on the first call, then checks it once a day, without making a call wait. An unchanged file is not downloaded again (ETag) nor reloaded (same SHA-256). If a check fails for any reason (network, DNS, HTTP error, unexpected content), the server keeps the copy it has and tries again 10 minutes later. Only files on carbone.io are offered. The tool is read-only and sends nothing about you or your templates.
Check Carbone API health and current version. No parameters.
Returns the API version string and a status message.
Returns a full overview of supported formats, features, and usage examples. No parameters.
The server serves the Carbone Skill, the template syntax reference for AI assistants, through the MCP Skills extension (io.modelcontextprotocol/skills, SEP-2640). A client that supports the extension finds it with skills/list and loads it when a template needs writing or fixing, without installing anything else.
| Skill | skill://carbone/SKILL.md, and its references under skill://carbone/references/ |
| Methods | skills/list, skills/get, resources/read, and resources/directory/read (directoryRead: true) |
| Version | The carbone-agent-plugin release pinned in skills.lock.json, the same as the skill's metadata.version: each server release ships the skill matching its tools |
| Transports | stdio and HTTP, both protocol eras |
The skill is part of the npm package and the Docker image: nothing is downloaded at build or run time, so it works the same on mcp.carbone.io, on a self-hosted server and offline. Clients without the extension can still read skill://carbone/SKILL.md as an ordinary resource: the server instructions and get_capabilities name it before its web copy. If the skill cannot be loaded (the startup log then says skills=none), they name the web copy only, so a model never looks for a resource that is not there.
file (convert_document) and template (render_document, inspect_template, upload_template) accept three forms:
| Form | Example | stdio | HTTP |
|---|---|---|---|
| Local path | /Users/me/invoice.docx, ~/invoice.docx, C:\Users\me\invoice.docx |
✅ | ❌ refused: the server cannot read the caller's disk |
URL (http:// or https://) |
https://example.com/invoice.docx |
✅ | ✅ |
| Base64 | the file content, base64-encoded | ✅ | ✅ |
A string that is neither a URL nor a path (starting with /, ./, ../, ~ or a drive letter) is taken as base64: a bare file name such as invoice.docx is not looked up and fails. Relative paths resolve against the server's working directory, which the client chooses, so prefer absolute paths. URLs are SSRF-guarded (see below), and every form is limited to CARBONE_MAX_FILE_BYTES. The JSON parameters passed by reference follow the same rules (Pass JSON by reference).
ChatGPT passes a file the user attached to the conversation only to a tool input listed in the tool's _meta["openai/fileParams"] (OpenAI Apps SDK reference). Over HTTP, the server declares one such input per file tool: attachedFile for convert_document's file, and attachedTemplate for the template of render_document, inspect_template and upload_template.
ChatGPT fills the input with { "download_url": "https://…", "file_id": "file_…", "mime_type": "…", "file_name": "…" }. The server downloads download_url (HTTPS only) with the same URL guard and size limit as a URL input. Give either the attachment or the string input, not both. upload_template uses file_name as the template name when name is not given.
Other clients ignore _meta: they see an optional parameter and leave it empty. The inputs are not offered in stdio, where a local path does the job.
A file too large to pass as base64 can be sent outside the MCP messages, by an assistant that can run shell commands (Claude Code, Cursor, VS Code, or a code sandbox allowed to reach the server). The server must run over HTTP with MCP_TICKET_SECRET set.
upload_templatewithrequestUploadUrl: { "size": <bytes>, "sha256": "<hex>" }(and any other field:name,category,versioning,expireAt…) returnsuploadUrlandheaders(anX-Upload-Token), and the command to send the file in its text. Nothing is stored yet.- The file is POSTed as the raw body with those headers:
curl -H 'X-Upload-Token: …' --data-binary @<file> <uploadUrl>. The server streams it to Carbone as it arrives and answers with the stored template, asupload_templatewould (id,versionId, …).
The URL accepts only the file it was issued for: a different size or SHA-256 is refused, and nothing is stored. It is valid for 10 minutes, or until the caller's sign-in expires if that comes first. Sending the same file again within that time stores no new template when versioning is false; otherwise it stores another copy (a new Template ID, or a new version of id when given). It runs at most 2 uploads at once per caller (the signed-in user or the API key) and 1 per URL, and drops an upload whose first bytes take over 5 seconds, or arriving slower than 1 MiB per 30 seconds.
The token is encrypted with AES-256-GCM and carries the caller's credential: the OAuth access token on the hosted server, the Carbone API key in API-key mode. It ends up in the assistant's conversation and shell history, where only this server can read it, with MCP_TICKET_SECRET. Keep that secret private: anyone holding it could read the credentials in tokens they have seen. Changing it makes the URLs issued just before invalid, and their error says to ask for a new one.
Server instances share nothing but the secret, so the URL works whichever instance receives the file. The secret is bound to MCP_PUBLIC_URL: two deployments sharing it (staging and production) never accept each other's URLs.
The server downloads URL inputs itself (file, template, and JSON parameters such as data passed by reference), on both transports, with these protections:
- Only
http://andhttps://URLs are fetched. - Unless
CARBONE_ALLOW_PRIVATE_NETWORK=true, a URL is refused when it points at a loopback, private (RFC 1918), link-local (including the cloud metadata address169.254.169.254), CGNAT, multicast or reserved address, in any IPv4 or IPv6 notation (including IPv4 addresses embedded in IPv6). - The check applies to the address the connection actually uses, so a DNS answer cannot change between the check and the connection (DNS rebinding). Redirects are followed by the server, at most 5 hops, and every hop is checked again.
- A download stops as soon as it passes
CARBONE_MAX_FILE_BYTES, and times out after 60 seconds. - A call without an API key (when the Carbone API needs one) fails before anything is downloaded.
- A failed download reports only an HTTP status code or a fixed error code, never text chosen by the remote server.
Local paths are a separate guard: they are read in stdio only, where the server already runs as you. Over HTTP they are refused, so a remote caller can never make the server read its own filesystem.
convert_document and render_document (and download_template, for outputPath / asAttachment) decide how the generated bytes reach the client. By default this depends on the format and the transport:
| Output | stdio (local clients) | HTTP (remote / self-hosted) |
|---|---|---|
| Text: HTML, XHTML, TXT, CSV, MD, XML, JSON (template samples) | inline text |
inline text |
| Inline images: PNG, JPG, GIF, WEBP | inline image |
inline image |
| Everything else (PDF, Office, SVG, TIFF, BMP, EMF…) | saved to a temp file, path returned as text | one-time download link (as with returnLink) |
Override the default with these optional parameters:
| Parameter | Behaviour |
|---|---|
outputPath |
stdio only. Write the output to this local path and return a summary instead of the bytes. The path must not exist yet: an existing file (or symlink) is never overwritten, and the new file is readable by the current user only (0600). In HTTP mode it is rejected (the file would land on the server, not your machine). |
asAttachment |
Return the bytes as an EmbeddedResource download attachment for any format (including text/images), instead of inlining or a link. Over HTTP, this is how to receive a PDF or Office file's bytes (or pass returnLink: false). |
returnLink |
Render without returning the bytes; instead return Carbone's public download URL (<API URL>/render/{renderId}?download=true, which downloads the file as an attachment named after reportName; a conversion has no templating pass, so its file is report.<ext>). Over HTTP it is the default for outputs not returned inline; false asks for the bytes. The link is one-time and short-lived (Carbone deletes the file after the first download), so pass it to the end user and do not fetch it yourself. Works in both transports. Mutually exclusive with outputPath / asAttachment; ignored when webhookUrl is set. |
Claude Desktop note: Claude Desktop (and claude.ai) mis-handle inline binary
EmbeddedResourceblobs: they coerce them into image blocks and reject the media type. The same blocks render correctly in Cursor, VS Code, and the MCP Inspector. This is why HTTP returns a link for PDF and Office outputs by default; with the local package, use the default temp-file path orreturnLink.
Batch generation (batchSplitBy) and renders over a minute need Carbone's asynchronous mode, which delivers the result to a webhook. An assistant has no webhook of its own, so the server can be one: render_document with async: true returns a job ID at once, and get_render_result returns the download link when the document is ready.
- The server gives Carbone its own
/webhookURL, and a sealed job token in a header Carbone sends back. - Carbone renders, then calls
/webhookonce with the renderId. The instance receiving it stores the result in the shared store, encrypted, under a hash of the job. The first result recorded is final. get_render_resultreads it, from any instance, for the caller who started the render (the same OAuth user or API key).
Requirements, HTTP only: MCP_TICKET_SECRET, and a store every instance shares (Configuration), since the webhook call and the next request rarely reach the same instance:
- an S3-compatible bucket (AWS S3, MinIO, Cloudflare R2…), set with the five
MCP_S3_*variables. Add a lifecycle rule deletingjobs/objects after 1 day to clean the bucket. - or a directory,
MCP_JOBS_DIR: for a single instance, or a volume mounted by every instance. A disk that belongs to each instance (container ephemeral storage) does not work with more than one. The server deletes files older than 1 hour itself.
Results are a few hundred bytes each.
Carbone stops an async render after 10 minutes, and calls the webhook once without retrying: a job with no result after 10 minutes (the render too long, or its result lost on the way) is reported failed, to start again.
The server supports two transport modes, chosen with the MCP_TRANSPORT environment variable. It supports MCP protocol 2026-07-28 and still serves clients on the earlier 2025-era protocol, over both stdio and HTTP.
Used by AI desktop clients (Claude Desktop, Claude Code, VS Code, Cursor). The client launches the server as a child process and communicates over stdin/stdout.
CARBONE_API_KEY=your_key npx carbone-mcpCARBONE_API_KEY is required at startup when targeting the Carbone cloud API (https://api.carbone.io). It can be omitted when CARBONE_BASE_URL points to an on-premise server.
Runs a Streamable HTTP server. Used for self-hosted deployments accessible to web-based or remote MCP clients.
MCP_TRANSPORT=http MCP_PORT=3000 npx carbone-mcp
# or with Docker, where HTTP is the default
docker run -d -p 127.0.0.1:3000:3000 carbone/carbone-mcpCARBONE_API_KEY is optional in HTTP mode. Each incoming request can supply its own key via the Authorization: Bearer <key> header, which takes precedence over the server-level env var. This allows multiple users to connect with their own API keys without sharing a single server-level key.
| Auth scenario | Behaviour |
|---|---|
CARBONE_API_KEY set at startup |
Used as fallback for requests without a Bearer token (a shared-key server: anyone who can reach the port spends that key; the server warns at startup) |
CARBONE_API_KEY set and CARBONE_REQUIRE_CLIENT_AUTH_HEADER=true |
No fallback: a request without a Bearer token gets the error below |
| Bearer token in request | Always takes precedence over the server-level key |
| Neither set, cloud API | The tool call returns the tool error Authentication failed: No API key provided… before anything is sent or downloaded |
On-premise (CARBONE_BASE_URL custom) |
No key required in any mode |
Deploying it: no server key (each client sends its own Bearer key) is the safe default. Publish the port on 127.0.0.1 for local use (docker run -p 127.0.0.1:3000:3000 …), and behind a TLS reverse proxy for remote clients. The HTTP settings (MCP_PORT, MCP_PATH, MCP_ALLOWED_ORIGINS, …) are listed under Configuration.
Endpoint behaviour (at MCP_PATH):
| Request | Response |
|---|---|
POST |
MCP over Streamable HTTP, stateless (no sessions). Serves protocol 2026-07-28 (server/discover, per-request _meta) and 2025-era clients that open with initialize. Closing the response stream cancels the request, including its upstream Carbone API call. |
GET, DELETE |
405 Method not allowed: no standalone SSE stream, no sessions (opening the endpoint in a browser shows this) |
Origin header present but not allowed |
403 before the request is processed (DNS-rebinding protection). Requests without an Origin header are unaffected. |
| Malformed or empty JSON body | 400 with JSON-RPC parse error -32700 |
Body over MCP_MAX_BODY_BYTES |
413 |
CORS preflights (OPTIONS) are answered 204; allowed request headers are Content-Type, Authorization, Mcp-Protocol-Version, Mcp-Method and Mcp-Name.
The server reads these environment variables at startup. Numbers must be positive integers and booleans true or false; an invalid value stops the server with an error.
| Variable | Default | Description |
|---|---|---|
CARBONE_API_KEY |
none | Your Carbone API key (account.carbone.io). stdio: required for Carbone Cloud; without it the server stops at startup. HTTP: optional; leave it unset so each client sends its own Authorization: Bearer <key>, which always takes precedence. When set, requests without a Bearer key spend it (see CARBONE_REQUIRE_CLIENT_AUTH_HEADER). Not needed when CARBONE_BASE_URL points to an on-premise server. |
CARBONE_BASE_URL |
https://api.carbone.io |
Carbone API base URL. Point it at your on-premise instance; with any URL other than the default, no API key is required. |
CARBONE_TIMEOUT |
60000 |
Timeout of each Carbone API request, in milliseconds. The server sets no maximum, but Carbone Cloud's synchronous API has its own 60-second limit. URL downloads have a separate, fixed 60-second timeout. |
CARBONE_MAX_FILE_BYTES |
104857600 (100 MB) |
Largest input the server resolves from a local path, URL or base64 string: file, template, and the JSON parameters passed by reference. A download stops as soon as it passes the limit. |
MCP_TRANSPORT |
stdio |
stdio for local clients, or http for a Streamable HTTP server. The Docker image sets http. |
MCP_PORT |
3000 |
HTTP listening port. |
MCP_PATH |
/ |
HTTP endpoint path. Must start with / and cannot be /health (reserved). |
MCP_MAX_BODY_BYTES |
62914560 (60 MB, Carbone Cloud's JSON data limit) |
Largest incoming MCP message: an HTTP request body, answered 413 as soon as the limit is passed, or one stdio message. |
MCP_ALLOWED_ORIGINS |
none | HTTP only. Browser Origin hostnames allowed in addition to localhost, 127.0.0.1 and [::1], which are always allowed: comma-separated, without scheme or port (e.g. app.example.com); <scheme>://* allows a browser-extension scheme (e.g. moz-extension://*). A request with any other Origin gets 403; requests without an Origin are unaffected. Invalid entries stop the server at startup. |
CARBONE_REQUIRE_CLIENT_AUTH_HEADER |
false |
HTTP only. true requires Authorization: Bearer <key> on every request. Left false, a request with no Bearer key falls back to the server-level CARBONE_API_KEY (a shared-key server: anyone reaching the port can spend it, and the server warns at startup). No effect when no server key is set. |
CARBONE_ALLOW_PRIVATE_NETWORK |
false |
true lets URL inputs resolve to private and internal addresses (URL guard). Off by default to block SSRF; enable it only on a trusted deployment with internal template hosts. |
MCP_ENABLED_TOOLS |
all tools | Only the tools you list are available, comma-separated. See Choosing the tools. |
MCP_TICKET_SECRET |
none | HTTP only. Turns on upload URLs, and async renders with MCP_S3_* or MCP_JOBS_DIR: at least 32 random bytes, base64 (openssl rand -base64 32), the same on every instance. |
MCP_PUBLIC_URL |
origin of MCP_RESOURCE_URL |
HTTP only. The server's public origin (e.g. https://mcp.example.com), used to build upload URLs and the async render webhook. Required with MCP_TICKET_SECRET in API-key mode, where the server cannot know the address clients reach it at. |
MCP_S3_ENDPOINT |
none | HTTP only, for async renders: the S3-compatible service origin, e.g. https://s3.us-east-1.amazonaws.com (http on localhost only). Set all five MCP_S3_* variables, or none. |
MCP_S3_REGION |
none | The bucket region, e.g. us-east-1. |
MCP_S3_BUCKET |
none | The bucket async render results are kept in. |
MCP_S3_ACCESS_KEY_ID |
none | An access key allowed to read, write and list that bucket (without list, S3 answers 403 instead of 404 for a missing object; the server checks this at startup and logs it). |
MCP_S3_SECRET_ACCESS_KEY |
none | Its secret key. |
MCP_JOBS_DIR |
none | HTTP only, for async renders, instead of MCP_S3_*: the absolute path of an existing, writable directory that every instance shares. |
MCP_OPENAI_APPS_CHALLENGE |
none | HTTP only. The domain-verification token OpenAI gives when you submit the server to the ChatGPT plugin directory. When set, the server returns it as plain text at /.well-known/openai-apps-challenge. |
MCP_MUSE_CHALLENGE |
none | HTTP only. The domain-verification token Meta gives when you submit the server to its connector directory (the hex string at the end of the file URL, or the whole muse-challenge=<token> line). When set, the server returns muse-challenge=<token> as plain text at /.well-known/muse-challenge/<token>. |
By default, every tool is available. Set MCP_ENABLED_TOOLS to offer only some of them, for example:
- an agent that must not change or delete your templates;
- a self-hosted Carbone that does not support every tool.
A read-only agent, for example, can render and convert documents and browse templates, but not upload, edit or delete them:
MCP_ENABLED_TOOLS=convert_document,render_document,get_render_result,inspect_template,list_templates,list_categories,list_tags,download_template,get_api_status,find_template_examplesWhat to know:
- A tool you don't list is gone for the AI. It can't be called, and the server never mentions it: not in the tool list, the instructions or
get_capabilities. Itscarbone://resources go with it. get_capabilitiesis always available, listed or not: it is the overview the other tools point to.- New tools stay off. When a new version adds a tool, it is not available until you add it to the list. Check the changelog when you upgrade.
- Related features follow their tools. Upload URLs need
upload_template. Async renders need bothrender_documentandget_render_result. - A typo stops the server. Names are case-sensitive, and an unknown name fails at startup with the list of valid ones, so a tool is never turned off by mistake.
- Check what is served in the startup log:
enabled=over HTTP,Enabled tools:on stdio.
Leaving the variable unset or empty makes every tool available.
Carbone uses these variables to run mcp.carbone.io. Self-hosted and on-premise servers leave them unset: OAuth mode needs this server to be registered as a resource server at account.carbone.io, which only Carbone does.
Setting MCP_OAUTH_CLIENT_ID, MCP_OAUTH_CLIENT_SECRET and MCP_RESOURCE_URL turns the HTTP server into an OAuth 2.1 resource server:
- MCP clients that implement MCP authorization (2025-06-18 or later) sign in with their Carbone account. A request without credentials gets
401with aWWW-Authenticatechallenge pointing to the protected-resource metadata, without an error code (RFC 6750 §3.1). A malformed Bearer gets400invalid_request, a token that fails verification401invalid_token, and a token withoutdoc_rwd403insufficient_scope. - Each token is introspected (RFC 7662) and exchanged (RFC 8693) for a short-lived Carbone token, the only one sent to the Carbone API: the client's own token never reaches it.
- A Carbone API key, or a Carbone JWT issued through OAuth to another client or to a client that sent no
resource, is refused with401without asking the authorization server: it was not issued for this server (MCP authorization specification). API keys work with the local package and self-hosted servers. - A client that never sends the RFC 8707
resourceparameter gets a token bound to nothing, which is refused with401.
A client may get 429 or 503 with Retry-After: it retries after that delay.
Setting only some of these variables, or CARBONE_API_KEY with them, stops the server at startup.
| Variable | Default | Description |
|---|---|---|
MCP_OAUTH_ISSUER |
https://account.carbone.io |
The authorization server, as an https origin without a path or trailing slash, exactly as it writes its own issuer: tokens are introspected at <issuer>/api/oauth/introspect and exchanged at <issuer>/api/oauth/token. |
MCP_OAUTH_CLIENT_ID |
none | This server's client ID, registered at the authorization server as the resource server for MCP_RESOURCE_URL (client_secret_basic). |
MCP_OAUTH_CLIENT_SECRET |
none | This server's client secret; never logged. |
MCP_RESOURCE_URL |
none | The URL MCP clients connect to, exactly as they enter it: the protected resource advertised at /.well-known/oauth-protected-resource[/<path>] (RFC 9728) and the audience every token must be bound to. An origin is written without a trailing slash (https://mcp.carbone.io); its path (/ for an origin) must equal MCP_PATH. |
Available in HTTP mode at GET /health. Always returns HTTP 200: the status code signals MCP server liveness.
curl http://localhost:3000/healthResponse:
{
"mcp": { "version": "2.5.0" },
"carbone": { "version": "5.x.x" }
}The carbone field reflects backend connectivity:
| Value | Meaning |
|---|---|
{ "version": "..." } |
Reachable and authenticated |
{ "error": "unauthorized", "message": "..." } |
Reachable but no/invalid API key |
{ "error": "unreachable", "message": "..." } |
Network error, timeout, or unexpected response |
{ "status": "checking" } |
Right after start, until the first check completes |
In HTTP mode, the server writes one logfmt line per event on stderr, starting with level=, so log viewers detect the level:
level=info msg="running in HTTP mode" version=2.5.0 skills=carbone@x.x.x mcp=http://0.0.0.0:3000/ health=http://0.0.0.0:3000/health
level=info msg=request method=POST path=/ status=200 ms=412 ip=203.0.113.7 mcp=tools/call tool=render_document proto=2025-11-25 ua=claude-code/2.1 user=sub:42 oauth_client=example-client outcome=ok rid=9f2c1a7b04d6e358
level=error msg=request method=POST path=/ status=200 ms=60012 ip=203.0.113.7 mcp=tools/call tool=convert_document user=key:3445f6f99c76 outcome=error error_type=upstream error="Carbone API request timed out after 60 s." rid=0f7090b8c1d2e3f4
| Level | Meaning |
|---|---|
info |
A request answered, and server events. |
warn |
A tool or resource error; an MCP request refused (4xx, 401 excepted, which starts signing in); the msg="HTTP error" line of a refused body; and conditions to check: the Carbone API unreachable, the authorization server paused, the job store unreadable, a skill not served (msg=skills, at startup), the examples catalog not refreshed (msg="examples catalog not refreshed"). |
error |
A 5xx answer; an upstream outage or an internal bug (error_type); a server failure. |
| Field | Meaning |
|---|---|
skills |
On the startup line: the skills served, as name@version (Carbone Skill), or none. |
ip |
The client's address, found past the internal proxies in X-Forwarded-For. |
mcp, tool |
The JSON-RPC method (batch for a batch), and the tool a tools/call names. |
client, proto, ua |
The client's name and version (on initialize and on every 2026-07-28 request), its Mcp-Protocol-Version and its User-Agent. |
user |
sub:<OAuth subject> or key:<first 12 hex characters of the API key's SHA-256>, never a token or a key. |
oauth_client |
OAuth mode: the client ID the token was issued to. |
outcome, error |
ok or error for a tool call or a resource read, with the start of the error's text. A request the MCP SDK refuses (invalid arguments, unknown tool or method) is error without text. A few 2025-era methods the SDK refuses itself (e.g. subscriptions/listen without a 2026-07-28 claim) are not marked. |
error_type |
upstream for a Carbone API outage, internal for a bug in this server. |
reason |
Why a 401 was answered: no-token or invalid-token. |
aborted |
1 when the client left before the answer was sent. |
rid |
The request's id, also on every other line written while it runs, and returned in the X-Request-Id response header. |
Values are cut to 300 characters. Tool arguments and results are not logged, except the first 200 characters of a tool or resource error, with URLs reduced to their host and long tokens redacted. /health requests from an internal address (the platform's own probe) are not logged.
The 36 values accepted by convertTo:
Documents: pdf, docx, doc, odt, ott, rtf, epub
Spreadsheets: xlsx, xls, ods, ots, csv, dbf, dif
Presentations, drawings: pptx, ppt, odp, otp, odg
Web/Text: html, xhtml, txt, md, xml, idml
Images: png, jpg, jpeg, webp, gif, tiff, bmp, svg, emf, wmf, eps
Valid outputs depend on the input format. doc, xls and ppt are output-only (rejected as input). zip is not an output format: batch archives come from batchOutput.
Full conversion matrix: carbone.io documentation