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.
On this page
To use the Gradiently MCP server, create an API key in Settings › API and agents, then add the hosted endpoint https:// 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 explains it in plain words, and the protocol's own site at modelcontextprotocol.io has the specification. The full technical reference for Gradiently's server lives in the developer docs.
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
Authorizationheader. 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.
What it lets the assistant do
What it lets the assistant do
What it lets the assistant do
What it lets the assistant do
What it lets the assistant do
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.
{
"mcpServers": {
"gradiently": {
"url": "https://gradiently.design/api/mcp",
"headers": { "Authorization": "Bearer YOUR_KEY" }
}
}
}In Claude Code, add the server from your terminal. Keep the key in an environment variable rather than typing it into your shell history.
claude mcp add --transport http gradiently https://gradiently.design/api/mcp \
--header "Authorization: Bearer $GRADIENTLY_API_KEY"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 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:
What the assistant can do
What the assistant can do
What the assistant can do
What the assistant can do
What the assistant can do
Plain requests work best. The assistant can lay out and edit designs itself with Gradiently's tools, which spends no Gradiently AI credits. If you ask for Gradiently's own Designer instead, it reads your brand profile and the brand's Mark before it composes anything, and as in the Studio, its work is measured in AI credits.
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. If you want the assistant to stay on-brand, brand guidelines your AI assistant can follow 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.
Questions people ask
What is the Gradiently MCP endpoint?
The hosted endpoint is https://. 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 a Mark is a one-time payment, so tick that permission only for an assistant you want claiming for you.
Written by Gradiently
The team behind Gradiently, a design tool built around Marks: living gradients that make everything you design look like yours.
See our profile