MercatoEsploraProvalo
Prezzi
AccediInizia
Sviluppatori

MCP e assistenti IA

Gradiently offre un’API HTTP e un server MCP ospitato. Collega un assistente con OAuth o una chiave API limitata a uno spazio.

Aggiornata il 11 ottobre 2026

Documentazione per sviluppatori

  • Panoramica
  • MCP e assistenti IA
  • Riferimento API
  • Chiavi API e permessi

In questa pagina

Prima di collegartiCollegare ChatGPT e ClaudeCollegare Claude CodeAltri clientCome si comportano gli strumentiMarkBrand e spazio di lavoroProgettareModificare ed esportareVideo, audio e sottotitoliEsempi di prompt

Il server accetta token di accesso OAuth e chiavi API dello spazio. Entrambi usano gli stessi permessi, licenze, crediti e limiti. Il Model Context Protocol è uno standard aperto per dare strumenti agli assistenti IA. Gradiently gestisce un server MCP ospitato. ChatGPT si collega a https://gradiently.design/api/mcp/chatgpt, Claude e gli altri client a 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.
  • Un client con chiave API invia Authorization: Bearer gr_live_…. ChatGPT e Claude inviano il token OAuth dopo l’accesso.
  • 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 token di accesso OAuth e chiavi API dello spazio. Entrambi usano gli stessi permessi, licenze, crediti e limiti.

Collegare ChatGPT e Claude

Aggiungi un connettore personalizzato con ChatGPT: https://gradiently.design/api/mcp/chatgpt; Claude: https://gradiently.design/api/mcp e scegli l’accesso OAuth. Accedi a Gradiently, scegli uno spazio e controlla i permessi. Solo i proprietari e gli amministratori possono collegare un assistente.

I collegamenti scadono dopo un’ora e si rinnovano automaticamente per un massimo di 30 giorni. Revoca un collegamento in Impostazioni › API e agenti per interrompere subito accesso e rinnovo.

Un collegamento personalizzato e una presenza nella directory pubblica sono distinti. La pubblicazione nella directory richiede la verifica e l’approvazione di OpenAI o Anthropic.

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.

bash
# Paste your key when asked. It stays hidden and out of your shell history.
read -rs GRADIENTLY_API_KEY && export GRADIENTLY_API_KEY

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.

  • 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.
json
{
  "mcpServers": {
    "gradiently": {
      "url": "https://gradiently.design/api/mcp",
      "headers": { "Authorization": "Bearer gr_live_…" }
    }
  }
}

Consenti chiamate lunghe agli strumenti

La maggior parte degli strumenti risponde in pochi secondi. render_design, inspect_design ed export_mark possono richiedere fino a tre minuti, design fino a circa cinque, e create_designs con wait fino a circa quattro. Se il tuo client ha un’impostazione di timeout per gli strumenti, alzala di conseguenza.

Come si comportano gli strumenti

  • Gli strumenti restituiscono testo JSON. inspect_design restituisce anche un’immagine PNG. In caso di errore viene restituito un messaggio.
  • 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.

I permessi da dare a un assistente

Una chiave creata nelle Impostazioni parte con designs:read, designs:write, marks:read, brand:generate e workspaces:read: abbastanza per ogni strumento di design. Aggiungi marks:claim per riservare Mark, personalities:write per creare brand o cambiarne il Mark e il profilo, e members:write per inviare inviti.

Mark

search_marks

Cosa fa

Cerca nel Mercato pubblico per nome o codice. Restituisce colori, materiali, stato e titolare.

Input

q, tone (dark o light), limit (da 1 a 120, 24 se omesso), tutti facoltativi

Permessi

marks:read
get_mark

Cosa fa

Un Mark e la sua ricetta completa.

Input

code (un codice o un id)

Permessi

marks:read
list_marks

Cosa fa

I Mark riservati per questo spazio di lavoro, con lo stato della licenza, e le tue bozze al suo interno.

Input

nessuno

Permessi

marks:read
claim_mark

Cosa fa

