Carbone MCP

Official

Overview Schema Source Related Servers Discussions Admin

Upload Template

upload_template

Store a reusable Carbone template (DOCX, XLSX, PDF, and more) and get back a Template ID that render_document uses to generate documents, with optional versioning.

Instructions

Upload and store a reusable Carbone template. Once uploaded, use render_document with the returned Template ID to generate documents from it. Supports versioning: multiple versions can live under a single stable Template ID, and rendering by Template ID uses the version with the most recent deployedAt. A result deployedAt of 0 means the version is not explicitly deployed: if another version of the same Template ID is deployed, renders by Template ID keep using that one. Accepted formats: DOCX, XLSX, PPTX, ODT, ODS, ODP, ODG, HTML, XHTML, XML, SVG, IDML, Markdown, TXT, CSV, RTF and PDF (not the legacy binary DOC, XLS or PPT).

Input Schema

Name	Required	Description
`id`	No	Existing Template ID (64-bit format) to add this upload to its version history. If omitted, a new Template ID is generated. Providing a Version ID (SHA-256) is not allowed and will cause an error.
`name`	No	Display name for the template, max 200 characters (e.g. "Invoice Template", "NDA Contract"). Optional but recommended: list_templates shows it and its search matches it.
`tags`	No	Labels shown by list_tags and on each list_templates result (e.g. ["sales", "billing", "v2"]). Duplicates are removed and the list is sorted; the whole list is limited to 100 characters (about 8 tags of 9 characters).
`sample`	No	Sample input data attached to the template for testing in Carbone Studio: an array with at most ONE object, whose keys data, complement, translations and enum are all optional. Example: [{ "data": { "name": "Acme" } }].
`comment`	No	Free-text comment to describe the template version or its purpose, max 200 characters.
`category`	No	Group templates into folders/categories, max 200 characters (e.g. "invoices", "legal", "hr").
`expireAt`	No	Schedule deletion at a UTC Unix timestamp (seconds); 0 (default) means the template never expires. After that time it is no longer listed, downloadable or renderable (404), and the file is purged after the retention delay. To remove a template now, use delete_template.
`template`	Yes	The template file. Three input forms are accepted: (1) Local file path — absolute, e.g. "/Users/me/report.docx" (or "C:\Users\me\report.docx" on Windows), or under the home directory, e.g. "~/report.docx". A relative path must start with "./" or "../" and resolves against the server process's working directory, which is rarely yours: prefer an absolute path. A bare file name such as "report.docx" is NOT a path: it would be sent as base64 content. (2) HTTPS URL — the file is downloaded automatically, e.g. "https://example.com/file.pptx". (3) Base64-encoded string — the raw file content encoded as base64. Supported input formats: DOCX, XLSX, PPTX, ODT, ODS, ODP, ODG, HTML, XHTML, XML, SVG, IDML, MD, TXT, CSV, RTF, PDF. Carbone reads XML-based and text-based documents (plus PDF): the legacy binary Office formats DOC, XLS and PPT are rejected as input, although they are valid outputs. Re-save such a file as DOCX, XLSX or PPTX first.
`deployedAt`	No	UTC Unix timestamp (seconds) to set as the deployment time for this version. Carbone uses the version with the most recent deployedAt when rendering via Template ID. Use 42000000000 to deploy immediately (special "NOW" sentinel value). Future values are not allowed.
`versioning`	No	Enable template versioning (default: true). When true, a stable Template ID is generated and multiple versions can be managed under it. When false, behaves as legacy mode and returns only a templateId (SHA-256 hash) and templateExtension.

Output Schema

Name	Required	Description
`id`	No	Stable Template ID (when versioning is enabled).
`name`	No	Template display name, when one was given.
`size`	No	Template size in bytes.
`type`	No	Detected template file type.
`createdAt`	No	UTC Unix timestamp (seconds) of the upload.
`versionId`	No	Version ID (SHA-256) of this uploaded version.
`deployedAt`	No	UTC Unix timestamp of deployment; 0 means this version is not explicitly deployed.
`templateId`	No	Template ID returned in legacy/non-versioned mode.
`templateExtension`	No	Detected file extension, e.g. "docx" (legacy/non-versioned mode).

Schema Changelog

Changes observed during successful MCP inspections.

Changed3 schema fields changedv2.1.4Oct 27, 2026
- addedInput schema / properties / tags / items / maxLength
```
Added value: +96
```
- addedInput schema / properties / tags / items / minLength
```
Added value: +1
```
- addedInput schema / properties / tags / maxItems
```
Added value: +100
```

Changed24 schema fields changedv2.0.0Oct 14, 2026

changedInput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

changedInput schema / properties / category / description

Previous value: -"Group templates into folders/categories (e.g. \"invoices\", \"legal\", \"hr\")."New value: +"Group templates into folders/categories, max 200 characters (e.g. \"invoices\", \"legal\", \"hr\")."

