MarketExploreTry on
Pricing
Sign inStart
Developers

MCP and AI assistants

Gradiently has an HTTP API and a hosted MCP server. Connect an assistant with OAuth sign-in or a scoped workspace API key.

Updated October 11, 2026

Developer docs

  • Overview
  • MCP and AI assistants
  • API reference
  • API keys and scopes

On this page

Before you connectConnect ChatGPT and ClaudeConnect Claude CodeOther clientsHow the tools behaveMarksBrands and workspaceDesigningEditing and exportingFootage, audio and captionsExample prompts

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://gradiently.design/api/mcp/chatgpt, and Claude and other clients to https://gradiently.design/api/mcp. 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://gradiently.design/api/mcp/chatgpt; Claude: https://gradiently.design/api/mcp 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.

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"

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

Allow long tool calls

Most tools answer in seconds. render_design, inspect_design and export_mark can take up to three minutes, design up to about five, and create_designs with wait up to about four. If your client has a tool timeout setting, raise it to match.

How the tools behave

  • Tools return JSON text. inspect_design also 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 /studio/<id> address on gradiently.design.
  • Several tools first look up your brands through /api/me, which needs both workspaces:read and designs: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.

The scopes to give an assistant

A key made in Settings starts with designs:read, designs:write, marks:read, brand:generate and workspaces:read: enough for every design tool. Add marks:claim to claim Marks, personalities:write to create brands or change their Mark and profile, and members:write to send invitations.

Marks

search_marks

What it does

Searches the public Market by name or code. Returns colours, materials, status and holder.

Inputs

q, tone (dark or light), limit (1 to 120, default 24), all optional

Scopes

marks:read
get_mark

What it does

One Mark and its full recipe.

Inputs

code (a code or an id)

Scopes

marks:read
list_marks

What it does

Marks held for this workspace, with licence state, and your drafts in it.

Inputs

none

Scopes

marks:read
claim_mark

What it does

Claims an available Mark. The key's creator holds it, never the workspace.

Inputs

code

Scopes

marks:read, marks:claim
export_mark

What it does

Renders a Mark on its own as a PNG, up to 4096 px a side.

Inputs

mark, width, height, personality

Scopes

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

What it does

Puts a version back as the draft. The current state is kept as a version first.

Inputs

mark, version

Scopes

brand:generate
update_mark_version

What it does

Renames or stars a version. Starred versions are kept.

Inputs

mark, version, label, starred

Scopes

brand:generate
delete_mark_version

What it does

Deletes a version, never the published one.

Inputs

mark, version

Scopes

brand:generate
ToolWhat it doesInputsScopes
search_marksSearches the public Market by name or code. Returns colours, materials, status and holder.q, tone (dark or light), limit (1 to 120, default 24), all optionalmarks:read
get_markOne Mark and its full recipe.code (a code or an id)marks:read
list_marksMarks held for this workspace, with licence state, and your drafts in it.nonemarks:read
claim_markClaims an available Mark. The key's creator holds it, never the workspace.codemarks:read, marks:claim
export_markRenders a Mark on its own as a PNG, up to 4096 px a side.mark, width, height, personalityworkspaces:read, designs:read, designs:write
restore_mark_versionPuts a version back as the draft. The current state is kept as a version first.mark, versionbrand:generate
update_mark_versionRenames or stars a version. Starred versions are kept.mark, version, label, starredbrand:generate
delete_mark_versionDeletes a version, never the published one.mark, versionbrand:generate

A 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_personalities

What it does

The workspace's brands, with their ids.

Inputs

none

Scopes

workspaces:read, designs:read
create_personality

What it does

Creates a named brand.

Inputs

name

Scopes

personalities:write
get_brand_profile

What it does

What a brand is, who it's for, its voice, dos and don'ts, and fonts.

Inputs

personality

Scopes

workspaces:read, designs:read
update_brand_profile

What it does

Replaces a brand's profile. The Designer reads it before every design.

Inputs

personality, profile

Scopes

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

What it does

You, the workspace's brands with their Mark codes, and the Marks held for it.

Inputs

none

Scopes

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

What it does

The key's workspace and your role in it.

Inputs

cursor

Scopes

workspaces:read
invite_member

What it does

