Skip to content
Scalekit Docs
Talk to an Engineer Dashboard

Carbone.io MCP connector

Bearer Token Files & DocumentsAIDeveloper Tools

Connect to Carbone.io MCP. Upload templates, render documents by merging templates with JSON data, convert between 100+ formats, and manage template...

Carbone.io MCP connector

  1. Install the SDK

    Section titled “Install the SDK”
    Terminal window
    npm install @scalekit-sdk/node

    Full SDK reference: Node.js | Python

  2. Set your credentials

    Section titled “Set your credentials”

    Add your Scalekit credentials to your .env file. Find values in app.scalekit.com > Developers > API Credentials.

    .env
    SCALEKIT_ENVIRONMENT_URL=<your-environment-url>
    SCALEKIT_CLIENT_ID=<your-client-id>
    SCALEKIT_CLIENT_SECRET=<your-client-secret>

  3. Make your first call

    Section titled “Make your first call”
    quickstart.ts
    import { ScalekitClient } from '@scalekit-sdk/node'
    import 'dotenv/config'
    

    const scalekit = new ScalekitClient(
      process.env.SCALEKIT_ENV_URL,
      process.env.SCALEKIT_CLIENT_ID,
      process.env.SCALEKIT_CLIENT_SECRET,
    )
    const actions = scalekit.actions
    

    const connector = 'carboneiomcp'
    const identifier = 'user_123'
    

    // Make your first call
    const result = await actions.executeTool({
      connector,
      identifier,
      toolName: 'carboneiomcp_get_api_status',
      toolInput: {},
    })
    console.log(result)

What you can do

Section titled “What you can do”

Connect this agent connector to let your agent:

  • Template upload, download — Upload and store a reusable Carbone template for use with render_document
  • Update template metadata — Update a stored template’s name, comment, category, tags, or deployment timestamps
  • Document render, convert — Generate a document by merging a Carbone template with JSON data, optionally converting the output format
  • List templates, tags, categories — List stored Carbone templates with optional filtering by category, tag, ID, or search query
  • Get capabilities, api status — Return a summary of all Carbone capabilities including supported formats, features, and usage examples
  • Delete template — Soft-delete a stored Carbone template by its template ID

Tool list

Section titled “Tool list”

Use the exact tool names from the Tool list below when you call execute_tool. If you’re not sure which name to use, list the tools available for the current user first.

carboneiomcp_convert_document # Convert a document to another format without storing a template. Supports 100+ input/output format combinations. 3 params

Convert a document to another format without storing a template. Supports 100+ input/output format combinations.

Name Type Required Description
convertTo string required Target output format. Documents : "pdf", "docx", "xlsx", "pptx", "odt", "ods", "odp", "odg", "rtf", "epub". Web/text : "html", "xhtml", "txt", "csv", "md", "xml", "idml". Images : "png", "jpg", "jpeg", "webp", "svg", "tiff", "bmp", "gif". Archive : "zip" (batch output). Simple usage: "pdf". Advanced usage: { "formatName": "pdf", "formatOptions": { "EncryptFile": true, "DocumentOpenPassword": "secret" } }.
file string required The document to convert. 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 input formats include: DOCX, XLSX, PPTX, ODT, ODS, ODP, ODG, HTML, XHTML, XML, IDML, Markdown (MD), PDF, TXT, CSV, PNG, JPG, SVG, and more. Full conversion matrix: https://carbone.io/documentation/developer/http-api/generate-reports.html#output-file-type
converter string optional Converter engine. Only relevant when convertTo is "pdf" (or an image format rasterised from a document). "L" — LibreOffice (default): best all-round engine for DOCX, XLSX, PPTX, ODT, ODS, ODP. "O" — OnlyOffice: highest fidelity rendering for Microsoft Office formats (DOCX, XLSX, PPTX). "C" — Chromium: best for HTML, CSS, JavaScript — full browser rendering. If omitted, LibreOffice is used by default.
carboneiomcp_delete_template # Soft-delete a stored Carbone template by its template ID. 1 param