Riserva un Mark disponibile. Il titolare è chi ha creato la chiave, mai lo spazio di lavoro.

Input

code

Permessi

marks:read, marks:claim
export_mark

Cosa fa

Genera un Mark da solo come PNG, fino a 4096 px per lato.

Input

mark, width, height, personality

Permessi

workspaces:read, designs:read, designs:write
restore_mark_version

Cosa fa

Ripristina una versione come bozza. Lo stato attuale viene prima conservato come versione.

Input

mark, version

Permessi

brand:generate
update_mark_version

Cosa fa

Rinomina una versione o la segna con una stella. Le versioni con stella vengono conservate.

Input

mark, version, label, starred

Permessi

brand:generate
delete_mark_version

Cosa fa

Elimina una versione, mai quella pubblicata.

Input

mark, version

Permessi

brand:generate
StrumentoCosa faInputPermessi
search_marksCerca nel Mercato pubblico per nome o codice. Restituisce colori, materiali, stato e titolare.q, tone (dark o light), limit (da 1 a 120, 24 se omesso), tutti facoltativimarks:read
get_markUn Mark e la sua ricetta completa.code (un codice o un id)marks:read
list_marksI Mark riservati per questo spazio di lavoro, con lo stato della licenza, e le tue bozze al suo interno.nessunomarks:read
claim_markRiserva un Mark disponibile. Il titolare è chi ha creato la chiave, mai lo spazio di lavoro.codemarks:read, marks:claim
export_markGenera un Mark da solo come PNG, fino a 4096 px per lato.mark, width, height, personalityworkspaces:read, designs:read, designs:write
restore_mark_versionRipristina una versione come bozza. Lo stato attuale viene prima conservato come versione.mark, versionbrand:generate
update_mark_versionRinomina una versione o la segna con una stella. Le versioni con stella vengono conservate.mark, version, label, starredbrand:generate
delete_mark_versionElimina una versione, mai quella pubblicata.mark, versionbrand:generate

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

list_personalities

Cosa fa

I brand dello spazio di lavoro, con i loro id.

Input

nessuno

Permessi

workspaces:read, designs:read
create_personality

Cosa fa

Crea un brand con un nome.

Input

name

Permessi

personalities:write
get_brand_profile

Cosa fa

Cos’è un brand, a chi si rivolge, il suo tono di voce, cosa fare e cosa evitare, e i font.

Input

personality

Permessi

workspaces:read, designs:read
update_brand_profile

Cosa fa

Sostituisce il profilo di un brand. Il Designer lo legge prima di ogni design.

Input

personality, profile

Permessi

workspaces:read, designs:read, personalities:write
my_workspace

Cosa fa

Tu, i brand dello spazio di lavoro con i codici dei loro Mark, e i Mark riservati per esso.

Input

nessuno

Permessi

workspaces:read, designs:read, marks:read
list_workspaces

Cosa fa

Lo spazio di lavoro della chiave e il tuo ruolo al suo interno.

Input

cursor

Permessi

workspaces:read
invite_member

Cosa fa

Invia via email un invito di sette giorni per entrare nello spazio di lavoro.

Input

workspaceId, email, role (admin, editor o viewer)

Permessi

members:write
StrumentoCosa faInputPermessi
list_personalitiesI brand dello spazio di lavoro, con i loro id.nessunoworkspaces:read, designs:read
create_personalityCrea un brand con un nome.namepersonalities:write
get_brand_profileCos’è un brand, a chi si rivolge, il suo tono di voce, cosa fare e cosa evitare, e i font.personalityworkspaces:read, designs:read
update_brand_profileSostituisce il profilo di un brand. Il Designer lo legge prima di ogni design.personality, profileworkspaces:read, designs:read, personalities:write
my_workspaceTu, i brand dello spazio di lavoro con i codici dei loro Mark, e i Mark riservati per esso.nessunoworkspaces:read, designs:read, marks:read
list_workspacesLo spazio di lavoro della chiave e il tuo ruolo al suo interno.cursorworkspaces:read
invite_memberInvia via email un invito di sette giorni per entrare nello spazio di lavoro.workspaceId, email, role (admin, editor o viewer)members:write

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

