MCP et assistants IA

Le Model Context Protocol est un standard ouvert qui donne des outils aux assistants IA. Gradiently héberge un serveur MCP à l’adresse https://gradiently.design/api/mcp. 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.
• Chaque requête vers le serveur doit porter la clé sous la forme Authorization: Bearer gr_live_…, y compris la première. Sans elle, le serveur répond 401.
• 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 n’accepte que les clés API. Il ne propose pas de connexion OAuth.

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é.

export GRADIENTLY_API_KEY="gr_live_…"

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.

• Claude Desktop et claude.ai ajoutent les serveurs distants comme connecteurs personnalisés. Si le formulaire du connecteur permet de définir un en-tête Authorization, utilisez l’URL et l’en-tête ci-dessus. S’il ne propose qu’une connexion OAuth, Gradiently ne peut pas encore y être connecté.
• ChatGPT et les autres assistants : même règle. Là où le client prend en charge les serveurs MCP distants avec un en-tête bearer, connectez-le avec l’URL et votre clé.
• 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

• Chaque outil renvoie son résultat sous forme de texte JSON. En cas d’échec, l’outil renvoie à la place le message d’erreur de l’API, par exemple une permission manquante ou un modèle inconnu.
• Les outils qui ont besoin d’une marque acceptent un personality facultatif (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 /studio/<id> de la création sur gradiently.design.
• Plusieurs outils cherchent d’abord vos marques via /api/me, qui demande à la fois workspaces:read et designs: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

Une 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

tone 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

design 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" }
    ]
  }
}

Modifier et exporter

wear_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.

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.
• « Génère des directions de marque pour Hearth, une boulangerie de quartier, calme et chaleureuse, et adopte celle à la palette la plus douce. » Utilise generate_brand et adopt_brand.
• « Forge un Mark appelé Night Harbour : un fond vide, du bleu marine à l’orange sodium, une seule couche de grain discrète. Corrige tout ce que la vérification signale, puis enregistre-le. » Utilise make_mark et save_mark.
• « 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_text et resize_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 demande workspaces: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.