MCP ja tekoälyavustajat

Model Context Protocol on avoin standardi, jolla tekoälyavustajille annetaan työkaluja. Gradientlyn isännöity MCP-palvelin toimii osoitteessa https://gradiently.design/api/mcp. Yhdistä se kerran API-avaimella, niin avustajasi voi kutsua Gradientlyn työkaluja, kun keskustelet sen kanssa. Jokainen työkalu tekee samat API-pyynnöt kuin oma koodisi tekisi, joten sillä on samat oikeudet, lisenssit, krediitit ja rajat.

Ennen kuin yhdistät

• Luo avain kohdassa Asetukset › API ja agentit (katso API-avaimet ja oikeudet). Avain ratkaisee, missä työtilassa avustaja toimii ja mitkä työkalut toimivat.
• Jokaisessa palvelimelle lähetetyssä pyynnössä, myös ensimmäisessä, on oltava avain muodossa Authorization: Bearer gr_live_…. Ilman sitä palvelin vastaa 401.
• Palvelin käyttää Streamable HTTP -yhteyttä tilattomasti JSON-vastauksin. Se ei tarvitse istuntoa, eikä erillistä tapahtumavirtaa tarvitse avata.
• Palvelin hyväksyy vain API-avaimia. Se ei tarjoa OAuth-kirjautumista.

Yhdistä Claude Code

Lisää Gradiently etäpalvelimeksi HTTP:n yli niin, että avaimesi on otsakkeessa. Pidä avain ympäristömuuttujassa, jotta se ei koskaan päädy komentohistoriaasi tai versionhallintaan tallennettuun tiedostoon.

export GRADIENTLY_API_KEY="gr_live_…"

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

Aloita uusi Claude Code -istunto ja pyydä sitä listaamaan Gradientlyn työkalut, niin näet, toimiiko yhteys. Jos se ilmoittaa tunnistautumisvirheestä, avain on kirjoitettu väärin tai kumottu, tai sen luoja ei ole enää työtilan omistaja tai ylläpitäjä.

Muut asiakasohjelmat

Mikä tahansa asiakasohjelma, joka voi lisätä etä-MCP-palvelimen Streamable HTTP:n yli ja lähettää mukautetun pyyntöotsakkeen, voi käyttää Gradientlyä samalla URL-osoitteella ja otsakkeella. Se, onnistuuko tämä omalla ohjelmallasi, riippuu ohjelmasta ja sen versiosta.

• Claude Desktop ja claude.ai lisäävät etäpalvelimia mukautettuina liittiminä. Jos liittimen lomakkeessa voi asettaa Authorization-otsakkeen, käytä yllä olevaa URL-osoitetta ja otsaketta. Jos se tarjoaa vain OAuth-kirjautumisen, Gradientlyä ei voi vielä yhdistää siellä.
• ChatGPT ja muut avustajat: sama sääntö. Jos asiakasohjelma tukee etä-MCP-palvelimia bearer-otsakkeella, yhdistä se URL-osoitteella ja avaimellasi.
• JSON-tiedostolla määritettävät asiakasohjelmat hyväksyvät usein alla olevan muodon, joka näkyy myös Asetuksissa kohdassa Yhdistä MCP-asiakasohjelma. Tarkista ohjelmasi dokumentaatiosta sen tarkka muoto.

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

Miten työkalut toimivat

• Jokainen työkalu palauttaa tuloksensa JSON-tekstinä. Kun jokin epäonnistuu, työkalu palauttaa sen sijaan API:n virheilmoituksen, esimerkiksi puuttuvasta oikeudesta tai tuntemattomasta mallipohjasta.
• Brändiä tarvitsevat työkalut ottavat valinnaisen personality-arvon (sen id:n tai slugin). Ilman sitä ne käyttävät työtilan ensimmäistä brändiä.
• Designin tallentavat työkalut palauttavat sen Studio-linkin eli designin osoitteen /studio/<id> sivustolla gradiently.design.
• Monet työkalut hakevat ensin brändisi osoitteesta /api/me, joka vaatii sekä oikeuden workspaces:read että designs:read. Näiden työkalujen kohdalla alla luetellaan molemmat oikeudet.
• Työkalukutsu kuluttaa avaimesi pyyntörajaa kerran MCP-pyynnöstä ja kerran jokaisesta työkalun tekemästä API-pyynnöstä.

