# Gradiently MCP: connect Claude, ChatGPT or any MCP client

[Canonical HTML page](https://gradiently.design/guide/connect-ai-assistant)

Gradiently speaks MCP, so an AI assistant can search Marks, read your brand and make designs that open in your Studio. Here is the setup in plain language, and how to keep it safe.

## The short version

- Gradiently runs a hosted MCP server at https://gradiently.design/api/mcp that any MCP client able to send an Authorization header can connect to.
- You connect with an API key created by a workspace owner or admin in Settings, under API and agents, sent as a Bearer token.
- Each key belongs to one workspace and carries only the permissions ticked when it was made, such as reading designs or searching Marks.
- Once connected, an assistant can search Marks, read your brand profile, make and edit designs and resize them, and every design opens in the Studio.
- A key is shown once, can be revoked at any time, and never moves a Mark's ownership to anyone else.

To use the **Gradiently MCP** server, create an API key in **Settings › API and agents**, then add the hosted endpoint `https://gradiently.design/api/mcp` to your MCP client with the header `Authorization: Bearer <your key>`. That's the whole connection. From then on, an assistant such as Claude can search Marks, read your brand, make designs and change them, and each design it makes opens in your Studio like any other.

MCP, the Model Context Protocol, is an open standard that lets AI assistants use real tools. If the idea is new, [what MCP is](https://gradiently.design/guide/what-is-mcp) explains it in plain words, and the protocol's own site at [modelcontextprotocol.io](https://modelcontextprotocol.io) has the specification. The full technical reference for Gradiently's server lives in the [developer docs](https://gradiently.design/developers/mcp).

## What you need before you start

- **A Gradiently account** and a workspace you are an **owner or admin** of. Only owners and admins can create or revoke keys.
- **An MCP client that can connect to a remote server over HTTP** and send a custom `Authorization` header. Claude Code does; many desktop and editor clients do too.
- **A safe place for the key**, such as a password manager or your client's secret storage. It is shown only once.

## Step 1: create a scoped API key

1. **Open Settings › API and agents** Pick the workspace the assistant should work in with the picker at the top. A key only ever acts in the workspace that issued it.
2. **Name it after where it's used** "Claude Desktop" or "Marketing agent". The name is how you'll know which one to revoke later.
3. **Tick only what it needs** The permissions are listed below. Four are ticked by default; **Claim Marks** is not.
4. **Create, then copy it now** The key appears once, in full. Copy it into your password manager before closing the dialog. Afterwards Settings shows only its first characters, when it was last used and how many permissions it has.

| Permission | What it lets the assistant do |
| --- | --- |
| Read designs | List and open designs in the workspace |
| Create and edit designs | Make new designs and change them |
| Search Marks | Look up Marks in the Market |
| Claim Marks | Claim a Mark for this workspace (off by default) |
| Generate brands | Make brand candidates from a description |

The permissions a key can carry, as Settings names them. Grant the smallest set that does the job.

## Step 2: add the endpoint to your client

The same page shows a ready-made snippet under **Connect an MCP client**, with a copy button. Clients that read a JSON configuration take it as it is; put your key in place of `YOUR_KEY`.

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

The configuration from Settings › API and agents. Keep real keys out of files you share or commit.

In **Claude Code**, add the server from your terminal. Keep the key in an environment variable rather than typing it into your shell history.

```bash
claude mcp add --transport http gradiently https://gradiently.design/api/mcp \
  --header "Authorization: Bearer $GRADIENTLY_API_KEY"
```

Adding Gradiently to Claude Code over HTTP.

Other assistants, including ChatGPT, can connect wherever their app, plan and workspace settings allow a custom remote MCP server with an authorization header. Support differs between clients and changes over time, so check your client's own help pages; [making on-brand designs from ChatGPT](https://gradiently.design/guide/design-with-chatgpt) covers what to look for. Once connected, ask the assistant to list its Gradiently tools to confirm it worked.

## What your assistant can do once connected

The server exposes the same actions you have in the product, through the same permissions. Grouped by job, they look like this:

| Job | What the assistant can do |
| --- | --- |
| Find | Search Marks by name, code or tone; read a Mark's recipe; list your Marks; find templates to start from |
| Design | Ask Gradiently's own Designer to make or change a design from a plain request; make a set of designs from one brief; start from a template; edit text and elements |
| Resize | Save copies of a design in other sizes, beside the original, which stays unchanged |
| Brand | Read and update a brand's profile; generate brand candidates and set one up with a Mark and starter designs |
| Marks | Forge a Mark recipe from a description and save it as your private draft; put a Mark on a design; claim a Mark if the key allows it |
| Share and export | Turn on a view-only link for a design, or render it as a PNG or PDF when the Mark is claimed |

Every design the assistant makes is saved in your workspace and comes back with a link that opens it in the Studio.

Plain requests work best. The assistant hands them to the Designer, which reads your brand profile and the brand's Mark before it composes anything. As in the Studio, the Designer's work is measured in AI credits.

A portrait event poster for a rooftop solstice party on a glowing gradient background

What "a poster for our rooftop solstice party, 21 June, sunset to sunrise" can come back as: a saved design on your brand's Mark, ready to open and adjust.

- "Make six posts for our autumn launch in our brand, portrait for Instagram."
- "Take yesterday's announcement and make a story and an X header from it."
- "Find three dark Marks with a silk material and tell me their codes."
- "Update our brand profile: we sound calm and precise, never salesy."

For a fuller walkthrough with Claude specifically, see [designing with Claude through Gradiently](https://gradiently.design/guide/design-with-claude). If you want the assistant to stay on-brand, [brand guidelines your AI assistant can follow](https://gradiently.design/guide/brand-guidelines-for-ai) shows how to write the brand profile it reads.

## Keeping the connection safe

### Avoid

- One key with every permission, shared by every tool
- Pasting a key into a chat, a document or a repository
- Leaving keys for tools you've stopped using
- Ticking Claim Marks for an agent that only designs

### Do

- One key per client, named after where it runs
- Storing it in a password manager or secret store
- Revoking unused keys in Settings; they stop at once
- Granting the smallest set of permissions that works

A few guarantees hold whatever the client does. A key only works in the workspace that issued it. It acts through the same rules as the person who created it, so it can't do anything their role can't. A key never transfers a Mark's ownership to the workspace or anyone else. Private designs stay private: a view-only link exists only when you ask for one. And if the person who created a key is removed from the workspace or loses their admin role, their keys stop working too.

> **Working as a team** Keys belong to a workspace, so an agent's designs land where your teammates can see and comment on them. [Working with a team in Gradiently](https://gradiently.design/guide/teams-and-workspaces) covers roles and sharing.

## FAQ

### What is the Gradiently MCP endpoint?

The hosted endpoint is `https://gradiently.design/api/mcp`. Every request needs the header `Authorization: Bearer` followed by an API key from Settings › API and agents.

### Who can create a Gradiently API key?

Owners and admins of a workspace. Each key belongs to that one workspace and carries only the permissions ticked when it was created.

### Does it work with ChatGPT?

It works with any MCP client that can connect to a remote HTTP server and send an authorization header. Whether ChatGPT can depends on the app, plan and workspace settings you use, so check its current help pages.

### What happens if my key leaks?

Revoke it in Settings › API and agents. Anything using it stops working straight away, and you can create a new key.

### Can an assistant claim Marks for me?

Only if its key has the Claim Marks permission, which is off by default. Claiming is free while Gradiently launches.