Emails a seven-day invitation to join the workspace.

Inputs

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

Scopes

members:write
ToolWhat it doesInputsScopes
list_personalitiesThe workspace's brands, with their ids.noneworkspaces:read, designs:read
create_personalityCreates a named brand.namepersonalities:write
get_brand_profileWhat a brand is, who it's for, its voice, dos and don'ts, and fonts.personalityworkspaces:read, designs:read
update_brand_profileReplaces a brand's profile. The Designer reads it before every design.personality, profileworkspaces:read, designs:read, personalities:write
my_workspaceYou, the workspace's brands with their Mark codes, and the Marks held for it.noneworkspaces:read, designs:read, marks:read
list_workspacesThe key's workspace and your role in it.cursorworkspaces:read
invite_memberEmails a seven-day invitation to join the workspace.workspaceId, email, role (admin, editor or viewer)members:write

tone 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_guidance

What it does

Reviewed written art direction: the quality bar, drawing capabilities, concept method and critique loop, with deeper topics such as illustration, data and typography. Not templates or model training.

Inputs

purpose, topic

Scopes

any key
draw_design

What it does

Draws an original editable design with your connected AI: text, shapes, its own vector artwork, SVG, native charts, graphics, photos, Mark windows and tables. Redraws only the selected page.

Inputs

drawing, personality, mark, designId, page, title

Scopes

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

What it does

Returns a real PNG image for the assistant to inspect and refine. Smaller sizes are the full page shrunk, as a feed shows it.

Inputs

id, page, maxDimension

Scopes

designs:read
find_icons

What it does

Finds valid built-in icon names.

Inputs

query, limit

Scopes

any key
find_graphics

What it does

Finds Gradiently's original recolourable graphics to use as supporting detail.

Inputs

query, limit

Scopes

any key
find_photos

What it does

Searches licensed photos on Openverse and returns thumbnails the assistant can look at. Says so when a thumbnail is unavailable. Nothing is saved.

Inputs

query, count

Scopes

designs:read
import_photo

What it does

Copies a chosen photo into the workspace's uploads with its attribution, within your upload quota.

Inputs

id

Scopes

designs:write
designAsks 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, selection

Scopes

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

What it does

Makes a set of up to twelve designs from one brief, in the background. Uses Gradiently AI credits.

Inputs

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

Scopes

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

What it does

A set's progress and each design's Studio link once it exists.

Inputs

id

Scopes

designs:read
stop_design_set

What it does

Stops a running set. Designs already drawn stay saved.

Inputs

id

Scopes

designs:write
compose_design

What it does

Lays out your copy with the layout engine and saves it. Returns review issues to fix.

Inputs

composition, personality, designId, title

Scopes

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

What it does

Every size preset with its pixel size.

Inputs

none

Scopes

any key
create_design

What it does

Creates a design from a form (blank by default), a size preset and copy keyed by element id.

Inputs

form, size, copy, look, personality

Scopes

workspaces:read, designs:read, designs:write
ToolWhat it doesInputsScopes
get_design_guidanceReviewed written art direction: the quality bar, drawing capabilities, concept method and critique loop, with deeper topics such as illustration, data and typography. Not templates or model training.purpose, topicany key
draw_designDraws an original editable design with your connected AI: text, shapes, its own vector artwork, SVG, native charts, graphics, photos, Mark windows and tables. Redraws only the selected page.drawing, personality, mark, designId, page, titledesigns:write, workspaces:read, designs:read, marks:read
inspect_designReturns a real PNG image for the assistant to inspect and refine. Smaller sizes are the full page shrunk, as a feed shows it.id, page, maxDimensiondesigns:read
find_iconsFinds valid built-in icon names.query, limitany key
find_graphicsFinds Gradiently's original recolourable graphics to use as supporting detail.query, limitany key
find_photosSearches licensed photos on Openverse and returns thumbnails the assistant can look at. Says so when a thumbnail is unavailable. Nothing is saved.query, countdesigns:read
import_photoCopies a chosen photo into the workspace's uploads with its attribution, within your upload quota.iddesigns:write
designAsks 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.request, personality, size, designId, scope, selectionworkspaces:read, designs:read, designs:write
create_designsMakes a set of up to twelve designs from one brief, in the background. Uses Gradiently AI credits.brief, items (size, brief, title), title, personality, mark, waitworkspaces:read, designs:read, designs:write
get_design_setA set's progress and each design's Studio link once it exists.iddesigns:read
stop_design_setStops a running set. Designs already drawn stay saved.iddesigns:write
compose_designLays out your copy with the layout engine and saves it. Returns review issues to fix.composition, personality, designId, titleworkspaces:read, designs:read, designs:write
list_sizesEvery size preset with its pixel size.noneany key
create_designCreates a design from a form (blank by default), a size preset and copy keyed by element id.form, size, copy, look, personalityworkspaces:read, designs:read, designs:write

