AI assistants & API keys

Before you start

• Connecting an app (Claude, ChatGPT): any ColorCraft account. Reading is always allowed; making books needs a plan or the free trial, as on the website.
• API keys (Claude Code, Cursor, scripts, your own agents): a paid Creator plan or higher. Keys keep working for reading if the plan ends, but stop spending.
• Current Terms. If our Terms changed since you last accepted them, an assistant can still read but can’t spend until you accept them on colorcraft.ai.
• Accounts with free pages from before plans existed need a plan to spend through an assistant; the pages still work on colorcraft.ai.

Connect your assistant

Claude and ChatGPT: Connect

1. 1

   Add ColorCraft as a custom connector

   In your app’s connector settings, add a custom connector with the address https://colorcraft.ai/api/mcp.

2. 2

   Sign in and choose what it may do

   A ColorCraft page opens. Sign in (or sign up), check the app’s name, and tick what it may do. Research niches starts ticked; Plan and draw books and Covers, listings and print files spend pages and start unticked. Under Limits for this app, set how much it may spend. Then click Approve.

3. 3

   Ask for something

   Try “What can I make with the pages I have left?”. The app never sees your password, and it never needs a key.

If your app can’t connect this way yet, use an API key with a tool that can send a header (below).

Claude Code

Create an API key (below), then run:

claude mcp add --transport http colorcraft https://colorcraft.ai/api/mcp \
  --header "Authorization: Bearer cc_live_…"

To share the set-up with a project without sharing the key, put this in the project’s .mcp.json and keep the key in the COLORCRAFT_API_KEY environment variable:

{
  "mcpServers": {
    "colorcraft": {
      "type": "http",
      "url": "https://colorcraft.ai/api/mcp",
      "headers": { "Authorization": "Bearer ${COLORCRAFT_API_KEY}" }
    }
  }
}

Cursor and other MCP clients

Add a remote server with the address and an Authorization header. In Cursor’s MCP settings file:

{
  "mcpServers": {
    "colorcraft": {
      "url": "https://colorcraft.ai/api/mcp",
      "headers": { "Authorization": "Bearer cc_live_…" }
    }
  }
}

Your own agent

With the Claude Agent SDK (TypeScript; the Python SDK takes the same server settings):

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "Find a strong coloring-book niche and plan a 24-page book. Ask me before spending.",
  options: {
    mcpServers: {
      colorcraft: {
        type: "http",
        url: "https://colorcraft.ai/api/mcp",
        headers: { Authorization: `Bearer ${process.env.COLORCRAFT_API_KEY}` },
      },
    },
    allowedTools: ["mcp__colorcraft__*"],
  },
})) {
  if (message.type === "result" && message.subtype === "success") console.log(message.result);
}

With the Claude API’s MCP connector, send the key as the server’s authorization_token and the anthropic-beta: mcp-client-2025-11-20 header:

{
  "model": "claude-opus-5-5",
  "max_tokens": 16000,
  "mcp_servers": [
    { "type": "url", "url": "https://colorcraft.ai/api/mcp", "name": "colorcraft", "authorization_token": "cc_live_…" }
  ],
  "tools": [{ "type": "mcp_toolset", "mcp_server_name": "colorcraft" }],
  "messages": [{ "role": "user", "content": "What can I make with the pages I have left?" }]
}

Any other MCP client works the same way: Streamable HTTP to the address above, with Authorization: Bearer cc_live_…. The server is stateless and speaks MCP 2026-07-28 and the 2025-era versions back to 2024-10-07. Send one JSON-RPC message per request: batches work only on protocol 2025-03-26 and older.

Create an API key

1. 1

   Open the Developer page

   Open the account menu and choose Developer. In API keys, click Create key.

2. 2

   Name it, choose what it may do, and set its limits

   Give it a name you’ll recognise (“Claude Code laptop”). Account is always on; Research, Create and Finish start ticked, so untick what it doesn’t need. Set its spending limits and when it expires.

