Le serveur accepte les jetons d’accès OAuth et les clés API d’espace. Les mêmes autorisations, licences, crédits et limites s’appliquent aux deux. Le Model Context Protocol est un standard ouvert qui donne des outils aux assistants IA. Gradiently héberge un serveur MCP. ChatGPT s’y connecte à l’adresse https://, Claude et les autres clients à l’adresse https://. Connectez-le une fois avec une clé API, et votre assistant peut appeler les outils de Gradiently pendant que vous lui parlez. Chaque outil fait les mêmes requêtes API que votre propre code : il a donc les mêmes permissions, licences, crédits et limites.
Avant de vous connecter
- Créez une clé dans Paramètres › API et agents (voir Clés API et permissions). La clé détermine dans quel espace de travail l’assistant travaille et quels outils fonctionneront.
- Un client avec clé API envoie
Authorization: Bearer gr_live_…. ChatGPT et Claude envoient le jeton OAuth après la connexion. - Le serveur parle Streamable HTTP, sans état, avec des réponses JSON. Il n’a besoin d’aucune session et n’a pas de flux d’événements séparé à ouvrir.
- Le serveur accepte les jetons d’accès OAuth et les clés API d’espace. Les mêmes autorisations, licences, crédits et limites s’appliquent aux deux.
Connecter ChatGPT et Claude
Ajoutez un connecteur personnalisé avec ChatGPT: https://; Claude: https:// et choisissez la connexion OAuth. Connectez-vous à Gradiently, choisissez un espace et vérifiez les autorisations. Seuls les propriétaires et administrateurs peuvent connecter un assistant.
Les connexions expirent après une heure et se renouvellent automatiquement pendant 30 jours au maximum. Révoquez une connexion dans Paramètres › API et agents pour arrêter immédiatement son accès et son renouvellement.
Une connexion personnalisée et une présence dans l’annuaire public sont distinctes. La présence dans l’annuaire nécessite l’examen et l’approbation d’OpenAI ou d’Anthropic.
Connecter Claude Code
Ajoutez Gradiently comme serveur distant en HTTP, avec votre clé dans l’en-tête. Gardez la clé dans une variable d’environnement pour qu’elle ne se retrouve jamais dans l’historique de votre terminal ni dans un fichier committé.
# Paste your key when asked. It stays hidden and out of your shell history.
read -rs GRADIENTLY_API_KEY && export GRADIENTLY_API_KEY
claude mcp add --transport http gradiently https://gradiently.design/api/mcp \
--header "Authorization: Bearer $GRADIENTLY_API_KEY"Ouvrez une nouvelle session Claude Code et demandez-lui de lister les outils de Gradiently pour vérifier la connexion. S’il signale une erreur d’authentification, la clé a été mal saisie, a été révoquée, ou son créateur n’est plus propriétaire ou admin de l’espace de travail.
Autres clients
Tout client capable d’ajouter un serveur MCP distant en Streamable HTTP et d’envoyer un en-tête de requête personnalisé peut utiliser Gradiently avec la même URL et le même en-tête. Que le vôtre le puisse dépend du client et de sa version.
- Les clients configurés par un fichier JSON acceptent souvent la forme ci-dessous, également affichée dans les Paramètres sous Connecter un client MCP. Consultez la documentation de votre client pour son format exact.
{
"mcpServers": {
"gradiently": {
"url": "https://gradiently.design/api/mcp",
"headers": { "Authorization": "Bearer gr_live_…" }
}
}
}Comment se comportent les outils
- Les outils renvoient du texte JSON.
inspect_designrenvoie aussi une image PNG. En cas d’échec, un message d’erreur est renvoyé. - Les outils qui ont besoin d’une marque acceptent un
personalityfacultatif (son id ou son slug). Sans lui, ils utilisent la première marque de l’espace de travail. - Les outils qui enregistrent une création renvoient son lien Studio, l’adresse
/de la création sur gradiently.design.studio/ <id> - Plusieurs outils cherchent d’abord vos marques via
/, qui demande à la foisapi/ me workspaces:readetdesigns:read. Ces outils indiquent les deux permissions ci-dessous. - Un appel d’outil compte dans la limite de débit de votre clé une fois pour la requête MCP, puis une fois pour chaque requête API que fait l’outil.
Marks
search_marksCe qu’il fait
Entrées
q, tone (dark ou light), limit (de 1 à 120, 24 par défaut), tous facultatifsPermissions
marks:readget_markCe qu’il fait
Entrées
code (un code ou un id)Permissions
marks:readlist_marksCe qu’il fait
Entrées
Permissions
marks:readclaim_markCe qu’il fait
Entrées
codePermissions
marks:read, marks:claimexport_markCe qu’il fait
Entrées
mark, width, height, personalityPermissions
workspaces:read, designs:read, designs:writerestore_mark_versionCe qu’il fait
Entrées
mark, versionPermissions
brand:generateupdate_mark_versionCe qu’il fait
Entrées
mark, version, label, starredPermissions
brand:generatedelete_mark_versionCe qu’il fait
Entrées
mark, versionPermissions
brand:generateUne réservation qui demande un paiement échoue avec un message indiquant qu’elle doit passer par le paiement ; terminez-la dans Gradiently. Une clé ne peut rien payer.
Marques et espace de travail
list_personalitiesCe qu’il fait
Entrées
Permissions
workspaces:read, designs:readcreate_personalityCe qu’il fait
Entrées
namePermissions
personalities:writeget_brand_profileCe qu’il fait
Entrées
personalityPermissions
workspaces:read, designs:readupdate_brand_profileCe qu’il fait
Entrées
personality, profilePermissions
workspaces:read, designs:read, personalities:writemy_workspaceCe qu’il fait
Entrées
Permissions
workspaces:read, designs:read, marks:readlist_workspacesCe qu’il fait
Entrées
cursorPermissions
workspaces:readinvite_memberCe qu’il fait
Entrées
workspaceId, email, role (admin, editor ou viewer)Permissions
members:writetone accepte jusqu’à trois valeurs parmi calm, bold, warm, cool, playful, luxe, natural, technical, editorial et nocturnal ; une requête qui en envoie davantage est refusée. colours accepte jusqu’à huit couleurs hexadécimales et count demande de une à huit propositions ; au-delà, la requête est refusée aussi. Pour adopter une proposition, envoyez exactement l’entrée qui l’a générée avec la key de la proposition : le serveur recrée la proposition à partir de cette entrée et ne fait jamais confiance à une recette envoyée par le client.
Créer
Pour une création originale, demandez à votre IA connectée de lire le profil de marque et get_design_guidance, de créer avec draw_design, d’examiner l’image réelle avec inspect_design, puis d’affiner avec edit_design. Ces outils directs n’utilisent aucun crédit IA Gradiently. Les limites de votre fournisseur et les autorisations de compte et d’exportation s’appliquent toujours. Un dessin peut contenir les illustrations vectorielles de l’hôte, du SVG assaini, de vrais graphiques, des éléments graphiques de la bibliothèque et des photos sous licence ; tout reste modifiable dans le Studio. La recherche et l’import de photos passent par Openverse, un catalogue externe.
get_design_guidanceCe qu’il fait
Entrées
purpose, topicPermissions
draw_designCe qu’il fait
Entrées
drawing, personality, mark, designId, page, titlePermissions
designs:write, workspaces:read, designs:read, marks:readinspect_designCe qu’il fait
Entrées
id, page, maxDimensionPermissions
designs:readfind_iconsCe qu’il fait
Entrées
query, limitPermissions
find_graphicsCe qu’il fait
Entrées
query, limitPermissions
find_photosCe qu’il fait
Entrées
query, countPermissions
designs:readimport_photoCe qu’il fait
Entrées
idPermissions
designs:writedesignDemande au Designer de Gradiently de réaliser une création, ou d’en modifier une, à partir d’une demande en langage courant. Il lit le profil de la marque et le Mark, crée, vérifie et enregistre. Utilise des crédits IA Gradiently.Entrées
request, personality, size, designId, scope, selectionPermissions
workspaces:read, designs:read, designs:writecreate_designsCe qu’il fait
Entrées
brief, items (size, brief, title), title, personality, mark, waitPermissions
workspaces:read, designs:read, designs:writeget_design_setCe qu’il fait
Entrées
idPermissions
designs:readstop_design_setCe qu’il fait
Entrées
idPermissions
designs:writecompose_designCe qu’il fait
Entrées
composition, personality, designId, titlePermissions
workspaces:read, designs:read, designs:writelist_sizesCe qu’il fait
Entrées
Permissions
create_designCe qu’il fait
Entrées
form, size, copy, look, personalityPermissions
workspaces:read, designs:read, designs:writedesign et create_designs consomment les crédits IA de l’espace de travail, comme le Designer dans le Studio. Quand le solde est trop bas, ils échouent avec un message qui le signale ; rechargez dans Paramètres › Crédits IA. Deux séries au plus tournent en même temps par personne, et une série terminée reste consultable une vingtaine de minutes. Les créations elles-mêmes restent.
Une composition indique une size (un id de taille prédéfinie comme ig-post, x-post ou li-banner, ou {w, h} en pixels), un layout (statement, editorial, poster, split, stat, quote, list, event ou minimal) et des blocks dans l’ordre de lecture, chacun avec un role comme headline, body ou cta, et son text.
{
"composition": {
"size": "ig-post",
"layout": "event",
"blocks": [
{ "role": "eyebrow", "text": "Summer supper club" },
{ "role": "headline", "text": "Long table on the roof" },
{ "role": "details", "text": "", "items": ["Saturday 21 June", "7pm till late"] },
{ "role": "cta", "text": "Book a seat" }
]
}
}compose_design. La réponse contient l’id de la création, son lien Studio, les problèmes relevés et les éléments placés.Modifier et exporter
list_designsCe qu’il fait
Entrées
personalityPermissions
workspaces:read, designs:readget_designCe qu’il fait
Entrées
id, page, kind, name, textPermissions
designs:readedit_designCe qu’il fait
Entrées
id, ops, pagePermissions
designs:writeupdate_design_textCe qu’il fait
Entrées
id, text (id d’élément vers mots)Permissions
designs:read, designs:writeresize_copiesCe qu’il fait
Entrées
id, sizesPermissions
designs:read, designs:writewear_markCe qu’il fait
Entrées
mark, et design ou personalityPermissions
render_designCe qu’il fait
Entrées
id, width, height, format, pagePermissions
designs:readexport_design_linkCe qu’il fait
/ d/ <id>, que toute personne qui l’a peut ouvrir.Entrées
idPermissions
designs:writewear_mark sur une création demande designs:read et designs:write. Faire d’un Mark celui d’une marque demande workspaces:read, designs:read et personalities:write, ainsi qu’un Mark que vous détenez avec une licence active. Désigner le Mark par son code demande aussi marks:read.
render_design accepte width et height de 1 à 4096 pixels et format png ou pdf. page compte à partir de 0 : par défaut, le PNG rend la première page et le PDF toutes les pages. Un PDF garde chaque page à sa taille dans le Studio : la taille demandée doit donc correspondre. Le rendu exige la même licence d’export pour le Mark de la création que dans le Studio, et il ne publie ni ne modifie jamais la création.
Vidéos, audio et sous-titres
Utilisez find_uploads pour trouver les références de sources autorisées, puis edit_design avec add_video, update_video, split_video, add_audio, update_audio, split_audio, remove_audio, set_element_timing, set_captions ou remove_captions. N’inventez jamais la durée d’une source. Les découpes vidéo et la visibilité des éléments utilisent les secondes de la page ; les débuts et découpes audio et les sous-titres utilisent les secondes du document. L’audio ne prolonge pas les scènes. Les sous-titres acceptent vos répliques horodatées ou du contenu SRT/WebVTT ; la transcription automatique n’est pas disponible. get_design renvoie la chronologie complète et les pistes. export_captions renvoie le contenu SRT/WebVTT par parties de 100 sous-titres et 48 000 caractères maximum ; utilisez nextOffset pour la partie suivante.
Exemples de demandes
- « Trouve dans le Marché des Marks sombres avec du chrome et montre-moi les trois plus proches du bleu canard profond. » Utilise
search_marks. - « Remplace le titre de la création 4f1c… par “Ouverture des portes à 19 h” et fais-en des copies pour une story Instagram et un post X. » Utilise
get_design,update_design_textetresize_copies. - « Rends la création 4f1c… en PNG de 1080 sur 1350 et enregistre-la sous launch.png. » Utilise
render_design. - « Crée une affiche pour notre fête du solstice sur le toit, le 21 juin, du coucher au lever du soleil. » Utilise
design, qui demandeworkspaces:read.
La référence complète des points de terminaison derrière ces outils se trouve dans Référence de l’API. Pour tout le reste, envoyez-nous une demande.