MCP en AI-assistenten

Het Model Context Protocol is een open standaard om AI-assistenten tools te geven. Gradiently draait een gehoste MCP-server op https://gradiently.design/api/mcp. Koppel hem één keer met een API-key, en je assistent kan de tools van Gradiently aanroepen terwijl je met hem praat. Elke tool doet dezelfde API-requests als je eigen code zou doen, dus hij heeft dezelfde rechten, licenties, credits en limieten.

Voordat je koppelt

Maak een key aan in Instellingen › API en agents (zie API-keys en rechten). De key bepaalt in welke workspace de assistent werkt en welke tools werken.
Elke request naar de server moet de key meesturen als Authorization: Bearer gr_live_…, ook de eerste. Zonder key antwoordt de server met 401.
De server spreekt Streamable HTTP, stateless, met JSON-antwoorden. Hij heeft geen sessie nodig en er is geen aparte eventstream om te openen.
De server accepteert alleen API-keys. Inloggen via OAuth wordt niet aangeboden.

Claude Code koppelen

Voeg Gradiently toe als externe server via HTTP, met je key in de header. Bewaar de key in een omgevingsvariabele, zodat hij nooit in je shellgeschiedenis of in een gecommit bestand terechtkomt.

bash

export GRADIENTLY_API_KEY="gr_live_…"

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

Start een nieuwe sessie in Claude Code en vraag om de tools van Gradiently te tonen, om de verbinding te controleren. Meldt hij een authenticatiefout, dan is de key verkeerd getypt of ingetrokken, of is zijn maker geen eigenaar of beheerder van de workspace meer.

Andere clients

Elke client die een externe MCP-server via Streamable HTTP kan toevoegen en een eigen request-header kan meesturen, kan Gradiently gebruiken met dezelfde URL en header. Of de jouwe dat kan, hangt af van de client en de versie.

Claude Desktop en claude.ai voegen externe servers toe als aangepaste connectors. Kun je in het connectorformulier een Authorization-header instellen, gebruik dan de URL en header hierboven. Biedt het alleen inloggen via OAuth, dan kun je Gradiently daar nog niet koppelen.
ChatGPT en andere assistenten: dezelfde regel. Ondersteunt de client externe MCP-servers met een bearer-header, koppel hem dan met de URL en je key.
Clients die je met een JSON-bestand instelt, accepteren vaak de vorm hieronder, die ook in Instellingen staat onder Een MCP-client verbinden. Kijk in de documentatie van je client voor het precieze formaat.

json

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

Hoe de tools werken

Elke tool geeft zijn resultaat terug als JSON-tekst. Gaat er iets mis, dan geeft de tool in plaats daarvan de foutmelding van de API terug, zoals een ontbrekend recht of een onbekende template.
Tools die een merk nodig hebben, nemen een optionele personality (het id of de slug). Zonder merk gebruiken ze het eerste merk van de workspace.
Tools die een ontwerp opslaan, geven de Studio-link terug: het adres /studio/<id> van het ontwerp op gradiently.design.
Verschillende tools zoeken eerst je merken op via /api/me, waarvoor zowel workspaces:read als designs:read nodig is. Die tools noemen hieronder beide rechten.
Een toolaanroep telt mee voor de limiet van je key: één keer voor de MCP-request en één keer voor elke API-request die de tool doet.

Marks

Tool	Wat hij doet	Invoer	Rechten
`search_marks`	Doorzoekt de openbare Markt op naam of code. Geeft kleuren, materialen, status en houder terug.	`q`, `tone` (dark of light), `limit` (1 tot 120, standaard 24), allemaal optioneel	`marks:read`
`get_mark`	Eén Mark met zijn volledige recept.	`code` (een code of een id)	`marks:read`
`list_marks`	Marks die voor deze workspace worden gehouden, met de status van de licentie, en je concepten erin.	geen	`marks:read`
`claim_mark`	Claimt een beschikbare Mark. De maker van de key wordt de houder, nooit de workspace.	`code`	`marks:read`, `marks:claim`
`make_mark`	Bouwt een Markrecept op basis van een bedoeling, of bewerkt er een, met een beoordeling van kleur en leesbaarheid en de dichtstbijzijnde Mark in de Markt. Slaat niets op.	`spec`, of `recipe` en `edit`	`marks:read`
`save_mark`	Slaat een recept op als je privé concept-Mark, of werkt een concept van jou bij. Geeft de Forge-link terug.	`name`, `recipe`, `id` (optioneel)	`brand:generate`
`export_mark`	Rendert een Mark op zichzelf als PNG, tot 4096 px per zijde.	`mark`, `width`, `height`, `personality`	`workspaces:read`, `designs:read`, `designs:write`
`list_mark_versions`	De opgeslagen versies van een concept, de nieuwste eerst. Alleen de maker van de Mark ziet ze.	`mark`, `cursor`	`marks:read`
`save_mark_version`	Bewaart een concept zoals het nu is, of een opgegeven recept, als versie met een naam.	`mark`, `label`, `recipe`	`brand:generate`
`restore_mark_version`	Zet een versie terug als concept. De huidige staat wordt eerst als versie bewaard.	`mark`, `version`	`brand:generate`
`update_mark_version`	Hernoemt een versie of geeft er een ster aan. Versies met een ster blijven bewaard.	`mark`, `version`, `label`, `starred`	`brand:generate`
`delete_mark_version`	Verwijdert een versie, nooit de gepubliceerde.	`mark`, `version`	`brand:generate`

