Skip to content
Scalekit Docs
Talk to an Engineer Dashboard

Connect AI agents to the Carbone.io MCP server

Vendor MCP
Open markdown

The Carbone.io MCP connector routes your AI agent's tool calls to Carbone.io's own MCP server through Scalekit. Each user connects their own Carbone.io access token once, and Scalekit sends it with every call, so your agent never handles credentials. It comes with 12 tools.

Tools
12
What they doRead · write · destructive
0 · 12 · 00 read12 write0 destructive
Users sign in with

Setup

  1. Install the SDK

    Terminal window
    npm install @scalekit-sdk/node dotenv

  2. 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. Create the Carbone.io MCP connection

    In AgentKit > Connections, create a Carbone.io MCP connection. The name you give it is the connection_name your code passes. See Configure connections.

    Console steps with screenshots

    Register your Carbone API key with Scalekit so it can authenticate and proxy document generation requests on behalf of your users. Carbone.io MCP uses Bearer Token authentication.

    1. Get a Carbone API key

      • Go to account.carbone.io and sign in.
      • Click My subscription in the left sidebar.
      • On the right side, find the API Access Keys panel.
      • For production use, click the lock icon next to Production API key to reveal and copy it.
      • For testing, click the eye icon next to Test API key to reveal it.

      Carbone Account dashboard showing the API Access Keys panel with Production and Test API keys

    2. Create a connection in Scalekit

      • In the Scalekit dashboard, go to AgentKit → Connections → Create Connection.
      • Search for Carbone.io MCP and click Create.
      • Note the Connection name — use this as connection_name in your code (e.g., carboneiomcp).

    3. Add a connected account

      Connected accounts link a specific user identifier in your system to a Carbone API key. Add one in the dashboard to test. In production, each user adds their own through the authorization link: they enter their credentials on the page it opens.

      In the dashboard, to test

      • Open the connection and click the Connected Accounts tab → Add account.
      • Fill in Your User’s ID and API Key, then click Save.

      From your backend, if your app already has the credentials

      For example, when users enter them on a settings page in your app:

      import { ConnectorStatus } from '@scalekit-sdk/node'
      

      const authorizationDetails = {
        details: {
          case: 'staticAuth',
          value: { details: { token: 'your-carbone-api-key' } },
        },
      }
      

      let { connectedAccount } = await scalekit.actions.upsertConnectedAccount({
        connectionName: 'carboneiomcp',
        identifier: 'user_123',
        authorizationDetails,
      })
      

      // Make sure the account is ACTIVE before the first tool call.
      if (connectedAccount?.status !== ConnectorStatus.ACTIVE) {
        ;({ connectedAccount } = await scalekit.actions.upsertConnectedAccount({
          connectionName: 'carboneiomcp',
          identifier: 'user_123',
          authorizationDetails,
        }))
      }

  4. Authorize a user and make your first call

    quickstart.mts
    import { ScalekitClient } from '@scalekit-sdk/node'
    import 'dotenv/config'
    import { createInterface } from 'node:readline/promises'
    

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

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

    // Generate an authorization link for the user
    const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })
    console.log('Authorize Carbone.io MCP:', link)
    const rl = createInterface({ input: process.stdin, output: process.stdout })
    await rl.question('Press Enter after authorizing...')
    rl.close()
    

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

    Each user opens the link once and enters their Carbone.io MCP server credentials there. If your app already has a user's credentials, add the account from your backend instead, as the console steps above show. See Authorize a user for the full flow and statuses.

Tools

