# Carbone — how to use (mcp.ai)

Connect your Carbone account and use 11 tools for documents straight from your AI agent. Connect with your own API key. Carbone is a fast and simple report generator that converts JSON data into various document formats such as PDF, DOCX, XLSX, ODT, and more, using templates.

## Option A — via MCP (recommended)
Remote MCP endpoint (HTTP, streamable): `https://api.mcp.ai/p_carbone?ms=1787295840000`
Add it as a custom/remote MCP connector in your client (Claude, Cursor, VS Code…), then authenticate when prompted. Once connected, ask the agent to use the server's tools (e.g. `carbone_delete_template`).

## Option B — via direct REST API
Base URL: `https://api.mcp.ai/api/carbone`
Auth: `Authorization: Bearer sk_live_…` — create a workspace API key at https://mcp.ai/settings/api-keys
Discover endpoints: `GET https://api.mcp.ai/api/carbone/_endpoints`

### Endpoints
- `POST https://api.mcp.ai/api/carbone/delete/template` — Permanently delete a template from the Carbone server by its 64-character hexadecimal template ID. This action is irreversible. Ensure you have the correct template ID before deleting.
  - body: { templateId: string }
- `POST https://api.mcp.ai/api/carbone/download/template` — Tool to download a template from Carbone by template ID. Use when you need to retrieve the original template file.
  - body: { template_id: string }
- `POST https://api.mcp.ai/api/carbone/generate/report` — Tool to generate a Carbone report from a template and JSON data. Use when you need to render documents in various formats.
  - body: { data: object|object[], enum?: object, lang?: string, timezone?: string, convertTo?: string|object, complement?: object, reportName?: string, templateId: string, batchOutput?: string, hardRefresh?: boolean, variableStr?: string, batchSplitBy?: string, translations?: object, currencyRates?: object, currencySource?: string, currencyTarget?: string, carbone-webhook-url?: string, carbone-webhook-headers?: object }
- `POST https://api.mcp.ai/api/carbone/get/status` — Tool to retrieve the current status and health of the Carbone server. Use before generating reports to ensure the service is operational.
- `POST https://api.mcp.ai/api/carbone/list/template/categories` — Tool to retrieve a list of all categories used in templates. Categories function like folders for organizing templates. Use when you need to see available template groupings.
  - body: { carbone_version?: integer }
- `POST https://api.mcp.ai/api/carbone/list/template/tags` — Tool to list all tags currently used in templates. Use when you need to discover available tags for categorizing or filtering templates by document type or version.
  - body: { carbone_version?: integer }
- `POST https://api.mcp.ai/api/carbone/list/templates` — Tool to retrieve a list of templates from Carbone storage with filtering, search, and cursor-based pagination. Use when you need to find templates, search by name or ID, or iterate through all deploye
  - body: { id?: string, limit?: integer, cursor?: string, origin?: integer, search?: string, category?: string, versionId?: string, carbone_version?: integer, includeVersions?: boolean }
- `POST https://api.mcp.ai/api/carbone/render/template/direct` — Tool to generate a document by uploading a base64-encoded template and data in a single API call. Use when you need to render documents without uploading templates separately.
  - body: { data: object|object[], enum?: object, lang?: string, download?: boolean, template: string, timezone?: string, convertTo?: string|object, complement?: object, reportName?: string, batchOutput?: string, hardRefresh?: boolean, variableStr?: string, batchSplitBy?: string, translations?: object, currencyRates?: object, currencySource?: string, currencyTarget?: string, carbone-version?: string }
- `POST https://api.mcp.ai/api/carbone/set/api/version` — Tool to set the Carbone API version to be used for subsequent requests. Use before rendering or managing templates to ensure correct version is applied.
  - body: { version: integer }
- `POST https://api.mcp.ai/api/carbone/update/template` — Tool to update metadata and attributes of an existing Carbone template. Use when you need to modify template name, comment, tags, category, or control version deployment and lifecycle.
  - body: { name?: string, tags?: string[], comment?: string, category?: string, expireAt?: integer, deployedAt?: integer, templateId: string, carbone_version?: integer }
- `POST https://api.mcp.ai/api/carbone/upload/template` — Upload a template file to the Carbone server to obtain a template ID for document generation. Supported template formats: DOCX, XLSX, PPTX, ODT, ODS, ODP, ODG, XHTML, IDML, HTML, or XML. Templates can
  - body: { template: object|string }

## Example prompts
- "What can I do in Carbone?"
- "Show me a summary of my Carbone account"

## More
- Page: https://mcp.ai/carbone
- Agent spec (llms.txt): https://mcp.ai/carbone/llms.txt
- Postman collection: https://mcp.ai/carbone/postman.json