Gradiently for developers

Build with Gradiently

Use the API and Gradiently’s MCP server to let your code, or your AI assistant, search Marks and make designs that open in the Studio.

Updated October 1, 2026

Gradiently gives you two ways in. The MCP server lets an AI assistant such as Claude Code use Gradiently's tools while you talk to it. The API lets your own code call the same endpoints directly. Both authenticate with an API key that belongs to one workspace, and both go through the same checks as the app: workspace roles, Mark licences, AI credits and rate limits.

What you can do

  • Search the Market and read any public Mark's full recipe.
  • Generate brand candidates from a name and a description, then adopt one: a draft Mark, a brand and three starter designs in one step.
  • Make designs with Gradiently's own Designer, with the layout engine, or from a template, and get back a link that opens in the Studio.
  • Edit saved designs by element, change their words, save copies in other sizes and put a different Mark on them.
  • Render a saved design to PNG or PDF, or publish a view link for it.
  • Forge Mark recipes from intent, review their colour and readability, and keep versions of your drafts.

MCP or the API

MCP server

  • For AI assistants that support remote MCP servers.
  • One address: https://gradiently.design/api/mcp.
  • Tools find your brand, save designs and return Studio links for you.
  • Best when you want to ask for work in plain words.

API

  • For scripts, back ends and automations.
  • JSON over HTTPS under https://gradiently.design/api.
  • You choose the brand, send the design document and handle each response.
  • Best when you need exact, repeatable control.

The MCP tools are built on the API. A tool call makes the same requests your code would, with the same key, so it counts against the same limits and fails with the same messages.

Quick start

  1. 1

    Create a key

    In Gradiently, open Settings › API and agents, choose the workspace, name the key after where you'll use it, pick what it can do and select Create key. Copy the key when it appears: it is shown only once. Only owners and admins can create keys.

  2. 2

    Connect your assistant

    In Claude Code, add Gradiently as a remote MCP server with your key in the Authorization header (the command is below). Other clients are covered on MCP and AI assistants.

  3. 3

    Ask for something

    Try "Generate three brand directions for a small bakery called Hearth, calm and warm, then adopt the first one." The assistant calls generate_brand and adopt_brand, and you get a new brand with its own draft Mark and starter designs in your workspace.

bash
export GRADIENTLY_API_KEY="gr_live_…"

claude mcp add --transport http gradiently https://gradiently.design/api/mcp \
  --header "Authorization: Bearer $GRADIENTLY_API_KEY"
Keep the key in an environment variable or a secret manager, never in a file you commit.

To call the API instead, send the same header with each request:

bash
curl https://gradiently.design/api/marks?q=harbour \
  -H "Authorization: Bearer $GRADIENTLY_API_KEY"
Searching the Market needs a key with the Search Marks permission (marks:read).

How a key acts

A key acts as the person who created it, inside the one workspace it was created for. It can never reach another workspace, even one its creator belongs to. It works only while its creator is still an owner or admin of that workspace and their account is active; if they are removed, demoted or switched off, the key stops working.

  • Designs, brands and uploads a key makes belong to the workspace, exactly as if its creator had made them in the app.
  • Marks a key claims are held by its creator, never by the workspace, and any licence stays theirs.
  • Designer work a key starts spends the workspace's AI credits, like the Designer in the Studio.
  • A key cannot manage keys, change the account, reach billing or give a Mark away. API keys and scopes lists what it can never do.

The rest of the docs

  • MCP and AI assistants: connecting Claude Code and other clients, every tool with its inputs and scopes, and example prompts.
  • API reference: the base URL, authentication, every endpoint a key can call, errors, rate limits and pagination.
  • API keys and scopes: creating, rotating and revoking keys, what each scope allows and how to keep keys safe.
  • New to MCP? What is MCP explains it in plain words, and modelcontextprotocol.io has the specification.

Stuck, or missing something you need? Send us a request and a person will reply.

Need a hand?

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

Send a request