Per un lavoro originale, chiedi alla tua IA collegata di leggere il profilo del brand e get_design_guidance, creare con draw_design, esaminare l’immagine reale con inspect_design e perfezionare con edit_design. Disegno, modifica e ispezione diretti non consumano crediti IA di Gradiently. Restano validi i limiti del tuo provider e le autorizzazioni di account ed esportazione. Un disegno può contenere illustrazioni vettoriali proprie dell’host, SVG ripulito, grafici nativi, grafiche della libreria e foto con licenza; tutto resta modificabile nello Studio. La ricerca e l’importazione di foto accedono a Openverse, un catalogo esterno.

get_design_guidance

Cosa fa

Direzione artistica scritta e revisionata: il livello di qualità, le possibilità di disegno, il metodo di concept e il ciclo di revisione, con approfondimenti come illustrazione, dati e tipografia. Non sono modelli da copiare né addestramento di modelli.

Input

purpose, topic

Permessi

qualsiasi chiave
draw_design

Cosa fa

Disegna un design originale e modificabile con la tua IA collegata: testo, forme, illustrazioni vettoriali proprie, SVG, grafici nativi, grafiche, foto, finestre della Mark e tabelle. Ridisegna solo la pagina selezionata.

Input

drawing, personality, mark, designId, page, title

Permessi

designs:write, workspaces:read, designs:read, marks:read
inspect_design

Cosa fa

Restituisce un’immagine PNG reale che l’assistente può esaminare e migliorare. Le dimensioni più piccole sono l’intera pagina ridotta, come la mostra un feed.

Input

id, page, maxDimension

Permessi

designs:read
find_icons

Cosa fa

Trova nomi validi delle icone integrate.

Input

query, limit

Permessi

qualsiasi chiave
find_graphics

Cosa fa

Trova le grafiche originali di Gradiently, ricolorabili, da usare come dettagli di supporto.

Input

query, limit

Permessi

qualsiasi chiave
find_photos

Cosa fa

Cerca foto con licenza su Openverse e restituisce miniature che l’assistente può guardare. Lo segnala quando una miniatura non è disponibile. Non viene salvato nulla.

Input

query, count

Permessi

designs:read
import_photo

Cosa fa

Copia la foto scelta nei caricamenti dello spazio di lavoro con la sua attribuzione, entro la tua quota di caricamento.

Input

id

Permessi

designs:write
designChiede al Designer di Gradiently di creare un design, o di modificarne uno, a partire da una richiesta a parole. Legge il profilo del brand e il Mark, progetta, verifica e salva. Utilizza crediti IA di Gradiently.

Input

request, personality, size, designId, scope, selection

Permessi

workspaces:read, designs:read, designs:write
create_designs

Cosa fa

Crea in background una serie di fino a dodici design da un solo brief. Utilizza crediti IA di Gradiently.

Input

brief, items (size, brief, title), title, personality, mark, wait

Permessi

workspaces:read, designs:read, designs:write
get_design_set

Cosa fa

L’avanzamento di una serie e il link allo Studio di ogni design appena esiste.

Input

id

Permessi

designs:read
stop_design_set

Cosa fa

Ferma una serie in corso. I design già disegnati restano salvati.

Input

id

Permessi

designs:write
compose_design

Cosa fa

Impagina i tuoi testi con il motore di impaginazione e salva il risultato. Restituisce i problemi da correggere emersi dalla verifica.

Input

composition, personality, designId, title

Permessi

workspaces:read, designs:read, designs:write
list_sizes

Cosa fa

Ogni formato predefinito, con la sua dimensione in pixel.

Input

nessuno

Permessi

qualsiasi chiave
create_design

Cosa fa

Crea un design da una forma di base (vuota per impostazione predefinita), un formato predefinito e testi associati agli id degli elementi.

Input

form, size, copy, look, personality

Permessi