Markit

Maksua vaativa lunastus epäonnistuu viestillä, jonka mukaan se vaatii kassan; viimeistele se Gradientlyssä. Avain ei voi maksaa mitään.

Brändit ja työtila

tone hyväksyy enintään kolme arvoista calm, bold, warm, cool, playful, luxe, natural, technical, editorial ja nocturnal; pyyntö, jossa niitä on enemmän, hylätään. colours hyväksyy enintään kahdeksan hex-väriä, ja count pyytää yhdestä kahdeksaan ehdotusta; myös näiden rajojen ylittävä pyyntö hylätään. Kun otat ehdotuksen käyttöön, lähetä täsmälleen sama syöte, josta se luotiin, ja ehdotuksen key: palvelin tekee ehdotuksen uudelleen tuosta syötteestä eikä koskaan luota asiakasohjelman lähettämään reseptiin.

Suunnittelu

design ja create_designs kuluttavat työtilan AI-krediittejä samoin kuin Designer Studiossa. Kun saldo on liian pieni, ne epäonnistuvat viestillä, joka kertoo siitä; lisää krediittejä kohdassa Asetukset › AI-krediitit. Kullakin henkilöllä voi olla käynnissä enintään kaksi sarjaa kerrallaan, ja valmis sarja on luettavissa noin kaksikymmentä minuuttia. Itse designit säilyvät.

Sommitelma nimeää koon size (esiasetuksen id, kuten ig-post, x-post tai li-banner, tai {w, h} pikseleinä), asettelun layout (statement, editorial, poster, split, stat, quote, list, event tai minimal) ja lukujärjestyksessä olevat lohkot blocks, joilla kullakin on role, kuten headline, body tai cta, sekä sen 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" }
    ]
  }
}

Muokkaaminen ja vienti

wear_mark designille vaatii oikeudet designs:read ja designs:write. Markin tekeminen brändin Markiksi vaatii oikeudet workspaces:read, designs:read ja personalities:write sekä Markin, joka on hallussasi voimassa olevalla lisenssillä. Jos nimeät Markin sen koodilla, tarvitaan myös marks:read.

render_design ottaa arvot width ja height 1:n ja 4096 pikselin väliltä sekä format-arvon png tai pdf. page lasketaan nollasta: PNG renderöi oletuksena ensimmäisen sivun ja PDF kaikki sivut. PDF säilyttää jokaisen sivun Studion koossa, joten pyytämäsi koon on vastattava sitä. Renderöinti vaatii designin Markille saman vientilisenssin kuin Studio, eikä se koskaan julkaise tai muuta designia.

Esimerkkikehotteita

• ”Etsi Markkinoilta tummia Markeja, joissa on kromia, ja näytä kolme lähimpänä syvää sinivihreää olevaa.” Käyttää työkalua search_marks.
• ”Luo brändisuuntia Hearthille, naapuruston leipomolle, rauhallinen ja lämmin, ja ota käyttöön se, jonka paletti on pehmein.” Käyttää työkaluja generate_brand ja adopt_brand.
• ”Tee Mark nimeltä Night Harbour: tyhjä pohja, laivastonsinisestä natriumoranssiin, yksi hillitty rakeisuustaso. Korjaa kaikki, mistä arviointi huomauttaa, ja tallenna se sitten.” Käyttää työkaluja make_mark ja save_mark.
• ”Vaihda designin 4f1c… otsikoksi ’Ovet aukeavat seitsemältä’ ja tee kopiot Instagram-tarinaa ja X-julkaisua varten.” Käyttää työkaluja get_design, update_design_text ja resize_copies.
• ”Renderöi design 4f1c… 1080 × 1350 -kokoiseksi PNG-kuvaksi ja tallenna se tiedostoon launch.png.” Käyttää työkalua render_design.
• ”Tee juliste kattoterassin juhannusjuhliimme 21. kesäkuuta, auringonlaskusta auringonnousuun.” Käyttää työkalua design, joka vaatii oikeuden workspaces:read.

Näiden työkalujen taustalla olevien päätepisteiden koko referenssi on sivulla API-referenssi. Kaikessa muussa lähetä meille pyyntö.