MCP e assistenti IA

Il Model Context Protocol è uno standard aperto per dare strumenti agli assistenti IA. Gradiently gestisce un server MCP ospitato all’indirizzo https://gradiently.design/api/mcp. Collegalo una volta con una chiave API, e il tuo assistente potrà chiamare gli strumenti di Gradiently mentre gli parli. Ogni strumento fa le stesse richieste API che farebbe il tuo codice, quindi ha gli stessi permessi, licenze, crediti e limiti.

Prima di collegarti

• Crea una chiave in Impostazioni › API e agenti (vedi Chiavi API e permessi). La chiave decide in quale spazio di lavoro opera l’assistente e quali strumenti funzioneranno.
• Ogni richiesta al server deve portare la chiave come Authorization: Bearer gr_live_…, compresa la prima. Senza chiave il server risponde 401.
• Il server usa Streamable HTTP, senza stato, con risposte JSON. Non richiede una sessione e non ha un flusso di eventi separato da aprire.
• Il server accetta solo chiavi API. Non offre l’accesso tramite OAuth.

Collegare Claude Code

Aggiungi Gradiently come server remoto via HTTP, con la tua chiave nell’header. Tieni la chiave in una variabile d’ambiente, così non finisce mai nella cronologia della shell o in un file di cui fai commit.

export GRADIENTLY_API_KEY="gr_live_…"

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

Avvia una nuova sessione di Claude Code e chiedigli di elencare gli strumenti di Gradiently per verificare il collegamento. Se segnala un errore di autenticazione, la chiave è stata scritta male o revocata, oppure chi l’ha creata non è più proprietario o amministratore dello spazio di lavoro.

Altri client

Qualsiasi client che possa aggiungere un server MCP remoto via Streamable HTTP e inviare un header personalizzato può usare Gradiently con lo stesso URL e lo stesso header. Se il tuo può farlo dipende dal client e dalla sua versione.

• Claude Desktop e claude.ai aggiungono i server remoti come connettori personalizzati. Se il modulo del connettore ti permette di impostare un header Authorization, usa l’URL e l’header qui sopra. Se offre solo l’accesso tramite OAuth, per ora Gradiently non si può collegare lì.
• ChatGPT e altri assistenti: vale la stessa regola. Dove il client supporta server MCP remoti con un header bearer, collegalo con l’URL e la tua chiave.
• I client configurati con un file JSON accettano spesso la struttura qui sotto, mostrata anche nelle Impostazioni in Collega un client MCP. Controlla la documentazione del tuo client per il formato esatto.

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

Come si comportano gli strumenti

• Ogni strumento restituisce il risultato come testo JSON. Quando qualcosa non va, lo strumento restituisce invece il messaggio di errore dell’API, ad esempio un permesso mancante o un modello sconosciuto.
• Gli strumenti che richiedono un brand accettano un personality facoltativo (il suo id o slug). Se manca, usano il primo brand dello spazio di lavoro.
• Gli strumenti che salvano un design restituiscono il suo link allo Studio, l’indirizzo /studio/<id> del design su gradiently.design.
• Diversi strumenti cercano prima i tuoi brand tramite /api/me, che richiede sia workspaces:read sia designs:read. Per questi strumenti, qui sotto sono elencati entrambi i permessi.
• Una chiamata a uno strumento conta sul limite di frequenza della tua chiave una volta per la richiesta MCP e una volta per ogni richiesta API fatta dallo strumento.

Mark

Una riserva che richiede un pagamento fallisce con un messaggio che indica di completare il checkout; completala in Gradiently. Una chiave non può pagare nulla.

Brand e spazio di lavoro

tone accetta fino a tre valori tra calm, bold, warm, cool, playful, luxe, natural, technical, editorial e nocturnal; una richiesta che ne invia di più viene rifiutata. colours accetta fino a otto colori esadecimali e count chiede da una a otto proposte; oltre questi limiti la richiesta viene rifiutata allo stesso modo. Per adottare una proposta, invia esattamente l’input che l’ha generata insieme alla key della proposta: il server ricrea la proposta da quell’input e non si fida mai di una ricetta inviata dal client.

Progettare

design e create_designs consumano i crediti IA dello spazio di lavoro, come fa il Designer nello Studio. Quando il saldo è troppo basso falliscono con un messaggio che lo dice; ricarica in Impostazioni › Crediti IA. Al massimo due serie per persona vengono eseguite insieme, e una serie finita resta leggibile per circa venti minuti. I design invece restano.

Una composizione indica un size (l’id di un formato predefinito come ig-post, x-post o li-banner, oppure {w, h} in pixel), un layout (statement, editorial, poster, split, stat, quote, list, event o minimal) e i blocks in ordine di lettura, ciascuno con un role come headline, body o cta e il suo 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" }
    ]
  }
}

Modificare ed esportare

wear_mark su un design richiede designs:read e designs:write. Rendere un Mark il Mark di un brand richiede workspaces:read, designs:read e personalities:write, e un Mark riservato da te con una licenza attiva. Indicare il Mark con il suo codice richiede anche marks:read.

render_design accetta width e height da 1 a 4096 pixel e format png o pdf. page parte da 0: il PNG genera per impostazione predefinita la prima pagina e il PDF tutte le pagine. Un PDF mantiene ogni pagina al suo formato nello Studio, quindi il formato che chiedi deve corrispondere. La generazione richiede la stessa licenza di esportazione per il Mark del design richiesta dallo Studio, e non pubblica né modifica mai il design.

Esempi di prompt

• «Trova nel Mercato Mark scuri con del cromo e mostrami i tre più vicini al deep teal.» Usa search_marks.
• «Genera direzioni di brand per Hearth, una panetteria di quartiere, calma e accogliente, e adotta quella con la palette più morbida.» Usa generate_brand e adopt_brand.
• «Forgia un Mark chiamato Night Harbour: un fondo vuoto, dal blu navy all’arancione sodio, un solo livello di grana discreto. Correggi tutto ciò che la verifica segnala, poi salvalo.» Usa make_mark e save_mark.
• «Cambia il titolo del design 4f1c… in “Porte aperte alle sette” e crea copie per una storia Instagram e un post su X.» Usa get_design, update_design_text e resize_copies.
• «Genera il design 4f1c… come PNG da 1080 per 1350 e salvalo in launch.png.» Usa render_design.
• «Crea un poster per la nostra festa del solstizio in terrazza, 21 giugno, dal tramonto all’alba.» Usa design, che richiede workspaces:read.

Il riferimento completo agli endpoint dietro questi strumenti è in Riferimento API. Per tutto il resto, inviaci una richiesta.