design 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.

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 for compose_design. The answer holds the design's id, its Studio link, review issues and the elements it placed.

Editing and exporting

list_designs

What it does

A brand's saved designs with Studio links.

Inputs

personality

Scopes

workspaces:read, designs:read
get_design

What it does

A design's size, pages and every element with its properties. Filter long designs by page, kind, name or text.

Inputs

id, page, kind, name, text

Scopes

designs:read
edit_design

What it does

Changes a design with up to 100 operations, as a person would in the Studio, and saves it.

Inputs

id, ops, page

Scopes

designs:write
update_design_text

What it does

Replaces the words of chosen text elements and keeps the layout.

Inputs

id, text (element id to words)

Scopes

designs:read, designs:write
resize_copies

What it does

Saves copies in up to eight other sizes, reflowed as the Studio does. The original is unchanged.

Inputs

id, sizes

Scopes

designs:read, designs:write
wear_mark

What it does

Puts a Mark on one design, or makes it a brand's Mark for new designs.

Inputs

mark, and design or personality

Scopes

see below
render_design

What it does

Renders a saved design to PNG or PDF with the Studio's engine. Returns the file as base64.

Inputs

id, width, height, format, page

Scopes

designs:read
export_design_link

What it does

Publishes a view link, /d/<id>, that anyone with it can open.

Inputs

id

Scopes

designs:write
ToolWhat it doesInputsScopes
list_designsA brand's saved designs with Studio links.personalityworkspaces:read, designs:read
get_designA design's size, pages and every element with its properties. Filter long designs by page, kind, name or text.id, page, kind, name, textdesigns:read
edit_designChanges a design with up to 100 operations, as a person would in the Studio, and saves it.id, ops, pagedesigns:write
update_design_textReplaces the words of chosen text elements and keeps the layout.id, text (element id to words)designs:read, designs:write
resize_copiesSaves copies in up to eight other sizes, reflowed as the Studio does. The original is unchanged.id, sizesdesigns:read, designs:write
wear_markPuts a Mark on one design, or makes it a brand's Mark for new designs.mark, and design or personalitysee below
render_designRenders a saved design to PNG or PDF with the Studio's engine. Returns the file as base64.id, width, height, format, pagedesigns:read
export_design_linkPublishes a view link, /d/<id>, that anyone with it can open.iddesigns:write

wear_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_text and resize_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 needs workspaces:read.

The whole reference for the endpoints behind these tools is on API reference. For anything else, send us a request.

Need a hand?

Send us a request with the topic API and MCP, and a person will reply.

Send a request

Find the look that’s only yours.

Every Mark is a living background with one owner. Try an unclaimed Mark, and claim yours when it feels right.

Start designingSee the launch offer

Marks left to claim

50of 1,000

950 claimed so farFind yours

Check a certificate

Type a certificate number or a Mark’s code to see who owns it.

Works with ChatGPT and Claude

Ask your AI for a design. It makes it in your Mark, ready to edit.

ChatGPTClaude
How to connect

Product

  • Market
  • Explore
  • Pricing
  • Launch packs
  • Certificates

Learn

  • Field Guide
  • Help centre
  • What’s new

Developers

  • Overview
  • ChatGPT and Claude
  • API reference
  • API keys

Company

  • About
  • Contact us
  • Sign in

Legal

  • Terms
  • Privacy
  • Refunds
  • Mark protection
  • Cookies
  • All policies
Move through the letters. Each one wears a real Mark.Touch a letter to see its Mark.One name. Ten Marks inside it.
© 2026 Gradiently