The easiest way to let an AI assistant work in derived is to connect it directly. Once connected, the assistant discovers everything it can do on its own: listing and creating canvases, adding and arranging objects, generating images and video, searching your library, and more. You do not need to teach it any commands.
You need an API key first. See Create an API key. The key needs Write and Generate permission for the assistant to create and change things.
What you’ll need
- Node 20 or newer. The connector runs on your machine and is launched by your AI client.
- An API key from Account → API Keys.
The connector is published on npm as derived-mcp.
There is nothing to install. npx fetches it the first time your client starts it.
Connect it
Open your client’s MCP settings
In Claude Desktop this is Settings → Connectors. Claude Code, Cursor and Codex each have their own config file. All of them take the same three things: a command, its arguments, and environment variables.
Add the connector
Paste this and replace the placeholder with your key:
{
"mcpServers": {
"derived": {
"command": "npx",
"args": [
"-y",
"derived-mcp"
],
"env": {
"DERIVED_API_KEY": "paste-your-key-here",
"DERIVED_API_URL": "https://derived.pro"
}
}
}
}Give the first run extra time
The first launch downloads the package. This can take longer than your client’s default startup timeout:
- Claude Code — start it once as
MCP_TIMEOUT=60000 claude. - Codex — add
startup_timeout_sec = 60to the server’s config. - Claude Desktop — if it reports the server failed to start, quit and reopen it. The package is cached by then.
Restart your client
derived appears in the tool list. The assistant can start work.
The two settings
| Variable | Required | What it does |
|---|---|---|
DERIVED_API_KEY | Yes | Your API key. The connector exits immediately if it is missing. |
DERIVED_API_URL | No | Which host to work against — defaults to https://derived.pro, so you can leave it out. |
One package serves both clustrd and derived. They are one deployment over
one database, and a key is matched by its own value, not by host. A wrong
DERIVED_API_URL is not rejected with an
error. It works against the other host without warning. Set it deliberately.
The connector talks to your client over stdio on your own machine. There is no hosted URL to point a client at. The key leaves your computer only in requests to derived itself.
Working with the assistant
Tell it which canvas to use and what you want. For example:
“List my canvases, then add three product shots to the ‘Summer Launch’ board.”
The assistant finds the canvas and does the rest.
It knows how to read a board
The connector ships two things in addition to the tool list:
- A guide it can pull on demand. A prompt called
canvas_literacyteaches it how to read a board before writing to it: which order to look at things in, how to find the images you care about, and which numbers not to over-read. If your client shows prompts (Claude Desktop lists them under the ➕ menu), you can invoke it yourself before a big job. - A field reference. A resource at
derived://guide/canvas-structureexplains every field in a canvas read. The assistant looks up what a number means instead of guessing.
It reads big boards without choking
A canvas read is paginated and summarised. On the first read of a board the assistant gets a compact index plus a whole-canvas summary: how the work clusters in time, which images came from which, and what is starred. It then fetches full detail only for the objects it needs. Boards of several thousand objects are supported.
The assistant can only do what your key allows. If it cannot change something, check that the key has Write and Generate permission, not only Read.
Frequently asked
Do I have to share my password?
No. The assistant uses only the API key you created, never your login. You can revoke the key at any time without affecting your account.
Can it see all my canvases?
Yes. A key covers your whole workspace. Point the assistant at the canvas you want it to work on.
Will it spend my units?
Only when it generates images or videos, and only if the key has Generate permission. If you've connected your own Fal.ai key, generations are billed to that account instead. It can check a price before committing. Ask what something will cost and it tells you without spending anything.
Can it delete my work by accident?
Deleting a canvas, deleting objects, and deleting a smart ref each require the assistant to pass an explicit confirmation flag. None of them happen as a side effect of a vaguer instruction. Deleting a canvas does not delete the underlying library images.
I upgraded and something changed.
npx -y fetches the current version every time. You are always on the latest.
To pin a version, replace derived-mcp in
the args above with derived-mcp@x.y.z.