Guides

Serveur MCP

Le serveur MCP (Model Context Protocol) expose l’API sous forme d’outils utilisables par un agent : Claude Code, Codex, Cursor, VS Code avec GitHub Copilot, Gemini CLI ou tout autre client MCP. Chaque outil appelle une route de /v1, avec les mêmes validations, prix, limites et mode test.

Élément	Valeur
URL	`https://api.renderthink.com/mcp`
Transport	HTTP « streamable », sans session.
Authentification	Une clé d’API dans l’en-tête `Authorization: Bearer …` : `rt_test_…` pour les essais, `rt_live_…` en production.

Configuration

Les exemples lisent la clé dans la variable d’environnement RENDERTHINK_API_KEY lorsque le client le permet. Gardez la clé dans la configuration utilisateur du client, jamais dans un fichier versionné. Si une clé est exposée, révoquez-la dans la console, écran Clés d’API.

Claude Code

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

Codex

Dans ~/.codex/config.toml, avec la clé lue dans la variable d’environnement :

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

Cursor

Dans ~/.cursor/mcp.json (ou dans le .cursor/mcp.json d’un projet), avec la clé lue dans la variable d’environnement :

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

VS Code (GitHub Copilot)

Dans .vscode/mcp.json, avec la clé demandée une fois puis conservée par VS Code :

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

Gemini CLI

Dans ~/.gemini/settings.json, avec la clé lue dans la variable d’environnement :

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

Autres clients

Tout client compatible avec le transport HTTP « streamable » et capable d’envoyer un en-tête Authorization fonctionne : indiquez l’URL ci-dessus et la clé en Bearer. Les connecteurs des assistants en ligne (ChatGPT, Claude sur le web) passent en général par une connexion OAuth, que le serveur MCP de RenderThink ne prend pas en charge.

Outils

Outil	Description	Droit
`create_render`	Crée un rendu (`POST /v1/renders`).	`renders`
`create_edit`	Crée une édition, par consigne ou par masque (`POST /v1/edits`).	`edits`
`create_decoration`	Crée une décoration (`POST /v1/decorations`).	`decorations`
`create_upscale`	Crée un upscaling (`POST /v1/upscales`).	`upscales`
`create_upload`	Prépare l’envoi d’une image locale : une adresse d’envoi et l’identifiant à passer en image (voir ci-dessous).	un droit de création
`get_generation`	Lit une génération, en attendant sa fin si elle est en cours (`GET /v1/generations/{id}`).	`generations_read`
`list_styles`	Liste les styles de décoration (`GET /v1/styles`).	`decorations`
`list_edit_material_categories`	Liste les catégories des matériaux d’édition (`GET /v1/edit-material-categories`).	`edits`
`list_edit_materials`	Liste les matériaux d’édition, filtrés par catégorie ou par nom (`GET /v1/edit-materials`).	`edits`

La liste et l’annulation des générations ne sont disponibles que sur /v1.

Fonctionnement

Les arguments d’un outil reprennent les noms et les valeurs des paramètres de la route, sauf background, qui n’existe pas : l’outil attend toujours la fin, dans la limite décrite ci-dessous. Un argument inconnu est refusé.
Un outil de création attend la fin de la génération pendant 50 secondes au plus, téléchargement des images compris : une génération courte (mode test, upscaling) revient terminée. Sinon, get_generation attend sa fin pendant wait_seconds secondes au plus (de 0 à 50, 50 par défaut) ; si elle est toujours en cours, l’agent le rappelle aussitôt, sans pause. Au bout de 5 minutes, l’agent s’arrête et donne l’identifiant à l’utilisateur : la génération continue et reste lisible.
Passez les images par URL, y compris l’output[0].url d’une génération pour en enchaîner plusieurs. Un message MCP ne porte pas d’image (64 Ko au plus) : pour une image locale, l’agent appelle create_upload, envoie le fichier par PUT à l’adresse upload_url (avant upload_url_expires_at), puis passe l’identifiant rendu (file_…) en image, mask ou layers[].element, avec une clé du même mode. Le fichier est une image JPEG, PNG ou WebP de 10 Mo au plus (max_bytes). Chaque fichier sert à une seule génération (une requête refusée le laisse disponible) ; non utilisé, il est effacé une heure après sa création, et un identifiant déjà pris ou effacé reçoit 404 resource_not_found. create_upload n’est pas facturé, mais exige en mode réel un solde positif ; les fichiers en attente sont limités selon le palier (générations par minute × 5), au-delà : 429 rate_limit_exceeded.
Un outil renvoie l’objet de /v1 en JSON. Pour une génération, une phrase indique en plus l’étape suivante. Aucune image n’est jointe au résultat : l’image produite, en pleine résolution, est à l’adresse output[0].url, que l’assistant transmet à l’utilisateur ou enregistre s’il peut écrire des fichiers. Avec l’identifiant de la génération (gen_…), get_generation la retrouve pendant les 24 heures qui suivent sa fin.
Une requête refusée donne un résultat d’outil en erreur, qui contient le corps d’erreur de /v1 (voir Erreurs). Rien n’est débité.
Les outils de création acceptent l’argument idempotency_key (1 à 255 caractères), équivalent de l’en-tête Idempotency-Key (voir Idempotence). Les clés d’idempotence sont communes à /v1 et au serveur MCP : une même valeur utilisée sur les deux reçoit 409 idempotency_key_reused.
Les limites de débit sont celles de /v1 : chaque requête vers /mcp compte, et les générations lancées par MCP entrent dans le même quota de générations lancées. Dans le journal des requêtes de la console, un appel d’outil apparaît sous /mcp/<outil>.