ColorwayKit MCP: Give Your AI Coding Agent a Verified Color System

Why an agent needs a color system, not a color description

When you describe colors in a prompt, three things go wrong. The model approximates — "a soft warm gray" becomes a different hex every session. Nobody measures — the pairing it emits for button text may sit at 2.6:1 and nothing in the pipeline catches it. And nothing persists — the palette it used last week is gone, so your product drifts.

A token system fixes all three at once. Every color has a role (background, surface, primary, on-primary…), every text/background pairing ships with a measured ratio and a pass/fail verdict, and the values live outside the prompt where they can be versioned and reused. The DESIGN.md workflow covers the file-based half of this; MCP covers the live half.

MCP or a DESIGN.md file — which one?

Both deliver the same verified tokens; they differ in when and how your agent gets them.

• MCP (live): the agent calls the server mid-task, always reads the latest engine output, works across every project you own, metered per account.
• DESIGN.md (file): committed to the repo, versioned with your code, works offline — best for baking the brand system in for CI and teammates.
• They compose: keep DESIGN.md in the repo as the contract, use MCP when the agent needs a fresh theme or wants to validate a color pair it just invented.

Connect in one command

Sign up free, open the MCP page, generate an agent token, then run the command for your client:

• Claude Code: claude mcp add --transport http colorwaykit https://www.colorwaykit.com/api/mcp --header "Authorization: Bearer <YOUR_TOKEN>"
• Cursor: add an MCP server entry with the URL and an Authorization header (JSON config on the MCP page)
• Codex CLI: codex mcp add colorwaykit --url https://www.colorwaykit.com/api/mcp --header "Authorization: Bearer <YOUR_TOKEN>"
• Then verify: ask your agent to "list the color tokens for #4F46E5" — if it answers with named roles (background, surface, primary, on-primary) plus measured contrast numbers, you are connected.

What get_theme actually returns (real output)

get_theme takes one brand hex and returns the full derived system. For #4F46E5 — indigo — the response contains 23 semantic roles for light mode and the same 23 for dark, and every text/background pairing carries four measured fields: the WCAG 2.1 ratio, the threshold it was judged against, the pass/fail verdict, and the APCA Lc value with its own verdict. Where a pair fails, a hue-preserving fix suggestion is included.

Two real numbers from that response. primary on background measures 6.02:1 — WCAG AA pass, APCA Lc 77.5, comfortable for body text. And the report is honest about its own failures: borderStrong on background measures 1.42:1 in light mode (1.91 in dark), below the 3:1 non-text threshold, and the response suggests #8f8f8f as the nearest passing border. That last part matters: a verification result that only ever says pass is a marketing claim, not a measurement.

check_pair: validate a color before it ships

When the agent invents or inherits a pairing mid-task — a muted label on a tinted panel, a status color on a chip — check_pair measures it on the spot. Real example: #A89890 text on #FFF7F3 returns WCAG 2.63:1 (fail at the 4.5:1 body-text threshold), APCA Lc 49.7 (fail for body and large text), plus a suggested foreground that meets 4.5:1 without losing the hue.

This is the check that prompt-only workflows never run. It takes the agent one tool call, and it turns "looks fine on my screen" into a number with a threshold and a fix.

get_theme_by_project: your tuned theme, live

If you fine-tune a theme in the browser — swap the primary, adjust a surface, re-run fixes — save it as a cloud project and get_theme_by_project hands that exact theme to your agent. The ownership check is enforced server-side: an agent can only read projects belonging to the token's account.

Quota: free to start, no card

MCP access comes with a free account: 5 calls per day on Free, 1,000 per month on Plus ($9.9), unlimited on Pro ($19.9). When you hit the limit, the server returns a message your agent will read back to you verbatim, including the upgrade link — no silent failures, no surprise bills.

References

• Model Context Protocol — specification
• WCAG 2.1 — W3C Recommendation
• APCA — Accessible Perceptual Contrast Algorithm

FAQ