MCP und KI-Assistenten

Das Model Context Protocol ist ein offener Standard, um KI-Assistenten Werkzeuge zu geben. Gradiently betreibt einen gehosteten MCP-Server unter https://gradiently.design/api/mcp. Verbinde ihn einmal mit einem API-Schlüssel, und dein Assistent kann die Werkzeuge von Gradiently aufrufen, während du mit ihm sprichst. Jedes Werkzeug stellt dieselben API-Anfragen, die dein eigener Code stellen würde, und hat daher dieselben Berechtigungen, Lizenzen, Credits und Limits.

Bevor du dich verbindest

• Erstelle einen Schlüssel unter Einstellungen › API und Agenten (siehe API-Schlüssel und Scopes). Der Schlüssel entscheidet, in welchem Arbeitsbereich der Assistent arbeitet und welche Werkzeuge funktionieren.
• Jede Anfrage an den Server muss den Schlüssel als Authorization: Bearer gr_live_… mitschicken, auch die erste. Ohne ihn antwortet der Server mit 401.
• Der Server spricht Streamable HTTP, zustandslos, mit JSON-Antworten. Er braucht keine Sitzung und hat keinen separaten Event-Stream, den du öffnen müsstest.
• Der Server akzeptiert nur API-Schlüssel. Eine Anmeldung per OAuth bietet er nicht an.

Claude Code verbinden

Füg Gradiently als Remote-Server über HTTP hinzu, mit deinem Schlüssel im Header. Bewahr den Schlüssel in einer Umgebungsvariable auf, damit er nie in deinem Shell-Verlauf oder einer committeten Datei landet.

export GRADIENTLY_API_KEY="gr_live_…"

claude mcp add --transport http gradiently https://gradiently.design/api/mcp \
  --header "Authorization: Bearer $GRADIENTLY_API_KEY"

Starte eine neue Sitzung in Claude Code und bitte es, die Werkzeuge von Gradiently aufzulisten, um die Verbindung zu prüfen. Meldet es einen Authentifizierungsfehler, wurde der Schlüssel falsch eingegeben oder widerrufen, oder sein Ersteller ist kein Inhaber oder Admin des Arbeitsbereichs mehr.

Andere Clients

Jeder Client, der einen Remote-MCP-Server über Streamable HTTP hinzufügen und einen eigenen Request-Header senden kann, kann Gradiently mit derselben URL und demselben Header nutzen. Ob deiner das kann, hängt vom Client und seiner Version ab.

• Claude Desktop und claude.ai fügen Remote-Server als benutzerdefinierte Connectors hinzu. Wenn du im Connector-Formular einen Authorization-Header setzen kannst, nimm die URL und den Header von oben. Bietet es nur eine Anmeldung per OAuth an, lässt sich Gradiently dort noch nicht verbinden.
• ChatGPT und andere Assistenten: dieselbe Regel. Wo der Client Remote-MCP-Server mit einem Bearer-Header unterstützt, verbinde ihn mit der URL und deinem Schlüssel.
• Clients, die über eine JSON-Datei konfiguriert werden, akzeptieren oft die Form unten, die auch in den Einstellungen unter Einen MCP-Client verbinden steht. Das genaue Format findest du in der Dokumentation deines Clients.

{
  "mcpServers": {
    "gradiently": {
      "url": "https://gradiently.design/api/mcp",
      "headers": { "Authorization": "Bearer gr_live_…" }
    }
  }
}

Wie sich die Werkzeuge verhalten

• Jedes Werkzeug gibt sein Ergebnis als JSON-Text zurück. Wenn etwas scheitert, gibt das Werkzeug stattdessen die Fehlermeldung der API zurück, etwa zu einem fehlenden Scope oder einer unbekannten Vorlage.
• Werkzeuge, die eine Marke brauchen, nehmen optional personality (ihre ID oder ihren Slug). Ohne diese Angabe nutzen sie die erste Marke des Arbeitsbereichs.
• Werkzeuge, die ein Design speichern, geben seinen Studio-Link zurück, die Adresse /studio/<id> des Designs auf gradiently.design.
• Mehrere Werkzeuge schlagen deine Marken zuerst über /api/me nach, was sowohl workspaces:read als auch designs:read braucht. Bei diesen Werkzeugen stehen unten beide Scopes.
• Ein Werkzeugaufruf zählt gegen das Ratenlimit deines Schlüssels einmal für die MCP-Anfrage und einmal für jede API-Anfrage, die das Werkzeug stellt.