workspaces:read, designs:read, designs:write
StrumentoCosa faInputPermessi
get_design_guidanceDirezione artistica scritta e revisionata: il livello di qualità, le possibilità di disegno, il metodo di concept e il ciclo di revisione, con approfondimenti come illustrazione, dati e tipografia. Non sono modelli da copiare né addestramento di modelli.purpose, topicqualsiasi chiave
draw_designDisegna un design originale e modificabile con la tua IA collegata: testo, forme, illustrazioni vettoriali proprie, SVG, grafici nativi, grafiche, foto, finestre della Mark e tabelle. Ridisegna solo la pagina selezionata.drawing, personality, mark, designId, page, titledesigns:write, workspaces:read, designs:read, marks:read
inspect_designRestituisce un’immagine PNG reale che l’assistente può esaminare e migliorare. Le dimensioni più piccole sono l’intera pagina ridotta, come la mostra un feed.id, page, maxDimensiondesigns:read
find_iconsTrova nomi validi delle icone integrate.query, limitqualsiasi chiave
find_graphicsTrova le grafiche originali di Gradiently, ricolorabili, da usare come dettagli di supporto.query, limitqualsiasi chiave
find_photosCerca foto con licenza su Openverse e restituisce miniature che l’assistente può guardare. Lo segnala quando una miniatura non è disponibile. Non viene salvato nulla.query, countdesigns:read
import_photoCopia la foto scelta nei caricamenti dello spazio di lavoro con la sua attribuzione, entro la tua quota di caricamento.iddesigns:write
designChiede al Designer di Gradiently di creare un design, o di modificarne uno, a partire da una richiesta a parole. Legge il profilo del brand e il Mark, progetta, verifica e salva. Utilizza crediti IA di Gradiently.request, personality, size, designId, scope, selectionworkspaces:read, designs:read, designs:write
create_designsCrea in background una serie di fino a dodici design da un solo brief. Utilizza crediti IA di Gradiently.brief, items (size, brief, title), title, personality, mark, waitworkspaces:read, designs:read, designs:write
get_design_setL’avanzamento di una serie e il link allo Studio di ogni design appena esiste.iddesigns:read
stop_design_setFerma una serie in corso. I design già disegnati restano salvati.iddesigns:write
compose_designImpagina i tuoi testi con il motore di impaginazione e salva il risultato. Restituisce i problemi da correggere emersi dalla verifica.composition, personality, designId, titleworkspaces:read, designs:read, designs:write
list_sizesOgni formato predefinito, con la sua dimensione in pixel.nessunoqualsiasi chiave
create_designCrea un design da una forma di base (vuota per impostazione predefinita), un formato predefinito e testi associati agli id degli elementi.form, size, copy, look, personalityworkspaces:read, designs:read, designs:write

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.

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" }
    ]
  }
}
Input per compose_design. La risposta contiene l’id del design, il suo link allo Studio, i problemi emersi dalla verifica e gli elementi posizionati.

Modificare ed esportare

list_designs

Cosa fa

I design salvati di un brand con i link allo Studio.

Input

personality

Permessi

workspaces:read, designs:read
get_design

Cosa fa

Il formato di un design, le pagine e ogni elemento con le sue proprietà. Filtra i design lunghi per pagina, tipo, nome o testo.

Input

id, page, kind, name, text

Permessi

designs:read
edit_design

Cosa fa

Modifica un design con fino a 100 operazioni, come farebbe una persona nello Studio, e lo salva.

Input

id, ops, page

Permessi

designs:write
update_design_text

Cosa fa

Sostituisce le parole degli elementi di testo scelti e mantiene l’impaginazione.

Input

id, text (dall’id dell’elemento alle parole)

Permessi

designs:read, designs:write
resize_copies

Cosa fa

Salva copie in fino a otto altri formati, reimpaginate come fa lo Studio. L’originale non cambia.

Input

id, sizes

Permessi

designs:read, designs:write
wear_mark

Cosa fa

Mette un Mark su un design, oppure lo rende il Mark di un brand per i nuovi design.

Input

mark, e design o personality