Soft-delete a stored Carbone template by its template ID.

Name Type Required Description
templateId string required Template ID (64-bit) or Version ID (SHA-256) to delete. Template ID — deletes the template record and all its versions. Version ID — deletes only that specific version, leaving other versions intact. Both formats are returned by upload_template and list_templates.
carboneiomcp_download_template # Download the original source file (DOCX, XLSX, PPTX, etc.) of a stored Carbone template. 1 param

Download the original source file (DOCX, XLSX, PPTX, etc.) of a stored Carbone template.

Name Type Required Description
templateId string required Template ID (64-bit) or Version ID (SHA-256) to download. Template ID — downloads the currently deployed version of the template. Version ID — downloads that exact version regardless of deployment status. Both formats are returned by upload_template and list_templates.
carboneiomcp_get_api_status # Check the Carbone API health and return the current API version and status. 0 params

Check the Carbone API health and return the current API version and status.

carboneiomcp_get_capabilities # Return a summary of all Carbone capabilities including supported formats, features, and usage examples. 0 params

Return a summary of all Carbone capabilities including supported formats, features, and usage examples.

carboneiomcp_list_categories # List all template categories currently in use in your Carbone account. 0 params

List all template categories currently in use in your Carbone account.

carboneiomcp_list_tags # List all tags currently used across templates in your Carbone account. 0 params

List all tags currently used across templates in your Carbone account.

carboneiomcp_list_templates # List stored Carbone templates with optional filtering by category, tag, ID, or search query. 8 params

List stored Carbone templates with optional filtering by category, tag, ID, or search query.

Name Type Required Description
category string optional Filter by category (e.g. "invoices", "legal").
cursor string optional Pagination cursor from the previous response nextCursor field. Use to fetch the next page.
id string optional Filter by Template ID (64-bit format). Cannot be a Version ID.
includeVersions boolean optional If true, returns all versions for each template. Default: false (only deployed version).
limit integer optional Maximum number of results to return (default: 100).
origin integer optional Filter by upload origin. 0 = uploaded via API, 1 = uploaded via Carbone Studio.
search string optional Fuzzy search in template names, or exact match on Template ID / Version ID.
versionId string optional Filter by Version ID (SHA-256 format).
carboneiomcp_render_document # Generate a document by merging a Carbone template with JSON data, optionally converting the output format. 21 params

Generate a document by merging a Carbone template with JSON data, optionally converting the output format.