Een claim waarvoor betaald moet worden, faalt met een melding dat er afgerekend moet worden; rond hem af in Gradiently. Een key kan nergens voor betalen.

Merken en workspace

Tool	Wat hij doet	Invoer	Rechten
`generate_brand`	Maakt merkkandidaten op basis van een naam en beschrijving. Dezelfde invoer geeft altijd dezelfde kandidaten.	`input`: `name`, `description`, `industry`, `tone`, `colours`, `count`, `nonce`	`brand:generate`
`adopt_brand`	Maakt van één kandidaat een concept-Mark, een merk en drie startontwerpen, in één stap.	`input` (ongewijzigd), `key`	`brand:generate`
`list_personalities`	De merken van de workspace, met hun id’s.	geen	`workspaces:read`, `designs:read`
`create_personality`	Maakt een merk met een naam.	`name`	`personalities:write`
`get_brand_profile`	Wat een merk is, voor wie het is, de toon, wat wel en niet mag, en de lettertypen.	`personality`	`workspaces:read`, `designs:read`
`update_brand_profile`	Vervangt het profiel van een merk. De Designer leest het voor elk ontwerp.	`personality`, `profile`	`workspaces:read`, `designs:read`, `personalities:write`
`my_workspace`	Jij, de merken van de workspace met hun Markcodes, en de Marks die ervoor worden gehouden.	geen	`workspaces:read`, `designs:read`, `marks:read`
`list_workspaces`	De workspace van de key en jouw rol erin.	`cursor`	`workspaces:read`
`invite_member`	Mailt een uitnodiging om lid te worden van de workspace, zeven dagen geldig.	`workspaceId`, `email`, `role` (admin, editor of viewer)	`members:write`

tone accepteert hoogstens drie van calm, bold, warm, cool, playful, luxe, natural, technical, editorial en nocturnal; een request met meer wordt geweigerd. colours accepteert tot acht hexkleuren en count vraagt om één tot acht kandidaten; meer dan dat wordt ook geweigerd. Om een kandidaat over te nemen, stuur je precies de invoer die hem genereerde, met de key van de kandidaat: de server maakt de kandidaat opnieuw op basis van die invoer en vertrouwt nooit een recept dat de client stuurt.

Ontwerpen

Tool	Wat hij doet	Invoer	Rechten
`design`	Vraagt de eigen Designer van Gradiently om op basis van een gewone vraag een ontwerp te maken of te wijzigen. Hij leest het merkprofiel en de Mark, ontwerpt, beoordeelt en slaat op.	`request`, `personality`, `size`, `designId`, `scope`, `selection`	`workspaces:read`, `designs:read`, `designs:write`
`create_designs`	Maakt op de achtergrond een reeks van maximaal twaalf ontwerpen vanuit één briefing.	`brief`, `items` (`size`, `brief`, `title`), `title`, `personality`, `mark`, `wait`	`workspaces:read`, `designs:read`, `designs:write`
`get_design_set`	De voortgang van een reeks en de Studio-link van elk ontwerp zodra het bestaat.	`id`	`designs:read`
`stop_design_set`	Stopt een lopende reeks. Ontwerpen die al getekend zijn, blijven opgeslagen.	`id`	`designs:write`
`compose_design`	Maakt de opmaak van je tekst met de layout-engine en slaat hem op. Geeft punten uit de beoordeling terug om op te lossen.	`composition`, `personality`, `designId`, `title`	`workspaces:read`, `designs:read`, `designs:write`
`find_templates`	Doorzoekt de handgemaakte ontwerpen van Gradiently. Geeft er tot zes terug, met een afbeelding en hun vakken.	`query`, `size`	elke key
`use_template`	Maakt een opgeslagen ontwerp van een template en behoudt de compositie.	`template`, `text`, `photos`, `icons`, `hide`, `personality`, `designId`	`workspaces:read`, `designs:read`, `designs:write`
`list_templates`	Id’s van starttemplates met de id’s van hun tekstelementen, en elk vast formaat.	geen	elke key
`create_design`	Maakt een ontwerp van een starttemplate-id, een vast formaat en tekst per element-id.	`template`, `size`, `copy`, `look`, `personality`	`workspaces:read`, `designs:read`, `designs:write`