addedInput schema / properties / category / maxLength
```
Added value: +200
```

changedInput schema / properties / comment / description

Previous value: -"Free-text comment to describe the template version or its purpose."New value: +"Free-text comment to describe the template version or its purpose, max 200 characters."

addedInput schema / properties / comment / maxLength
```
Added value: +200
```

changedInput schema / properties / deployedAt / description

Previous value: -"UTC Unix timestamp (seconds) to set as the deployment time for this version. Carbone uses the version with the most recent deployedAt when rendering via Template ID. Use 42000000000 to deploy immediately (special \"NOW\" sentinel value)."New value: +"UTC Unix timestamp (seconds) to set as the deployment time for this version. Carbone uses the version with the most recent deployedAt when rendering via Template ID. Use 42000000000 to deploy immediately (special \"NOW\" sentinel value). Future values are not allowed."

changedInput schema / properties / expireAt / description

Previous value: -"UTC Unix timestamp (seconds) at which this template will be automatically deleted. Use 42000000000 to delete immediately (special \"NOW\" sentinel value)."New value: +"Schedule deletion at a UTC Unix timestamp (seconds); 0 (default) means the template never expires. After that time it is no longer listed, downloadable or renderable (404), and the file is purged after the retention delay. To remove a template now, use delete_template."

changedInput schema / properties / expireAt / minimum
```
Previous value: --9007199254740991New value: +0
```

changedInput schema / properties / name / description

Previous value: -"Display name for the template (e.g. \"Invoice Template\", \"NDA Contract\")."New value: +"Display name for the template, max 200 characters (e.g. \"Invoice Template\", \"NDA Contract\"). Optional but recommended: list_templates shows it and its search matches it."

addedInput schema / properties / name / maxLength
```
Added value: +200
```

changedInput schema / properties / sample / description

Previous value: -"Sample input data attached to the template for testing in Carbone Studio. Each item must include data, complement, translations, and enum objects."New value: +"Sample input data attached to the template for testing in Carbone Studio: an array with at most ONE object, whose keys data, complement, translations and enum are all optional. Example: [{ \"data\": { \"name\": \"Acme\" } }]."

addedInput schema / properties / sample / items / additionalProperties
```
Added value: +false
```

removedInput schema / properties / sample / items / required

Removed value: -[
-  "data",
-  "complement",
-  "translations",
-  "enum"
-]

addedInput schema / properties / sample / maxItems
```
Added value: +1
```

changedInput schema / properties / tags / description

Previous value: -"Tags for searchability and filtering (e.g. [\"sales\", \"billing\", \"v2\"])."New value: +"Labels shown by list_tags and on each list_templates result (e.g. [\"sales\", \"billing\", \"v2\"]). Duplicates are removed and the list is sorted; the whole list is limited to 100 characters (about 8 tags of 9 characters)."

changedInput schema / properties / template / description

Previous value: -"The template file. Three input forms are accepted: (1) Local file path — absolute or relative, e.g. \"/home/user/report.docx\" or \"./invoice.xlsx\". (2) HTTPS URL — the file is downloaded automatically, e.g. \"https://example.com/file.pptx\". (3) Base64-encoded string — the raw file content encoded as base64. Supported formats: DOCX, XLSX, PPTX, ODT, ODS, ODP, ODG, HTML, XHTML, IDML, XML, Markdown (MD), PDF, and more. Full list: https://carbone.io/documentation/developer/http-api/generate-reports.md"New value: +"The template file. Three input forms are accepted: (1) Local file path — absolute, e.g. \"/Users/me/report.docx\" (or \"C:\\Users\\me\\report.docx\" on Windows), or under the home directory, e.g. \"~/report.docx\". A relative path must start with \"./\" or \"../\" and resolves against the server process's working directory, which is rarely yours: prefer an absolute path. A bare file name such as \"report.docx\" is NOT a path: it would be sent as base64 content. (2) HTTPS URL — the file is downloaded automatically, e.g. \"https://example.com/file.pptx\". (3) Base64-encoded string — the raw file content encoded as base64. Supported input formats: DOCX, XLSX, PPTX, ODT, ODS, ODP, ODG, HTML, XHTML, XML, SVG, IDML, MD, TXT, CSV, RTF, PDF. Carbone reads XML-based and text-based documents (plus PDF): the legacy binary Office formats DOC, XLS and PPT are rejected as input, although they are valid outputs. Re-save such a file as DOCX, XLSX or PPTX first."

changedInput schema / properties / versioning / description

Previous value: -"Enable template versioning (default: true). When true, a stable Template ID is generated and multiple versions can be managed under it. When false, behaves as legacy mode and returns only a templateId (SHA-256 hash)."New value: +"Enable template versioning (default: true). When true, a stable Template ID is generated and multiple versions can be managed under it. When false, behaves as legacy mode and returns only a templateId (SHA-256 hash) and templateExtension."