Name Type Required Description
data object required JSON data merged into the template. Access fields with {d.fieldName} tags. Nested objects: {d.customer.name}. Array loops: {d.items[i].description} … {d.items[i+1]}. Conditionals: {d.status == "active" ? "Yes" : "No"}. For pure document conversion without data injection, pass {}.
batchOutput string optional Container format for the batch result. Use "zip" to receive all generated documents as a single ZIP archive. Must be used together with batchSplitBy.
batchReportName string optional Filename pattern for each individual document inside the batch ZIP. Supports Carbone tags. Tags are resolved against the item's data (relative path) or the full dataset (absolute path). Examples: "invoice-{d.id}.pdf", "{d.client.name}-{d.date}.docx". Must be used together with batchSplitBy.
batchSplitBy string optional JSON path to the array in your data that drives batch generation. One document is generated per element of the array; all documents are bundled together. Use batchOutput: "zip" to receive a single ZIP archive. Use batchReportName to customise each filename inside the ZIP. Example: "d.invoices" — produces one PDF per item in data.invoices. Example: "d.employees" — produces one contract per employee.
complement object optional Extra data object accessible in templates with {c.field} tags (as opposed to {d.field} for main data). Useful for static or shared values that should not be mixed into the main dataset: company info, logo URLs, footer text, configuration constants. Example: { "company": "Acme Corp", "address": "123 Main St", "vatNumber": "FR12345" }
converter string optional Converter engine. Only relevant when convertTo is "pdf" (or an image rasterised from a document). "L" — LibreOffice (default): best all-round engine for DOCX, XLSX, PPTX, ODT, ODS, ODP. "O" — OnlyOffice: highest fidelity for Microsoft Office formats (DOCX, XLSX, PPTX). "C" — Chromium: best for HTML/CSS/JS templates — full browser rendering. If omitted, LibreOffice is used by default.
convertTo string optional Output format. If omitted, the output matches the template format. Documents : "pdf", "docx", "xlsx", "pptx", "odt", "ods", "odp", "odg", "rtf", "epub". Web/text : "html", "xhtml", "txt", "csv", "md", "xml", "idml". Images : "png", "jpg", "jpeg", "webp", "svg", "tiff", "bmp", "gif". Archive : "zip" (use with batchSplitBy for batch output). Simple usage: "pdf". Advanced usage: { "formatName": "pdf", "formatOptions": { ... } } for PDF-specific options.
currencyRates object optional Exchange rate table used by :formatC for currency conversion. Keys are ISO 4217 currency codes; values are rates relative to a common base. The base currency should have rate 1. Example: { "EUR": 1, "USD": 1.08, "GBP": 0.86, "JPY": 160.5 }.
currencySource string optional ISO 4217 currency code of the monetary amounts in the JSON data. Used by the :formatC formatter as the conversion source. Must be set together with currencyTarget and currencyRates. Example: "EUR" if all prices in your data are in euros.
currencyTarget string optional ISO 4217 currency code of the output document. The :formatC formatter converts amounts from currencySource to this currency using currencyRates. Must be set together with currencySource and currencyRates. Example: "USD" to display prices in US dollars. Documentation: https://carbone.io/documentation.html#formatc-precisionorformat-
enum object optional Enumeration map used with the :convEnum(TYPE) formatter to translate code values into human-readable labels. Define one key per enum type; each value is an object mapping code → label. Example: { "STATUS": { "1": "Active", "2": "Inactive", "3": "Pending" }, "ROLE": { "A": "Admin", "U": "User" } }. Template usage: {d.status:convEnum(STATUS)}, {d.role:convEnum(ROLE)}. Documentation: https://carbone.io/documentation.html#convenum-type-
hardRefresh boolean optional If true, Carbone recomputes pagination and refreshes the table of contents after rendering. Requires convertTo to be defined. Use this for DOCX/ODT templates that contain a TOC field or cross-references that need updating after data injection.
lang string optional Locale of the generated document. Affects three things: (1) {t(key)} translation tags — selects the matching translation from the translations map. (2) :formatN number formatter — applies locale-specific thousand/decimal separators. (3) :formatC currency formatter — applies locale-specific currency symbols and formatting. Format: BCP-47 lowercase, e.g. "fr-fr", "en-us", "de-de", "es-es", "pt-br", "zh-cn", "ja-jp". Full list: https://github.com/carboneio/carbone/blob/master/formatters/_locale.js
reportName string optional Filename for the generated document, returned in the Content-Disposition header. Supports Carbone tags resolved against the data at render time. Examples: "invoice.pdf" (static), "{d.type}-{d.id}.pdf" (dynamic), "{d.client}-{d.date:formatD(YYYY-MM)}.docx".
template string optional Inline template for one-shot render without storing a template first. Accepts a local file path (e.g. /home/user/invoice.docx), a URL (https://example.com/template.docx), or a base64-encoded string. The template is uploaded and rendered in a single API request — no Template ID is returned. Use this for ephemeral renders; use upload_template + templateId when you need to reuse the template. Supported formats: DOCX, XLSX, PPTX, ODT, ODS, ODP, ODG, HTML, XHTML, IDML, XML, Markdown (MD), PDF, and more. Mutually exclusive with templateId — provide exactly one, never both.
templateId string optional The ID of a previously uploaded template to render. Two ID formats are accepted: (1) Template ID (64-bit) — stable identifier shared across versions; Carbone automatically uses the deployed version. (2) Version ID (SHA-256) — pins rendering to a specific version regardless of deployment status. Both are returned by upload_template. Mutually exclusive with template — provide exactly one, never both.
timezone string optional IANA timezone used to convert dates in the rendered document. Default: "Europe/Paris". Applied when templates use the :formatD formatter, e.g. {d.date:formatD(YYYY-MM-DD HH:mm)}. Common values: "UTC", "America/New_York", "America/Los_Angeles", "Europe/London", "Europe/Paris", "Europe/Berlin", "Asia/Tokyo", "Asia/Shanghai", "Australia/Sydney". Full list (TZ identifier column): https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
translations object optional Translation map for multilingual documents. Requires "lang" to be set to select the active locale. Top-level keys are BCP-47 locale codes; values are key → translated-string maps. Template usage: {t(greeting)} is replaced by the matching string for the active locale. Example: { "fr-fr": { "greeting": "Bonjour", "total": "Total" }, "en-us": { "greeting": "Hello", "total": "Total" } }. Documentation: https://carbone.io/documentation.html#translations
variableStr string optional Carbone alias expressions evaluated once before rendering, available everywhere in the template. Used to pre-compute reusable values or shorten repetitive paths. Syntax: "{#aliasName = expression}". Example: "{#fullName = d.firstName + \" \" + d.lastName}{#total = d.price * d.qty}". Aliases are then used in the template as {#fullName}, {#total}. Documentation: https://carbone.io/documentation.html#alias
webhookHeaders object optional Custom headers Carbone will include when POSTing to your webhookUrl. Pass plain header names as keys — the prefix "carbone-webhook-header-" is added automatically before sending to Carbone, and Carbone forwards the original header names to your webhook endpoint. Example: { "authorization": "my-secret", "custom-id": "12345", "custom-name": "Jane Doe" } — Carbone will call your URL with headers: authorization: my-secret, custom-id: 12345, custom-name: Jane Doe. Requires webhookUrl to be set.
webhookUrl string optional Webhook URL to enable asynchronous rendering. When provided, Carbone returns immediately and POSTs { "success": true, "data": { "renderId": "..." } } to this URL when the document is ready. The default render timeout is extended to 5 minutes on Carbone Cloud (vs 60 s for synchronous requests). Download the document with GET /render/:renderId once the webhook is received. Required when using batchSplitBy (batch generation is always asynchronous). Example: "https://your-server.com/carbone-webhook".
carboneiomcp_update_template_metadata # Update a stored template's name, comment, category, tags, or deployment timestamps. 7 params

Update a stored template's name, comment, category, tags, or deployment timestamps.

Name Type Required Description
templateId string required Template ID (64-bit) or Version ID (SHA-256) to update. Using a Template ID updates the metadata shared by all versions. Using a Version ID updates only that specific version.
category string optional New category.
comment string optional New free-text comment.
deployedAt integer optional Unix timestamp (seconds) to set as the deployment time for this version. Carbone picks the version with the most recent deployedAt when rendering. Use 42000000000 to deploy immediately (special "NOW" value).
expireAt integer optional Unix timestamp (seconds) at which this template will be automatically deleted. Use 42000000000 to delete immediately.
name string optional New display name.
tags array optional New list of tags — replaces existing tags entirely.
carboneiomcp_upload_template # Upload and store a reusable Carbone template for use with render_document. 10 params

Upload and store a reusable Carbone template for use with render_document.

Name Type Required Description
name string required Display name for the template (e.g. "Invoice Template", "NDA Contract").
template string required 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
category string optional Group templates into folders/categories (e.g. "invoices", "legal", "hr").
comment string optional Free-text comment to describe the template version or its purpose.
deployedAt integer optional 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).
expireAt integer optional UTC Unix timestamp (seconds) at which this template will be automatically deleted. Use 42000000000 to delete immediately (special "NOW" sentinel value).
id string optional 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.
sample array optional Sample input data attached to the template for testing in Carbone Studio. Each item must include data, complement, translations, and enum objects.
tags array optional Tags for searchability and filtering (e.g. ["sales", "billing", "v2"]).
versioning boolean optional 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).