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

Tools
11
What they doRead · write · destructive
0 · 11 · 00 read11 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. Documents : "pdf", "docx", "xlsx", "pptx", "odt", "ods", "odp", "odg", "rtf", "epub", plus the legacy "doc", "xls", "ppt" (output only — Carbone writes them but cannot read them back). 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" } }.
    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, Markdown (MD), TXT, CSV, RTF, PDF, PNG and JPG. Carbone reads XML-based and text-based documents only, so the legacy BINARY Office formats DOC, XLS and PPT are REJECTED as input — Carbone can produce them as output but cannot read them. Re-save such a file as DOCX/XLSX/PPTX first. Full conversion matrix: https://carbone.io/documentation/developer/http-api/generate-reports.md
    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 saved to a temp file in stdio mode (path returned), or returned as an attachment in HTTP mode. Ignored when outputPath or returnLink is set.
    converterstring
    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. "I" — Carbone ICE (Instant Converter Engine, Carbone 5.14.0+): DOCX → PDF ONLY, no third-party converter — up to 60x faster than LibreOffice on a 1000-page DOCX (3x on a one-page document). Any other input or output format is REJECTED — use another converter for those. PDF options: only Watermarks are applied. EncryptFile, DocumentOpenPassword, RestrictPermissions and the other security options are SILENTLY IGNORED — the PDF comes back readable by anyone, with no error — so NEVER pick "I" when the request needs a password or restricted permissions; use "L" for those. Also unsupported: WEBP and EMF/WMF images, table of contents, SmartArt, complex charts, footnotes/endnotes, comments, tracked changes, form fields, equations, bookmarks and links; a missing font falls back to Noto Sans. If omitted, LibreOffice is used by default.one of LCOI
    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 512 characters.
    hardRefreshboolean
    Forces Carbone to run the converter even when the output format already matches the input format. Only useful for PDF: converting PDF → PDF to APPLY formatOptions (watermark, password, PDF/A, page range). Without it Carbone may pass the file straight through and none of those options take effect. Leave unset for any format-changing conversion (DOCX → PDF, XLSX → CSV, …), where the converter runs anyway.
    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
    Filename (WITHOUT extension) for the converted document, returned in the Content-Disposition header. Carbone appends the extension matching convertTo, so do not include one — "report.pdf" yields "report.pdf.pdf". Examples: "contract", "2026-invoice". Unlike render_document, Carbone tags are NOT resolved here (conversion does not run templating), so pass a literal name rather than a pattern like "{d.id}" — a pattern would come back verbatim. Ignored when returnLink is set, which returns a download URL rather than 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_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.

  • carboneiomcp_list_templatesList stored Carbone templates with filtering, search, and pagination.Write

    List Templates

    List stored Carbone templates with filtering, search, and pagination. Filter by Template ID, Version ID, category, or upload origin. Use includeVersions to see the full version history of each template. Supports cursor-based pagination for large collections. Note: filtering by tags is not supported by the Carbone API — use list_tags to discover tags, then filter results manually. Note: templates uploaded with versioning disabled appear with id = null and are identified only by their versionId — pass that versionId where a Template ID is expected (e.g. delete_template, download_template).

    Inputs

    categorystring
    Filter by category (e.g. "invoices", "legal").
    cursorstring
    Pagination cursor from the previous response nextCursor field. Use to fetch the next page.
    idstring
    Filter by Template ID (64-bit format). Cannot be a Version ID.
    includeVersionsboolean
    If true, returns all versions for each template. Default: false (only deployed version).
    limitinteger
    Maximum number of results to return, between 1 and 100. Default: 100. Use cursor to page beyond that.
    origininteger
    Filter by upload origin. 0 = API, 1 = Carbone Studio, 2 = Salesforce, 3 = Odoo, 4 = HubSpot. Templates created through this MCP are origin 0.
    searchstring
    Fuzzy search in template names, or exact match on Template ID / Version ID.
    versionIdstring
    Filter by Version ID (SHA-256 format).
All 33 in Files & Documents