Pass the exact name to execute_tool
Try in PlaygroundRequest a tool
  • carboneiomcp_convert_documentConvert any document to another format without storing a template.Write

    Convert Document

    Convert any document to another format without storing a template. Supports 100+ input/output format combinations: Office documents, PDFs, images, web pages, spreadsheets, and more. The source file can be a local path, a URL, or a base64 string. Carbone tags are PRESERVED, not resolved: converting a template keeps every {d.field} intact, so this is also how you proof a template in another format (DOCX template → PDF, or DOCX → ODT while it stays a template). Use render_document instead when you need data injection ({d.field} tags resolved), translations, or batch generation. Common conversions: DOCX → PDF (file: "report.docx", convertTo: "pdf"; add converter: "I" for the fastest DOCX→PDF path), XLSX → PDF (file: "data.xlsx", convertTo: "pdf"), PPTX → PDF (file: "slides.pptx", convertTo: "pdf", converter: "O" for best fidelity), HTML → PDF (file: "page.html", convertTo: "pdf", converter: "C" for full CSS/JS rendering), DOCX → HTML (file: "doc.docx", convertTo: "html"), XLSX → CSV (file: "sheet.xlsx", convertTo: "csv"), PDF → PNG (file: "doc.pdf", convertTo: "png"), PPTX → PNG (first slide as image), MD → PDF (file: "readme.md", convertTo: "pdf").

    Inputs

    convertTostringrequired
    Target output format. Valid outputs depend on the input format (e.g. HTML converts to pdf, docx or png, but not xlsx); see the conversion matrix: https://carbone.io/documentation/developer/http-api/generate-reports.html#output-file-type. "doc", "xls" and "ppt" are output formats; as input, use DOCX, XLSX or PPTX. Simple usage: "pdf". With options: { "formatName": "pdf", "formatOptions": { ... } }.
    filestringrequired
    The document to convert. Two input forms are accepted: (1) HTTPS URL — the file is downloaded automatically, e.g. "https://example.com/file.pptx". (2) Base64-encoded string — the raw file content encoded as base64. Local file paths are NOT accepted — this server is reached over HTTP, so a path would resolve on the server's disk rather than yours and is rejected. Upload the bytes as base64, or host the file at a URL. 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. Full conversion matrix: https://carbone.io/documentation/developer/http-api/generate-reports.html#output-file-type
    asAttachmentboolean
    If true, return the document as a downloadable file attachment (a base64 EmbeddedResource), for any format. Default delivery: text and png/jpg/gif/webp are returned inline; other binary outputs (PDF, Office, …) are returned as an attachment. Ignored when outputPath or returnLink is set.
    converterstring
    Converter engine, used whenever the format changes (not only for PDF). If omitted, "L" is used. "L" LibreOffice: DOCX, XLSX, PPTX, ODT, ODS, ODP, ODG, MD, PDF; the only converter supporting all PDF options. "I" Carbone ICE: DOCX and ODT to PDF; Carbone's own engine, 3x to 300x faster, recommended over "O" for DOCX from v5.15.0. It converts all content except WEBP and EMF/WMF images, SmartArt and complex charts (bar, line, area, pie and doughnut charts are drawn), comments, tracked changes, form fields and equations: keep the default "L" for documents with those. A missing font is replaced by Noto Sans (https://carbone.io/documentation/developer/http-api/generate-reports.html#converters-carbone-ice-limitations). "O" OnlyOffice: DOCX, XLSX, PPTX to PDF. "C" Chromium: HTML to PDF, JPG, PNG, WEBP with full CSS/JS; 100 MB max. PDF options: "L" supports all of them; "O", "C" and "I" apply Security (passwords, permissions) and Watermarks. Docs: https://carbone.io/documentation/developer/http-api/generate-reports.html#convertersone of LOCI
    egressAuthorizationstring
    Value for the Authorization header Carbone adds to its OUTBOUND (egress) requests during conversion — e.g. when a Chromium HTML→PDF conversion fetches a protected external image or stylesheet. For example "Bearer abc123" makes Carbone send `authorization: Bearer abc123` to those hosts. Only the authorization header can be customised; max 511 characters.
    hardRefreshboolean
    If true, Carbone runs the converter even when the output format equals the input format, and recomputes pagination and the table of contents at the end of the conversion. Needed for PDF → PDF: without it Carbone returns the PDF unchanged and formatOptions (password, permissions, watermarks, PDF/A, …) are NOT applied. This server sets it automatically when the input is a PDF, convertTo is "pdf" and formatOptions are given; pass false to opt out. Example (PDF → PDF/A-4): { "hardRefresh": true, "convertTo": { "formatName": "pdf", "formatOptions": { "SelectPdfVersion": 4 } } }.
    outputPathstring
    NOT AVAILABLE on this server, which is reached over HTTP: the converted document would be written to the server's disk instead of yours, so passing outputPath is rejected. Use asAttachment to receive the bytes, or returnLink for a one-time download URL.
    reportNamestring
    Name of the delivered file, WITHOUT extension (e.g. "contract", "2026-invoice"). The document is delivered as "<reportName>.<ext>", with the extension of convertTo, used as the attachment name. This server names the file itself: a conversion has no templating pass, which is where Carbone resolves reportName. Used literally: Carbone tags such as {d.id} are not resolved here. Ignored with returnLink (a download URL, not a named file).
    returnLinkboolean
    If true, generate the document and return a public download URL instead of the file contents. The link is SHORT-LIVED and ONE-TIME — Carbone deletes the file after the first download — so it is meant for the end user to download once (do not fetch it programmatically). Works in stdio and HTTP. Mutually exclusive with outputPath and asAttachment.
  • carboneiomcp_delete_templateDelete a stored Carbone template.Write

    Delete Template

    Delete a stored Carbone template. This is a soft delete: the template is marked for garbage collection and removed after a delay (default 24 hours). You can delete by Template ID (removes all versions) or by Version ID (removes only that specific version). For immediate or scheduled deletion, use update_template_metadata with expireAt = 42000000000 (NOW) or a future Unix timestamp.

    Inputs

    templateIdstringrequired
    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_templateDownload the original source file of a stored Carbone template (e.g.Write

    Download Template

    Download the original source file of a stored Carbone template (e.g. the DOCX, XLSX, PPTX, or HTML file that was uploaded). Use this to inspect, edit, or back up a template. Pass a Template ID to download the currently deployed version, or a Version ID to download a specific version. Set sample:true to fetch the JSON sample dataset stored with the template instead of the template file itself.

    Inputs

    templateIdstringrequired
    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.
    asAttachmentboolean
    If true, return the template as a downloadable file attachment (base64 resource) instead of inline text/image. Useful in HTTP mode where outputPath is unavailable. Default: false. Ignored when outputPath is set.
    outputPathstring
    NOT AVAILABLE on this server, which is reached over HTTP: the template file would be written to the server's disk instead of yours, so passing outputPath is rejected. Use asAttachment to receive the bytes, or returnLink for a one-time download URL.
    sampleboolean
    If true, download the JSON SAMPLE DATASET saved with the template (the "sample" array passed to upload_template) instead of the template file. Returns JSON of the form [{ "data": {...}, "complement": {...}, "translations": {...}, "enum": {...} }]. Use it to recover the example data a template expects — handy before calling render_document against an unfamiliar template. Errors if the template was uploaded without a sample.
  • carboneiomcp_get_api_statusCheck Carbone API health and version.Write

    Get Api Status

    Check Carbone API health and version. Returns the current API version and a status message. Useful for verifying connectivity and confirming which Carbone version is active.

    Inputs

    This tool takes no inputs.

  • carboneiomcp_get_capabilitiesReturns a summary of all Carbone capabilities: supported formats, features, tool usage examples, and links to full documentation.Write

    Get Capabilities

    Returns a summary of all Carbone capabilities: supported formats, features, tool usage examples, and links to full documentation. Call this first if you are unsure what Carbone can do.

    Inputs

    This tool takes no inputs.

  • carboneiomcp_inspect_templateList the Carbone tags a template uses and return a sample JSON dataset matching its structure.Write

    Inspect Template

    List the Carbone tags a template uses and return a sample JSON dataset matching its structure. Call it before render_document when you do not know which data a template expects. Pass exactly one of templateId (a stored template: Template ID or Version ID) or template: an HTTPS URL or a base64-encoded string (local file paths are not accepted over HTTP). It runs one render on the Carbone account and discards the document. {t()} translation tags are not listed.

    Inputs

    templatestring
    Inline template to inspect, without storing it. Two input forms are accepted: (1) HTTPS URL — the file is downloaded automatically, e.g. "https://example.com/file.pptx". (2) Base64-encoded string — the raw file content encoded as base64. Local file paths are NOT accepted — this server is reached over HTTP, so a path would resolve on the server's disk rather than yours and is rejected. Upload the bytes as base64, or host the file at a URL. 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. Mutually exclusive with templateId — provide exactly one, never both.
    templateIdstring
    The ID of a stored template to inspect. Two ID formats are accepted: (1) Template ID (64-bit) — the deployed version is inspected. (2) Version ID (SHA-256) — that exact version is inspected. Both are returned by upload_template and list_templates. Mutually exclusive with template — provide exactly one, never both.
  • carboneiomcp_list_categoriesList all template categories currently in use in your Carbone account.Write

    List Categories

    List all template categories currently in use in your Carbone account. Categories act like folders for organising templates (e.g. "invoices", "legal", "hr"). Use the returned names as the category filter in list_templates or upload_template.

    Inputs

    This tool takes no inputs.

  • carboneiomcp_list_tagsList all tags currently used across templates in your Carbone account.Write

    List Tags

    List all tags currently used across templates in your Carbone account. Tags are free-form labels attached to templates (e.g. "sales", "billing", "v2"). Note: the Carbone API does not support filtering list_templates by tag — use this tool to discover available tags, then call list_templates and filter the results manually.

    Inputs

    This tool takes no inputs.

All 45 in Files & Documents