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://, Claude e gli altri client a https://. 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://; Claude: https:// 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.
# 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.
{
"mcpServers": {
"gradiently": {
"url": "https://gradiently.design/api/mcp",
"headers": { "Authorization": "Bearer gr_live_…" }
}
}
}Come si comportano gli strumenti
- Gli strumenti restituiscono testo JSON.
inspect_designrestituisce anche un’immagine PNG. In caso di errore viene restituito un messaggio. - Gli strumenti che richiedono un brand accettano un
personalityfacoltativo (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
/del design su gradiently.design.studio/ <id> - Diversi strumenti cercano prima i tuoi brand tramite
/, che richiede siaapi/ me workspaces:readsiadesigns: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
search_marksCosa fa
Input
q, tone (dark o light), limit (da 1 a 120, 24 se omesso), tutti facoltativiPermessi
marks:readget_markCosa fa
Input
code (un codice o un id)Permessi
marks:readlist_marksCosa fa
Input
Permessi
marks:readclaim_markCosa fa
Input
codePermessi
marks:read, marks:claimexport_markCosa fa
Input
mark, width, height, personalityPermessi
workspaces:read, designs:read, designs:writerestore_mark_versionCosa fa
Input
mark, versionPermessi
brand:generateupdate_mark_versionCosa fa
Input
mark, version, label, starredPermessi
brand:generatedelete_mark_versionCosa fa
Input
mark, versionPermessi
brand:generateUna 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_personalitiesCosa fa
Input
Permessi
workspaces:read, designs:readcreate_personalityCosa fa
Input
namePermessi
personalities:writeget_brand_profileCosa fa
Input
personalityPermessi
workspaces:read, designs:readupdate_brand_profileCosa fa
Input
personality, profilePermessi
workspaces:read, designs:read, personalities:writemy_workspaceCosa fa
Input
Permessi
workspaces:read, designs:read, marks:readlist_workspacesCosa fa
Input
cursorPermessi
workspaces:readinvite_memberCosa fa
Input
workspaceId, email, role (admin, editor o viewer)Permessi
members:writetone 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_guidanceCosa fa
Input
purpose, topicPermessi
draw_designCosa fa
Input
drawing, personality, mark, designId, page, titlePermessi
designs:write, workspaces:read, designs:read, marks:readinspect_designCosa fa
Input
id, page, maxDimensionPermessi
designs:readfind_iconsCosa fa
Input
query, limitPermessi
find_graphicsCosa fa
Input
query, limitPermessi
find_photosCosa fa
Input
query, countPermessi
designs:readimport_photoCosa fa
Input
idPermessi
designs:writedesignChiede 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, selectionPermessi
workspaces:read, designs:read, designs:writecreate_designsCosa fa
Input
brief, items (size, brief, title), title, personality, mark, waitPermessi
workspaces:read, designs:read, designs:writeget_design_setCosa fa
Input
idPermessi
designs:readstop_design_setCosa fa
Input
idPermessi
designs:writecompose_designCosa fa
Input
composition, personality, designId, titlePermessi
workspaces:read, designs:read, designs:writelist_sizesCosa fa
Input
Permessi
create_designCosa fa
Input
form, size, copy, look, personalityPermessi
workspaces:read, designs:read, designs:writedesign 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" }
]
}
}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_designsCosa fa
Input
personalityPermessi
workspaces:read, designs:readget_designCosa fa
Input
id, page, kind, name, textPermessi
designs:readedit_designCosa fa
Input
id, ops, pagePermessi
designs:writeupdate_design_textCosa fa
Input
id, text (dall’id dell’elemento alle parole)Permessi
designs:read, designs:writeresize_copiesCosa fa
Input
id, sizesPermessi
designs:read, designs:writewear_markCosa fa
Input
mark, e design o personalityPermessi
render_designCosa fa
Input
id, width, height, format, pagePermessi
designs:readexport_design_linkCosa fa
/ d/ <id>, che chiunque lo abbia può aprire.Input
idPermessi
designs:writewear_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_texteresize_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 richiedeworkspaces:read.
Il riferimento completo agli endpoint dietro questi strumenti è in Riferimento API. Per tutto il resto, inviaci una richiesta.