Guides

MCP server

The MCP (Model Context Protocol) server exposes the API as tools an agent can use: Claude Code, Codex, Cursor, VS Code with GitHub Copilot, Gemini CLI or any other MCP client. Each tool calls a /v1 route, with the same validations, prices, limits and test mode.

Element	Value
URL	`https://api.renderthink.com/mcp`
Transport	“Streamable” HTTP, without sessions.
Authentication	An API key in the `Authorization: Bearer …` header: `rt_test_…` for trials, `rt_live_…` in production.

Setup

The examples read the key from the RENDERTHINK_API_KEY environment variable when the client allows it. Keep the key in the client's user configuration, never in a versioned file. If a key is exposed, revoke it in the console, on the API keys screen.

Claude Code

bash
claude mcp add --transport http renderthink https://api.renderthink.com/mcp \
  --header "Authorization: Bearer $RENDERTHINK_API_KEY"

Codex

In ~/.codex/config.toml, with the key read from the environment variable:

toml
[mcp_servers.renderthink]
url = "https://api.renderthink.com/mcp"
bearer_token_env_var = "RENDERTHINK_API_KEY"

Cursor

In ~/.cursor/mcp.json (or in a project's .cursor/mcp.json), with the key read from the environment variable:

json
{
  "mcpServers": {
    "renderthink": {
      "url": "https://api.renderthink.com/mcp",
      "headers": {
        "Authorization": "Bearer ${env:RENDERTHINK_API_KEY}"
      }
    }
  }
}

VS Code (GitHub Copilot)

In .vscode/mcp.json, with the key asked once then kept by VS Code:

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

Gemini CLI

In ~/.gemini/settings.json, with the key read from the environment variable:

json
{
  "mcpServers": {
    "renderthink": {
      "httpUrl": "https://api.renderthink.com/mcp",
      "headers": {
        "Authorization": "Bearer ${RENDERTHINK_API_KEY}"
      }
    }
  }
}

Other clients

Any client that supports the “streamable” HTTP transport and can send an Authorization header works: enter the URL above and the key as Bearer. Online assistant connectors (ChatGPT, Claude on the web) generally use an OAuth connection, which the RenderThink MCP server does not support.

Tools

Tool	Description	Permission
`create_render`	Creates a render (`POST /v1/renders`).	`renders`
`create_edit`	Creates an edit, by instruction or by mask (`POST /v1/edits`).	`edits`
`create_decoration`	Creates a decoration (`POST /v1/decorations`).	`decorations`
`create_upscale`	Creates an upscaling (`POST /v1/upscales`).	`upscales`
`create_upload`	Prepares the upload of a local image: an upload URL and the id to pass as an image (see below).	a creation permission
`get_generation`	Retrieves a generation, waiting for its end if it is in progress (`GET /v1/generations/{id}`).	`generations_read`
`list_styles`	Lists the decoration styles (`GET /v1/styles`).	`decorations`
`list_edit_material_categories`	Lists the categories of the edit materials (`GET /v1/edit-material-categories`).	`edits`
`list_edit_materials`	Lists the edit materials, filtered by category or by name (`GET /v1/edit-materials`).	`edits`

Listing and canceling generations are only available on /v1.

How it works

The arguments of a tool use the names and values of the route's parameters, except background, which does not exist: the tool always waits for the end, within the limit described below. An unknown argument is refused.
A creation tool waits for the end of the generation for 50 seconds at most, image downloads included: a short generation (test mode, upscaling) comes back finished. Otherwise, get_generation waits for its end for up to wait_seconds seconds (0 to 50, default 50); if it is still in progress, the agent calls it again right away, without pausing. After 5 minutes, the agent stops and gives the user the id: the generation continues and stays readable.
Send images by URL, including a generation's output[0].url to chain several generations. An MCP message carries no image (64 KB at most): for a local image, the agent calls create_upload, sends the file with a PUT to upload_url (before upload_url_expires_at), then passes the returned id (file_…) as image, mask or layers[].element, with a key of the same mode. The file is a JPEG, PNG or WebP image of 10 MB at most (max_bytes). Each file serves one generation (a refused request leaves it available); an unused file is deleted 1 hour after its creation, and an id already used or deleted gets 404 resource_not_found. create_upload is free, but requires a positive balance in live mode; waiting files are limited by tier (generations per minute × 5), beyond that: 429 rate_limit_exceeded.
A tool returns the /v1 object in JSON. For a generation, a sentence also gives the next step. No image is attached to the result: the output image, at full resolution, is at the output[0].url address, which the assistant passes on to the user or saves if it can write files. With the generation id (gen_…), get_generation retrieves it for the 24 hours after its end.
A refused request gives a tool result in error, which holds the /v1 error body (see Errors). Nothing is charged.
Creation tools accept the idempotency_key argument (1 to 255 characters), equivalent to the Idempotency-Key header (see Idempotency). Idempotency keys are shared by /v1 and the MCP server: the same value used on both gets 409 idempotency_key_reused.
The rate limits are those of /v1: every request to /mcp counts, and the generations launched through MCP count in the same quota of generations launched. In the console request log, a tool call appears as /mcp/<tool>.