Marks

Ein Sichern, das eine Zahlung braucht, scheitert mit dem Hinweis, dass ein Checkout nötig ist; schließ es in Gradiently ab. Ein Schlüssel kann nichts bezahlen.

Marken und Arbeitsbereich

tone nimmt bis zu drei der Werte calm, bold, warm, cool, playful, luxe, natural, technical, editorial und nocturnal an; eine Anfrage mit mehr wird abgelehnt. colours nimmt bis zu acht Hex-Farben an, und count fordert einen bis acht Vorschläge an; mehr davon wird ebenfalls abgelehnt. Um einen Vorschlag zu übernehmen, schick genau die Eingabe, die ihn erzeugt hat, zusammen mit dem key des Vorschlags: Der Server erzeugt den Vorschlag aus dieser Eingabe neu und vertraut nie einem Rezept, das der Client schickt.

Gestalten

design und create_designs verbrauchen die KI-Credits des Arbeitsbereichs, so wie der Designer im Studio. Ist das Guthaben zu niedrig, scheitern sie mit einer entsprechenden Meldung; lade unter Einstellungen › KI-Credits auf. Pro Person laufen höchstens zwei Reihen gleichzeitig, und eine fertige Reihe bleibt etwa zwanzig Minuten lang abrufbar. Die Designs selbst bleiben erhalten.

Eine Komposition nennt eine size (die ID einer Vorgabe wie ig-post, x-post oder li-banner, oder {w, h} in Pixeln), ein layout (statement, editorial, poster, split, stat, quote, list, event oder minimal) und blocks in Lesereihenfolge, jeweils mit einer role wie headline, body oder cta und ihrem 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" }
    ]
  }
}

Bearbeiten und exportieren

wear_mark auf einem Design braucht designs:read und designs:write. Um einen Mark zum Mark einer Marke zu machen, braucht es workspaces:read, designs:read und personalities:write sowie einen Mark, den du mit aktiver Lizenz hältst. Wenn du den Mark über seinen Code angibst, brauchst du außerdem marks:read.

render_design nimmt width und height von 1 bis 4096 Pixeln und format png oder pdf. page zählt ab 0: PNG rendert standardmäßig die erste Seite, PDF alle Seiten. Ein PDF behält jede Seite in ihrer Größe aus dem Studio, die angefragte Größe muss also passen. Zum Rendern braucht es für den Mark des Designs dieselbe Exportlizenz wie im Studio, und das Design wird dabei nie veröffentlicht oder verändert.

Beispiel-Prompts

• „Finde dunkle Marks mit Chrom im Markt und zeig mir die drei, die Dunkelpetrol am nächsten kommen.“ Nutzt search_marks.
• „Generiere Markenrichtungen für Hearth, eine Bäckerei im Viertel, ruhig und warm, und übernimm die mit der sanftesten Palette.“ Nutzt generate_brand und adopt_brand.
• „Schmiede einen Mark namens Night Harbour: ein leerer Grund, Marineblau bis Natriumorange, eine ruhige Körnungsebene. Beheb alles, was die Prüfung anmerkt, und speichere ihn dann.“ Nutzt make_mark und save_mark.
• „Ändere die Überschrift in Design 4f1c… zu ‚Einlass ab sieben‘ und mach Kopien für eine Instagram-Story und einen X-Post.“ Nutzt get_design, update_design_text und resize_copies.
• „Rendere Design 4f1c… als PNG mit 1080 mal 1350 und speichere es als launch.png.“ Nutzt render_design.
• „Mach ein Poster für unsere Sonnwendparty auf der Dachterrasse, 21. Juni, von Sonnenuntergang bis Sonnenaufgang.“ Nutzt design, das workspaces:read braucht.

Die vollständige Referenz der Endpunkte hinter diesen Werkzeugen steht unter API-Referenz. Für alles andere schick uns eine Anfrage.