3. 3

   Copy it now

   The key (it starts with cc_live_) is shown once. Copy it into your tool straight away; we keep only a scrambled fingerprint, so we can’t show it again. Lost it? Revoke it and make another.

The Developer page also lists each key’s and app’s use: calls and pages over the last 7 and 30 days, the last 50 calls, and what is left of today’s limits. Revoke (a key) and Disconnect (an app) stop it at once. Removing ColorCraft inside an app only deletes the app’s copy: disconnect it here as well.

What an assistant can do

27 tools in four groups. An assistant only sees the groups you allowed. Everything is listed with its cost in pages of your balance; anything not marked otherwise is free.

Research uses research searches, not pages: trials, Mini, Starter and older plans get 3 in total; paid plans get 30 a month on Creator, 100 on Professional and 300 on Studio. Reading a report you already hold never uses one.

Spending limits

Three things stop an assistant from spending more than you meant, even one left running overnight:

• spend_limit on every call that uses pages. The assistant says the most the call may use. If the cost is higher, nothing starts and the call answers limit_exceeded.
• idempotency_key on every call that spends or creates. If the same call arrives twice (a retry after a dropped connection), it is done and charged once and the first answer comes back. The same key with different arguments answers idempotency_conflict.
• Limits on each key and app, checked before any work starts. Change them on the Developer page; these are the defaults:

Pages per day count what has been charged plus what running jobs still expect to use, so two books started at once can’t both slip under the limit. Your balance is checked the same way across all your keys and apps.

Long jobs

• Drawing a book, building a niche report, painting cover art and making PDFs take minutes. The tool answers at once with a job_id; the assistant follows it with get_job, which waits up to 25 seconds a call and answers as soon as something changes.
• If the conversation ends, the work carries on and shows up in your dashboard. Another conversation finds it with list_active_jobs.
• Storybooks and comics of 8 pages or more draw a 2-page preview first and wait. The assistant should show you the preview, then call approve_preview to draw the rest or cancel_book to stop, so a look you don’t like costs 2 pages, not a whole book.
• Files come back as download links, fresh on every get_job call and valid for about an hour. The files themselves are kept for 7 days; export again after that.

When you need to do something

Some things only you can do, in a browser: start a plan or the trial, upgrade, accept new Terms, raise a limit, or unlock a trial book’s clean print file. When that happens the tool says so with a human_action: a reason, a colorcraft.ai link for you to open, and what the assistant will do afterwards (check your account again, or retry the call). Assistants never take payment.

On the free trial, interior PDFs and cover wraps come back as watermarked previews, not for KDP, with a link to unlock the clean file for that book or start a plan.

What it doesn’t do

• Files are for KDP paperbacks. Niche reports cover hardcover too, but say when ColorCraft can’t make that format.
• Amazon KDP has no upload API, so the journey ends with files you upload to KDP yourself: the interior PDF, the cover wrap PDF and the listing text. Paperbacks need at least 24 interior pages, and the tools run the same checks the editor does, but Amazon decides whether to accept a book.
• No ordering printed copies, no changes to your plan or payment details, and nothing you made is ever deleted.
• No uploading your own manuscript, photos or pictures, and no page-by-page editing. Use the app for those.

Errors

Every refusal comes with a code an assistant can act on and a message in plain words. Each tool answers with one text block: a one-line summary, a blank line, then JSON. A successful call also returns that JSON as structured content. A refusal is marked as an error and has no structured content; its JSON is {error_code, message} plus details such as human_action, retry_after_seconds or, for invalid_args, the issues. An argument a tool doesn’t take is refused with invalid_args rather than ignored. Some refusals also carry route_code, ColorCraft’s internal reason, for support; assistants should act on error_code. The codes:

Your data

An app you connect sees what its tools return: your account’s email, plan and page balance, your books’ titles, plans, reports and file links. It never sees your password or payment details. What it does with them is up to that app and its own privacy policy. We keep a log of each call (the tool, the outcome, the pages it used) for 90 days, so you and we can see what happened; the arguments are removed after 30 days. See the Privacy Policy and the Terms of Service, which cover API keys and connected apps.