changedInput schema / required

Previous value: -[
-  "template",
-  "name"
-]New value: +[
+  "template"
+]

changedOutput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

addedOutput schema / properties / createdAt

Added value: +{
+  "description": "UTC Unix timestamp (seconds) of the upload.",
+  "type": "number"
+}

addedOutput schema / properties / deployedAt

Added value: +{
+  "description": "UTC Unix timestamp of deployment; 0 means this version is not explicitly deployed.",
+  "type": "number"
+}

changedOutput schema / properties / name / description

Previous value: -"Template display name."New value: +"Template display name, when one was given."

addedOutput schema / properties / templateExtension

Added value: +{
+  "description": "Detected file extension, e.g. \"docx\" (legacy/non-versioned mode).",
+  "type": "string"
+}

removedOutput schema / required
```
Removed value: -[
-  "name"
-]
```

Changed1 schema field changedv1.6.0Aug 22, 2026

changedInput schema / properties / template / description

Previous value: -"The template file. Accepts a local file path (e.g. /home/user/invoice.docx), a URL (https://example.com/template.docx), or a base64-encoded string. Supported formats: DOCX, XLSX, PPTX, ODT, ODS, ODP, ODG, HTML, XHTML, IDML, XML, Markdown (MD), PDF, and more. Full list: https://carbone.io/documentation/developer/http-api/generate-reports.md"New value: +"The template file. Three input forms are accepted: (1) Local file path — absolute or relative, e.g. \"/home/user/report.docx\" or \"./invoice.xlsx\". (2) HTTPS URL — the file is downloaded automatically, e.g. \"https://example.com/file.pptx\". (3) Base64-encoded string — the raw file content encoded as base64. Supported formats: DOCX, XLSX, PPTX, ODT, ODS, ODP, ODG, HTML, XHTML, IDML, XML, Markdown (MD), PDF, and more. Full list: https://carbone.io/documentation/developer/http-api/generate-reports.md"

Changed2 schema fields changedv1.2.2Jun 25, 2026

changedInput schema / properties / template / description

Previous value: -"The template file. Accepts a local file path (e.g. /home/user/invoice.docx), a URL (https://example.com/template.docx), or a base64-encoded string. Supported formats: DOCX, XLSX, PPTX, ODT, ODS, ODP, ODG, HTML, XHTML, IDML, XML, Markdown (MD), PDF, and more. Full list: https://carbone.io/documentation/developer/http-api/generate-reports.html#output-file-type"New value: +"The template file. Accepts a local file path (e.g. /home/user/invoice.docx), a URL (https://example.com/template.docx), or a base64-encoded string. Supported formats: DOCX, XLSX, PPTX, ODT, ODS, ODP, ODG, HTML, XHTML, IDML, XML, Markdown (MD), PDF, and more. Full list: https://carbone.io/documentation/developer/http-api/generate-reports.md"

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": false,
+  "properties": {
+    "id": {
+      "description": "Stable Template ID (when versioning is enabled).",
+      "type": "string"
+    },
+    "name": {
+      "description": "Template display name.",
+      "type": "string"
+    },
+    "size": {
+      "description": "Template size in bytes.",
+      "type": "number"
+    },
+    "templateId": {
+      "description": "Template ID returned in legacy/non-versioned mode.",
+      "type": "string"
+    },
+    "type": {
+      "description": "Detected template file type.",
+      "type": "string"
+    },
+    "versionId": {
+      "description": "Version ID (SHA-256) of this uploaded version.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "name"
+  ],
+  "type": "object"
+}

First observedv1.1.2May 8, 2026

TDQS

A4.6/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already establish that this is a non-read-only, open-world, non-idempotent, non-destructive operation. The description adds substantial behavioral context beyond those annotations: versioning semantics, the deployedAt=0 behavior, expiry/purge/404 consequences, and rejection of legacy binary Office formats.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core action and follow-up usage, then proceeds to versioning and format details. It is somewhat long and repeats accepted format information that also appears in the schema, but the size is reasonable for a complex 10-parameter upload tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the rich input schema, output schema, and annotations, the description covers what an agent needs: purpose, follow-up render action, versioning behavior, accepted formats, and expiry behavior. No critical behavior appears missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description adds meaningful cross-parameter semantics not fully captured by individual schema fields, especially how multiple versions relate to a stable Template ID and how rendering selects the most recent deployedAt version.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: uploading and storing a reusable Carbone template. It also explains the primary follow-up action via render_document using the returned Template ID, which clearly distinguishes this tool from render_document itself.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives clear usage context by saying the returned Template ID should be passed to render_document, and it mentions delete_template for immediate removal. It does not explicitly compare this tool against update_template_metadata or state when not to use it, so it falls short of a 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Upload Template

Instructions

Input Schema

Output Schema

Schema Changelog

TDQS

Other Tools