The server accepts OAuth access tokens and workspace API keys. Both use the same permissions, licences, credits and limits. The Model Context Protocol is an open standard for giving AI assistants tools. Gradiently runs a hosted MCP server. ChatGPT connects to https://, and Claude and other clients to https://. Connect it once with an API key, and your assistant can call Gradiently's tools while you talk to it. Each tool makes the same API requests your own code would, so it has the same permissions, licences, credits and limits.
Before you connect
- Create a key in Settings › API and agents (see API keys and scopes). The key decides which workspace the assistant works in and which tools will work.
- An API-key client sends
Authorization: Bearer gr_live_…. ChatGPT and Claude send the OAuth token after sign-in. - The server speaks Streamable HTTP, stateless, with JSON responses. It needs no session and has no separate event stream to open.
- The server accepts OAuth access tokens and workspace API keys. Both use the same permissions, licences, credits and limits.
Connect ChatGPT and Claude
Add a custom connector with ChatGPT: https://; Claude: https:// and choose OAuth sign-in. Sign in to Gradiently, choose a workspace and review its permissions. Only workspace owners and admins can connect an assistant.
Connections expire after one hour and renew automatically for up to 30 days. Revoke a connection in Settings › API and agents to stop both its access and renewal immediately.
A custom connection and a public directory listing are separate. Directory availability requires review and approval by OpenAI or Anthropic.
Connect Claude Code
Add Gradiently as a remote server over HTTP, with your key in the header. Keep the key in an environment variable so it never lands in your shell history or a committed file.
# 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"Start a new Claude Code session and ask it to list Gradiently's tools to check the connection. If it reports an authentication error, the key was mistyped, revoked, or its creator is no longer an owner or admin of the workspace.
Other clients
Any client that can add a remote MCP server over Streamable HTTP and send a custom request header can use Gradiently with the same URL and header. Whether yours can depends on the client and its version.
- Clients configured with a JSON file often accept the shape below, which is also shown in Settings under Connect an MCP client. Check your client's documentation for its exact format.
{
"mcpServers": {
"gradiently": {
"url": "https://gradiently.design/api/mcp",
"headers": { "Authorization": "Bearer gr_live_…" }
}
}
}How the tools behave
- Tools return JSON text.
inspect_designalso returns a PNG image. Failures return an error message. - Tools that need a brand take an optional
personality(its id or slug). Without one they use the workspace's first brand. - Tools that save a design return its Studio link, the design's
/address on gradiently.design.studio/ <id> - Several tools first look up your brands through
/, which needs bothapi/ me workspaces:readanddesigns:read. Those tools list both scopes below. - A tool call counts against your key's rate limit once for the MCP request and once for each API request the tool makes.
Marks
search_marksWhat it does
Inputs
q, tone (dark or light), limit (1 to 120, default 24), all optionalScopes
marks:readget_markWhat it does
Inputs
code (a code or an id)Scopes
marks:readlist_marksWhat it does
Inputs
Scopes
marks:readclaim_markWhat it does
Inputs
codeScopes
marks:read, marks:claimexport_markWhat it does
Inputs
mark, width, height, personalityScopes
workspaces:read, designs:read, designs:writerestore_mark_versionWhat it does
Inputs
mark, versionScopes
brand:generateupdate_mark_versionWhat it does
Inputs
mark, version, label, starredScopes
brand:generatedelete_mark_versionWhat it does
Inputs
mark, versionScopes
brand:generateA claim that needs payment fails with a message that it needs checkout; finish it in Gradiently. A key can't pay for anything.
Brands and workspace
list_personalitiesWhat it does
Inputs
Scopes
workspaces:read, designs:readcreate_personalityWhat it does
Inputs
nameScopes
personalities:writeget_brand_profileWhat it does
Inputs
personalityScopes
workspaces:read, designs:readupdate_brand_profileWhat it does
Inputs
personality, profileScopes
workspaces:read, designs:read, personalities:writemy_workspaceWhat it does
Inputs
Scopes
workspaces:read, designs:read, marks:readlist_workspacesWhat it does
Inputs
cursorScopes
workspaces:readinvite_memberWhat it does
Inputs
workspaceId, email, role (admin, editor or viewer)Scopes
members:writetone takes up to three of calm, bold, warm, cool, playful, luxe, natural, technical, editorial and nocturnal; a request with more is rejected. colours takes up to eight hex colours and count asks for one to eight candidates; more of either is rejected too. To adopt a candidate, send exactly the input that generated it with the candidate's key: the server makes the candidate again from that input and never trusts a recipe sent by the client.
Designing
For original work, ask your connected AI to read the brand and get_design_guidance, author with draw_design, inspect the real image with inspect_design, and refine with edit_design. Direct drawing, editing and inspection use no Gradiently AI credits. Your provider usage and account/export permissions still apply. Drawings can hold the host's own vector artwork, sanitised SVG, native charts, library graphics and licensed photos; everything stays editable in the Studio. Photo search and import reach Openverse, an external catalogue.
get_design_guidanceWhat it does
Inputs
purpose, topicScopes
draw_designWhat it does
Inputs
drawing, personality, mark, designId, page, titleScopes
designs:write, workspaces:read, designs:read, marks:readinspect_designWhat it does
Inputs
id, page, maxDimensionScopes
designs:readfind_iconsWhat it does
Inputs
query, limitScopes
find_graphicsWhat it does
Inputs
query, limitScopes
find_photosWhat it does
Inputs
query, countScopes
designs:readimport_photoWhat it does
Inputs
idScopes
designs:writedesignAsks Gradiently's own Designer to make a design, or change one, from a plain request. It reads the brand profile and Mark, designs, reviews and saves. Uses Gradiently AI credits.Inputs
request, personality, size, designId, scope, selectionScopes
workspaces:read, designs:read, designs:writecreate_designsWhat it does
Inputs
brief, items (size, brief, title), title, personality, mark, waitScopes
workspaces:read, designs:read, designs:writeget_design_setWhat it does
Inputs
idScopes
designs:readstop_design_setWhat it does
Inputs
idScopes
designs:writecompose_designWhat it does
Inputs
composition, personality, designId, titleScopes
workspaces:read, designs:read, designs:writelist_sizesWhat it does
Inputs
Scopes
create_designWhat it does
Inputs
form, size, copy, look, personalityScopes
workspaces:read, designs:read, designs:writedesign and create_designs spend the workspace's AI credits, as the Designer does in the Studio. When the balance is too low they fail with a message saying so; top up in Settings › AI credits. At most two sets run at once per person, and a finished set stays readable for about twenty minutes. The designs themselves stay.
A composition names a size (a preset id such as ig-post, x-post or li-banner, or {w, h} in pixels), a layout (statement, editorial, poster, split, stat, quote, list, event or minimal) and blocks in reading order, each with a role such as headline, body or cta and its 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. The answer holds the design's id, its Studio link, review issues and the elements it placed.Editing and exporting
list_designsWhat it does
Inputs
personalityScopes
workspaces:read, designs:readget_designWhat it does
Inputs
id, page, kind, name, textScopes
designs:readedit_designWhat it does
Inputs
id, ops, pageScopes
designs:writeupdate_design_textWhat it does
Inputs
id, text (element id to words)Scopes
designs:read, designs:writeresize_copiesWhat it does
Inputs
id, sizesScopes
designs:read, designs:writewear_markWhat it does
Inputs
mark, and design or personalityScopes
render_designWhat it does
Inputs
id, width, height, format, pageScopes
designs:readexport_design_linkWhat it does
/ d/ <id>, that anyone with it can open.Inputs
idScopes
designs:writewear_mark on a design needs designs:read and designs:write. Making a Mark a brand's Mark needs workspaces:read, designs:read and personalities:write, and a Mark you hold with an active licence. Naming the Mark by its code also needs marks:read.
render_design takes width and height from 1 to 4096 pixels and format png or pdf. page counts from 0: PNG renders the first page by default and PDF every page. A PDF keeps each page at its Studio size, so the size you ask for must match. Rendering needs the same export licence for the design's Mark as the Studio, and it never publishes or changes the design.
Footage, audio and captions
Use find_uploads to discover trusted source references, then edit_design with add_video, update_video, split_video, add_audio, update_audio, split_audio, remove_audio, set_element_timing, set_captions or remove_captions. Never guess source duration. Footage splits and element timing use page-local seconds; audio starts, audio splits and caption cues use document-global seconds. Audio does not extend scenes. Captions accept supplied cue arrays or SRT/WebVTT content; automatic transcription is unavailable. get_design returns the complete scene clock and tracks. export_captions returns SRT/WebVTT file content in parts of at most 100 cues and 48,000 characters; follow nextOffset for the next part.
Example prompts
- "Find dark Marks in the Market with chrome in them and show me the three closest to deep teal." Uses
search_marks. - "Change the headline on design 4f1c… to 'Doors open at seven' and make copies for an Instagram story and an X post." Uses
get_design,update_design_textandresize_copies. - "Render design 4f1c… as a 1080 by 1350 PNG and save it to launch.png." Uses
render_design. - "Make a poster for our rooftop solstice party, 21 June, sunset to sunrise." Uses
design, which needsworkspaces:read.
The whole reference for the endpoints behind these tools is on API reference. For anything else, send us a request.