# Gradiently Claude connector: design with MCP inside Claude

[Canonical HTML page](https://gradiently.design/guide/design-with-claude-connector)

Claude can search Marks, read your brand and build real, editable designs in your workspace. There are two ways in, a connector with sign in or a scoped key, and this page covers both.

## The short version

- Gradiently runs a hosted MCP server for Claude at https://gradiently.design/api/mcp.
- In the Claude app, Gradiently is added as a custom connector with OAuth sign in; in Claude Code, it is added with a scoped API key from Settings › API and agents.
- A new API key starts with the permissions every design tool needs, and Claim Marks stays off unless you choose it.
- When Claude composes a design with Gradiently's tools it spends no Gradiently AI credits, and every saved design opens in the Studio.
- A key only ever works in the workspace that issued it, acts as the owner or admin who made it, and can be revoked at once.

To set up the **Gradiently Claude** connector, point Claude at Gradiently's hosted MCP server at `https://gradiently.design/api/mcp`. In the Claude app, add it as a custom connector and sign in to Gradiently. In Claude Code, add it from the terminal with a scoped API key. Either way, Claude can then search Marks, read your brand kit and make designs that are saved in your workspace and open in the Studio, with every word still editable.

MCP, the Model Context Protocol, is the open standard that lets Claude use real tools. [What is MCP](https://gradiently.design/guide/what-is-mcp) explains it simply, and the protocol itself is documented at [modelcontextprotocol.io](https://modelcontextprotocol.io).

## Which way to connect Claude

| Where you use Claude | How it connects | Sign in |
| --- | --- | --- |
| The Claude app, on the web or desktop | Custom connector | OAuth: sign in to Gradiently, pick a workspace |
| Claude Code in your terminal | Remote MCP server over HTTP | A scoped API key in the Authorization header |
| Other MCP clients | Remote server with a custom header | A scoped API key |

Same server, same tools, same permissions. Only the way Claude proves who it is differs.

Whichever route you take, you must be an **owner or admin** of the Gradiently workspace. Editors and viewers can't connect assistants or create keys.

## Connect the Claude app with a custom connector

1. **Open Claude's connector settings** Add a custom connector. Which Claude plans allow custom connectors is Anthropic's decision, so check Claude's help pages if you can't see the option. [Claude connectors](https://gradiently.design/guide/claude-connectors) explains the feature.
2. **Paste the server address** Name it Gradiently and use `https://gradiently.design/api/mcp`. Choose OAuth sign in.
3. **Sign in and choose a workspace** In the Gradiently window, pick the workspace Claude should work in and read the permissions under **Allow this assistant to**.
4. **Allow, then check** Choose **Allow connection**. Back in Claude, ask it to list its Gradiently tools to confirm.

Access renews automatically for up to 30 days, then you reconnect. A custom connector is yours to use straight away; a listing in Claude's public directory is separate and needs Anthropic's review.

## Connect Claude Code with a scoped API key

Claude Code uses a key rather than sign in. Create one in Gradiently under **Settings › API and agents**: choose the workspace, name it after where it lives (*Claude Code, laptop*), tick what it may do and select **Create key**. The key is shown once, so copy it into your password manager straight away.

```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 so it never lands in your shell history or a committed file. Start a new session and ask Claude to list Gradiently's tools.

Other clients that read a JSON file usually accept the same server and header. Settings shows a ready snippet under **Connect an MCP client**.

```json
{
  "mcpServers": {
    "gradiently": {
      "url": "https://gradiently.design/api/mcp",
      "headers": { "Authorization": "Bearer gr_live_…" }
    }
  }
}
```

The JSON shape many MCP clients accept. Check your client's own documentation for its exact format.

## Choosing the key's permissions

Each permission is a scope. A new key starts with five that cover every design tool, so most people change nothing. Add the others only when Claude genuinely needs them.

| Permission in Settings | On by default | What it allows |
| --- | --- | --- |
| Read designs | Yes | Read brands, designs and uploads, and render designs |
| Create and edit designs | Yes | Create, change and resize designs, upload images, run the Designer |
| Search Marks | Yes | Search the Market and read any public Mark |
| Read the workspace | Yes | Read the workspace and its members |
| Generate brands | Yes | Generate brand directions from a name and description |
| Edit brands | No | Change a brand's profile and Mark, create brands |
| Claim Marks | No | Claim an available Mark for the key's creator |
| Invite members | No | Send invitations to join the workspace |

Grant only what the job needs. A key's scopes can't be changed later, so make a new key if the job changes.

## What Claude can do once connected

Claude works through the same actions you have in the product. It can search the Market by name, colour words or code; read your brand profile, voice and fonts; draw an original design, look at the rendered image and refine it; fill one of Gradiently's templates; change the words on a saved design; make resized copies; and render a design to PNG or PDF. When Claude composes the design itself, Gradiently charges **no AI credits**. If you ask it to hand the job to Gradiently's own Designer, that uses credits as it would in the Studio.

Claude Code makes a particular kind of job easy. Say you keep a blog and want a link image for every post. Ask: *"For each post in /content, make a 1200×630 link preview in our brand with the post title, then render each one as a PNG into /public/og."* Claude designs each image in Gradiently, checks it and writes the files where your site expects them. [Open Graph image size](https://gradiently.design/guide/open-graph-image-size) explains why 1200×630.

A wide blog link preview image with an engineering article title on a gradient background

A 1200×630 link preview designed through the Gradiently MCP server and rendered straight into a site's folder.

> **Allow long tool calls** Most tools answer in seconds, but rendering and inspecting a design can take up to three minutes, and a job handed to the Designer up to about five. If your client has a tool timeout setting, raise it.

## Prompts that work well with Claude

- *"Read our brand profile, then make a LinkedIn post and an X post announcing our new office in Bristol."*
- *"Find three dark Marks with a silk material close to deep teal and give me their codes."*
- *"Take yesterday's announcement and make a story and a YouTube thumbnail from it."*
- *"Change the date on the event poster to 14 November and render it as a PDF."*

The better your brand kit, the less you need to say in each request; [brand voice for AI](https://gradiently.design/guide/brand-kit-voice) shows what to fill in. For more ideas aimed at social posts, see [Claude for social media](https://gradiently.design/guide/claude-social-media-posts), and for the bigger picture, [Claude design](https://gradiently.design/guide/design-with-claude).

## Keeping the connection safe

### A key can

- Work in the one workspace that issued it
- Do what its creator's role and its scopes allow
- Make designs that belong to the workspace
- Show when it was last used, in Settings

### A key can never

- Reach another workspace, even one you belong to
- Pay for anything or reach billing
- Transfer, list or release a Mark
- Create or manage other keys

If a key leaks or you stop using it, select **Revoke** beside it in **Settings › API and agents** and it stops working at once. Keys also stop when their creator leaves the workspace or loses the admin role. Using ChatGPT too? [Gradiently in ChatGPT](https://gradiently.design/guide/design-with-chatgpt-app) has its own setup, and the full tool reference is in the [developer docs](https://gradiently.design/developers/mcp).

## FAQ

### What is the Gradiently MCP server address for Claude?

`https://gradiently.design/api/mcp`. In the Claude app use it as a custom connector with OAuth; in Claude Code, add it with your API key in the Authorization header.

### Do I need an API key to use Gradiently in Claude?

Not in the Claude app, which signs in with OAuth. Claude Code and most other MCP clients need a scoped key from Settings › API and agents.

### Does Claude spend my Gradiently AI credits?

Not when it composes designs with Gradiently's tools itself. Handing a job to Gradiently's own Designer uses credits.

### Can Claude claim a Mark for me?

Only with a key that has the Claim Marks permission, which is off by default. Any claim that needs payment still has to be finished in Gradiently.

### Why does Claude say it can't authenticate?

The key was mistyped or revoked, or its creator is no longer an owner or admin of the workspace. Create a new key and update your client.