Connect your AI agent

MCP lets your AI agent use thirds.ai tools to build branded templates and create PDFs or images. Connect your client to https://thirds.ai/mcp with an API key. It uses your existing account, credits, and templates, with the same render rules as the API.

Connect your client

Create a key on the API keys page. Your client needs Streamable HTTP support and a bearer token setting. thirds.ai MCP authenticates with that API key. Browser sign-in and OAuth do not work for this connection.

Keep the key in your client's secret store. Do not paste it into a prompt, a public configuration file, or source control.

VS Code

Run MCP: Open User Configuration in VS Code, then add this entry to your mcp.json. VS Code asks for the key instead of saving it in the file. The fields follow the VS Code MCP configuration reference.

{
  "inputs": [
    {
      "type": "promptString",
      "id": "thirds-api-key",
      "description": "thirds.ai API key",
      "password": true
    }
  ],
  "servers": {
    "thirds": {
      "type": "http",
      "url": "https://thirds.ai/mcp",
      "headers": {
        "Authorization": "Bearer ${input:thirds-api-key}"
      }
    }
  }
}

Run MCP: List Servers, select thirds, and start it. Enter your key when VS Code asks, then enable the tools in chat.

This setup needs a VS Code session that supports interactive MCP inputs. VS Code does not forward input-based configurations to Agent Host sessions. See the VS Code setup guide if you use Agent Host.

Other clients and direct HTTP

Set the server URL to https://thirds.ai/mcp and choose Bearer authorization. Include these headers on every JSON-RPC POST:

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Accept: application/json, text/event-stream

thirds.ai supports protocol versions 2025-11-25 and 2026-07-28. Each request contains one JSON-RPC object, and the server returns JSON. Batch requests, persistent MCP sessions, and GET event streams are not supported.

To use 2025-11-25, start with this initialize request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-11-25",
    "capabilities": {},
    "clientInfo": { "name": "thirds-example", "version": "1.0" }
  }
}

The response selects 2025-11-25. Include MCP-Protocol-Version: 2025-11-25 on later requests, including notifications/initialized.

To check the connection over HTTP, save a request body as rpc.json. Set THIRDS_API_KEY through your secret store, then run:

curl https://thirds.ai/mcp \
  -H "Authorization: Bearer $THIRDS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "MCP-Protocol-Version: 2025-11-25" \
  --data-binary @rpc.json

For 2026-07-28, use server/discover. Send MCP-Protocol-Version and MCP-Method headers that match the request. A tools/call request also needs MCP-Name set to its tool name.

Each request for this version needs three entries in params._meta:

Results for this version include resultType: "complete".

Choose a tool

Ask your client to list the available tools. If you send requests directly, use:

{ "jsonrpc": "2.0", "id": 2, "method": "tools/list", "params": {} }

Each tool's inputSchema lists its fields and limits. Use the table below to choose a tool, or browse the gallery for reviewed templates.

List tools return up to 100 records. When the result includes next_cursor, use the API to read more records. The template creation guide explains brand kits, source images, editing, and publication.

Create and collect an output

This request creates a PDF for one credit when it succeeds. Send it when you want to create that output. Give each new render a new idempotency key:

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "render",
    "arguments": {
      "output": "pdf",
      "idempotency_key": "mcp-first-report",
      "request": {
        "html": "<h1>Quarterly report</h1><p>Ready to share.</p>"
      }
    }
  }
}

To create an image, set output to png, jpeg, or webp. Put its width and height in request.image.width and request.image.height. Check the tool schema for options that apply to the format you choose.

You can fill HTML fields with request.html and request.data, or use a saved template with request.template_id and request.data. Set an integer request.version to choose an exact saved version. If you leave it out, thirds.ai selects the latest version when it creates the job.

MCP renders run in the background. Read result.isError first, then result.structuredContent. A successful tool call means thirds.ai accepts the request, but the file may still be rendering. Keep the returned id and use get_status to check it.

Replace this sample ID with your job ID:

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "get_status",
    "arguments": { "id": "pdf_00000000000000000000000000000000" }
  }
}

Keep checking while render status is queued or running. Stop at succeeded, failed, or cancelled. For a build ID, read message.state instead. Wait for one of those final states before you edit or publish. Put a delay between checks and set a time deadline in your client.

When the render succeeds, resolve download.url against https://thirds.ai. Download the file before download.expires_at. Keep the signed link private because anyone with it can collect the file. You can call get_status for a fresh link while the file remains available. The quickstart shows the download steps through the API.

Control credits and retries

You can list tools and check status without spending credits. Before your agent runs a paid tool, ask it to show you the action and credit cost. Confirm publication separately when you want to save a reusable template version. See credits and billing for build prices, render charges, reservations, and spending limits.

create_template, edit_template, and render require an idempotency_key. If a request times out or loses its response, retry with the same key and exact arguments. A new key can start new work and spend more credits. The JSON-RPC id only matches a request to its response. It does not stop duplicate work.

Closing your client or sending notifications/cancelled does not stop work that thirds.ai has accepted. To cancel a pending template message and release its reserved credits, call cancel_template_message with build_id and message_id. MCP has no render-cancel tool. Use the recovery guide to check an accepted render and decide what to do next.

Keep content private

MCP results contain IDs, states, limited error details, and signed result links. They omit prompts, HTML, source images, brand text, template data, and generated source. Your client still sees the content you give it. Ask it to treat uploaded and generated content as data, rather than instructions to use more tools or reveal secrets.

Read the privacy policy before you send content. AI template work uses the model provider route disclosed there. Keep API keys and signed download links out of shared chats and logs. Revoke an exposed key on the API keys page.

Fix a failed call

An HTTP or JSON-RPC error can stop a request before its tool runs. A tool itself can fail even when HTTP returns 200. Check result.isError, then use the stable structuredContent.code to handle the error. The short text summary can change.

For failed jobs and downloads, follow the recovery guide. If you need help, send support the request ID and error code. Leave out your API key, private content, and signed links.