Permessi

vedi sotto
render_design

Cosa fa

Genera un design salvato in PNG o PDF con il motore dello Studio. Restituisce il file in base64.

Input

id, width, height, format, page

Permessi

designs:read
export_design_link

Cosa fa

Pubblica un link di visualizzazione, /d/<id>, che chiunque lo abbia può aprire.

Input

id

Permessi

designs:write
StrumentoCosa faInputPermessi
list_designsI design salvati di un brand con i link allo Studio.personalityworkspaces:read, designs:read
get_designIl formato di un design, le pagine e ogni elemento con le sue proprietà. Filtra i design lunghi per pagina, tipo, nome o testo.id, page, kind, name, textdesigns:read
edit_designModifica un design con fino a 100 operazioni, come farebbe una persona nello Studio, e lo salva.id, ops, pagedesigns:write
update_design_textSostituisce le parole degli elementi di testo scelti e mantiene l’impaginazione.id, text (dall’id dell’elemento alle parole)designs:read, designs:write
resize_copiesSalva copie in fino a otto altri formati, reimpaginate come fa lo Studio. L’originale non cambia.id, sizesdesigns:read, designs:write
wear_markMette un Mark su un design, oppure lo rende il Mark di un brand per i nuovi design.mark, e design o personalityvedi sotto
render_designGenera un design salvato in PNG o PDF con il motore dello Studio. Restituisce il file in base64.id, width, height, format, pagedesigns:read
export_design_linkPubblica un link di visualizzazione, /d/<id>, che chiunque lo abbia può aprire.iddesigns:write

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.

Video, audio e sottotitoli

Usa find_uploads per trovare riferimenti a sorgenti autorizzate, poi edit_design con add_video, update_video, split_video, add_audio, update_audio, split_audio, remove_audio, set_element_timing, set_captions o remove_captions. Non inventare mai la durata di una sorgente. I tagli video e i tempi degli elementi usano i secondi della pagina; gli inizi e i tagli audio e i sottotitoli usano i secondi dell’intero documento. L’audio non prolunga le scene. I sottotitoli accettano voci con tempi o contenuti SRT/WebVTT; la trascrizione automatica non è disponibile. get_design restituisce la sequenza completa e le tracce. export_captions restituisce il contenuto SRT/WebVTT in parti di massimo 100 sottotitoli e 48.000 caratteri; usa nextOffset per la parte successiva.

Esempi di prompt

  • «Trova nel Mercato Mark scuri con del cromo e mostrami i tre più vicini al deep teal.» Usa search_marks.
  • «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.

Ti serve una mano?

Inviaci una richiesta con l’argomento API e MCP, e ti risponderà una persona.

Invia una richiesta

Trova lo stile che è solo tuo.

Ogni Mark è uno sfondo vivo con un solo proprietario. Prova un Mark ancora disponibile e riserva il tuo quando ti senti pronto.

Inizia a progettareVedi l’offerta di lancio

Mark ancora da riservare

50su 1000

950 riservati finoraTrova il tuo

Verifica un certificato

Scrivi il numero di un certificato o il codice di un Mark per scoprire di chi è.

Funziona con ChatGPT e Claude

Chiedi un design alla tua AI. Lo crea nel tuo Mark, pronto da modificare.

ChatGPTClaude
Come collegarla

Prodotto

  • Mercato
  • Esplora
  • Prezzi
  • Pacchetti di lancio
  • Certificati

Scopri

  • Guida pratica
  • Centro assistenza
  • Novità

Sviluppatori

  • Panoramica
  • ChatGPT e Claude
  • Riferimento API
  • Chiavi API

Azienda

  • Chi siamo
  • Contattaci
  • Accedi

Note legali

  • Termini
  • Privacy
  • Rimborsi
  • Protezione dei Mark
  • Cookie
  • Tutte le policy
Passa sopra le lettere. Ognuna indossa un vero Mark.Tocca una lettera per vedere il suo Mark.Un nome. Dieci Mark al suo interno.
© 2026 Gradiently