MCP and AI assistants

The Model Context Protocol is an open standard for giving AI assistants tools. Gradiently runs a hosted MCP server at 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.
• Every request to the server must carry the key as Authorization: Bearer gr_live_…, including the first one. Without it the server answers 401.
• The server speaks Streamable HTTP, stateless, with JSON responses. It needs no session and has no separate event stream to open.
• The server accepts API keys only. It does not offer an OAuth sign-in.

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.

export GRADIENTLY_API_KEY="gr_live_…"

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.

• Claude Desktop and claude.ai add remote servers as custom connectors. If the connector form lets you set an Authorization header, use the URL and header above. If it offers only an OAuth sign-in, Gradiently can't be connected there yet.
• ChatGPT and other assistants: the same rule. Where the client supports remote MCP servers with a bearer header, connect it with the URL and your key.
• 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

• Each tool returns its result as JSON text. When something fails, the tool returns the API's error message instead, such as a missing scope or an unknown template.
• 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.

Marks

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

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

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.

{
  "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" }
    ]
  }
}

Editing and exporting

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.

Example prompts

• "Find dark Marks in the Market with chrome in them and show me the three closest to deep teal." Uses search_marks.
• "Generate brand directions for Hearth, a neighbourhood bakery, calm and warm, and adopt the one with the softest palette." Uses generate_brand and adopt_brand.
• "Forge a Mark called Night Harbour: a void ground, navy to sodium orange, one quiet grain layer. Fix anything the review flags, then save it." Uses make_mark and save_mark.
• "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.