Skip to content

Latest commit

 

History

History
741 lines (536 loc) · 55.6 KB

API.md

File metadata and controls

741 lines (536 loc) · 55.6 KB

Carbone MCP API reference

Full parameter reference for the 12 tools of the Carbone MCP server, and for running the server itself. For setup, start with the README.

Table of contents

Document operations

Template management

Discovery

Server


convert_document

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_document and render_document use 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, PDF. The legacy binary formats DOC, XLS and PPT are rejected as input (415, error w118) even though Carbone can produce them as output: re-save them as DOCX/XLSX/PPTX first.

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_document to resolve tags into real values, or render_document with keepTags to 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: converter C, with formatOptions: { "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, html or txt, to an image (png, jpg, webp), or is re-saved as pdf (e.g. to add a password, watermarks or PDF/A: the server sets hardRefresh for 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 options
  • I: Carbone ICE, DOCX and ODT → PDF; Carbone's own engine, 3x to 300x faster, recommended over O for 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 default L for 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 → PDF
  • C: 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 from formatOptions (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 PDF Encrypt the PDF; requires DocumentOpenPassword
DocumentOpenPassword PDF Password to open the document
RestrictPermissions PDF Restrict printing, copying and changes; use with PermissionPassword
PermissionPassword PDF Password to change the restricted permissions
Watermarks PDF 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. ";"

render_document

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

Template source (exactly one required)

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)

Data & output

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

Localisation & formatting

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)

Async & webhook

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 generation

Batch rendering is always asynchronous: pass async: true when the server runs async renders, or a webhookUrl that 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

Pass JSON by reference

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 as file / template.


inspect_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_templates

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_categories

List all template categories in your account. No parameters.

Returns an array of category name strings.


list_tags

List all tags used across your templates. No parameters.

Returns an array of tag name strings.


upload_template

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.


update_template_metadata

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_template

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_template

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

get_render_result

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_template_examples

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:

  1. Try Carbone: render_document with its renderArguments generates 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.
  2. Fill it with your data: inspect_template on its template URL lists the tags and a sample dataset, the shape your data takes.
  3. Learn a feature: search it (barcode, chart, loop, translations), then read the example's page.
  4. Proof the template: convert_document on its template URL shows it with its tags as written.
  5. Make it yours: upload_template with 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.


get_api_status

Check Carbone API health and current version. No parameters.

Returns the API version string and a status message.


get_capabilities

Returns a full overview of supported formats, features, and usage examples. No parameters.


Carbone Skill

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 inputs

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).

Chat attachments (ChatGPT)

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.

Upload URLs

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.

  1. upload_template with requestUploadUrl: { "size": <bytes>, "sha256": "<hex>" } (and any other field: name, category, versioning, expireAt…) returns uploadUrl and headers (an X-Upload-Token), and the command to send the file in its text. Nothing is stored yet.
  2. 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, as upload_template would (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.

URL guard

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:// and https:// 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 address 169.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.


Output & file delivery

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 EmbeddedResource blobs: 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 or returnLink.


Async renders

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.

  1. The server gives Carbone its own /webhook URL, and a sealed job token in a header Carbone sends back.
  2. Carbone renders, then calls /webhook once 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.
  3. get_render_result reads 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 deleting jobs/ 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.

Transport modes

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.

stdio (default)

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-mcp

CARBONE_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.

http

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-mcp

CARBONE_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.


Configuration

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>.

Choosing the tools

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_examples

What 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. Its carbone:// resources go with it.
  • get_capabilities is 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 both render_document and get_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.

Hosted server (OAuth mode)

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 401 with a WWW-Authenticate challenge pointing to the protected-resource metadata, without an error code (RFC 6750 §3.1). A malformed Bearer gets 400 invalid_request, a token that fails verification 401 invalid_token, and a token without doc_rwd 403 insufficient_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 with 401 without 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 resource parameter gets a token bound to nothing, which is refused with 401.

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.

Health endpoint

Available in HTTP mode at GET /health. Always returns HTTP 200: the status code signals MCP server liveness.

curl http://localhost:3000/health

Response:

{
  "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

Logs

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.


Supported output formats

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