design en create_designs gebruiken de AI-credits van de workspace, net als de Designer in de Studio. Is het saldo te laag, dan falen ze met een melding die dat zegt; waardeer op in Instellingen › AI-credits. Per persoon lopen er hoogstens twee reeksen tegelijk, en een afgeronde reeks blijft ongeveer twintig minuten leesbaar. De ontwerpen zelf blijven bestaan.

Een compositie noemt een size (een formaat-id zoals ig-post, x-post of li-banner, of {w, h} in pixels), een layout (statement, editorial, poster, split, stat, quote, list, event of minimal) en blocks in leesvolgorde, elk met een role zoals headline, body of cta en de bijbehorende text.

json

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

Invoer voor compose_design. Het antwoord bevat het id van het ontwerp, de Studio-link, punten uit de beoordeling en de elementen die zijn geplaatst.

Bewerken en exporteren

Tool	Wat hij doet	Invoer	Rechten
`list_designs`	De opgeslagen ontwerpen van een merk, met Studio-links.	`personality`	`workspaces:read`, `designs:read`
`get_design`	Het formaat en de pagina’s van een ontwerp, en elk element met zijn eigenschappen. Filter lange ontwerpen op pagina, soort, naam of tekst.	`id`, `page`, `kind`, `name`, `text`	`designs:read`
`edit_design`	Wijzigt een ontwerp met maximaal 100 bewerkingen, zoals iemand dat in de Studio zou doen, en slaat het op.	`id`, `ops`, `page`	`designs:write`
`update_design_text`	Vervangt de tekst van gekozen tekstelementen en behoudt de opmaak.	`id`, `text` (element-id naar tekst)	`designs:read`, `designs:write`
`resize_copies`	Slaat kopieën op in maximaal acht andere formaten, opnieuw opgemaakt zoals de Studio dat doet. Het origineel blijft ongewijzigd.	`id`, `sizes`	`designs:read`, `designs:write`
`wear_mark`	Zet een Mark op één ontwerp, of maakt hem de Mark van een merk voor nieuwe ontwerpen.	`mark`, en `design` of `personality`	zie hieronder
`render_design`	Rendert een opgeslagen ontwerp naar PNG of PDF met de engine van de Studio. Geeft het bestand terug als base64.	`id`, `width`, `height`, `format`, `page`	`designs:read`
`export_design_link`	Publiceert een bekijklink, `/d/<id>`, die iedereen met de link kan openen.	`id`	`designs:write`

wear_mark op een ontwerp heeft designs:read en designs:write nodig. Een Mark de Mark van een merk maken vraagt om workspaces:read, designs:read en personalities:write, en om een Mark die jij houdt met een actieve licentie. Noem je de Mark bij zijn code, dan is ook marks:read nodig.

render_design accepteert width en height van 1 tot 4096 pixels en format png of pdf. page telt vanaf 0: PNG rendert standaard de eerste pagina en PDF alle pagina’s. Een PDF houdt elke pagina op het formaat uit de Studio, dus het formaat dat je vraagt, moet daarbij passen. Voor renderen is dezelfde exportlicentie voor de Mark van het ontwerp nodig als in de Studio, en het ontwerp wordt nooit gepubliceerd of gewijzigd.

Voorbeeldprompts

“Zoek donkere Marks met chroom erin in de Markt en laat me de drie zien die het dichtst bij diep petrol liggen.” Gebruikt search_marks.
“Genereer merkrichtingen voor Hearth, een buurtbakkerij, rustig en warm, en neem de richting met het zachtste palet over.” Gebruikt generate_brand en adopt_brand.
“Smeed een Mark die Night Harbour heet: een lege ondergrond, van marineblauw naar natriumoranje, één rustige korrellaag. Los alles op wat de beoordeling aanwijst en sla hem dan op.” Gebruikt make_mark en save_mark.
“Verander de kop van ontwerp 4f1c… in ‘Deuren open om zeven uur’ en maak kopieën voor een Instagramstory en een X-post.” Gebruikt get_design, update_design_text en resize_copies.
“Render ontwerp 4f1c… als PNG van 1080 bij 1350 en sla het op als launch.png.” Gebruikt render_design.
“Maak een poster voor ons zonnewendefeest op het dak, 21 juni, van zonsondergang tot zonsopgang.” Gebruikt design, waarvoor workspaces:read nodig is.

De volledige referentie voor de endpoints achter deze tools staat op API-referentie. Voor al het andere kun je ons een verzoek sturen.