Your agent gets a build brief before it builds a screen, and a scored review after: does the screen serve the user's job, does it follow UX heuristics, does it match your design system. Reviews use a real screenshot when the page is running.

Works with any MCP client: Claude Code, Codex, Cursor, Grok Build, Claude Desktop and others.

Tools

Tool	When	What it returns
`Discover`	Before building a screen	A ~600-token build brief: the user's job, heuristics to apply, patterns, design tokens
`Ux`	After building	0–10 score for heuristics, cognitive load, pattern conformance and job fit, with findings and fixes
`Visual`	After building	0–10 score for brand compliance, visual hierarchy and aesthetics, from a screenshot when you pass `render_url`

Project context is stored server-side and improves with every call: anti-patterns found in one review shape the next brief.

Hosted or local?

TheDesignAgent runs in two places. The same API key works in both, and the hosted server can also sign you in through the browser with no key.

	Hosted: `https://www.thedesignagent.ai/mcp`	Local: this package
Tools	`Discover`, `Ux`, `Visual`	`Discover`, `Ux`, `Visual`
Install	Nothing to install	Node.js 20+, runs through `npx`
Screenshots	Public pages and preview deploys	Also `localhost`, with your local browser

Use the hosted server for briefs, UX reviews and Visual reviews of deployed or preview URLs. Use this package when you want Visual reviews of pages running on your machine.

Setup

Get an API key (it starts with tda_) at thedesignagent.ai/dashboard/api-keys.

You can put the key in each client's config as shown below, or save it once for every client and the CLI:

npx -y --package=@thedesignagent/mcp thedesignagent login

That writes ~/.thedesignagent/credentials, readable only by you. THEDESIGNAGENT_API_KEY still wins when it's set, so you can then leave the env lines out of the configs below.

Claude Code (recommended: the plugin)

The plugin includes this server, plus skills that teach the agent the brief → build → review loop and /tda:brief and /tda:review commands:

/plugin marketplace add CMBurnett/the-design-agent-plugin
/plugin install tda@thedesignagent

Or add the server on its own:

claude mcp add thedesignagent -e THEDESIGNAGENT_API_KEY=tda_... -- npx -y --package=@thedesignagent/mcp thedesignagent-mcp

Or the hosted server, with no install and no key:

claude mcp add --transport http thedesignagent https://www.thedesignagent.ai/mcp

Then run /mcp in Claude Code, choose thedesignagent and sign in to your TheDesignAgent account in the browser. There's no key to copy. For CI or a shared machine, use a key instead by adding --header "Authorization: Bearer tda_...".

Codex

In ~/.codex/config.toml:

[mcp_servers.thedesignagent]
command = "npx"
args = ["-y", "--package=@thedesignagent/mcp", "thedesignagent-mcp"]
env = { THEDESIGNAGENT_API_KEY = "tda_..." }

Cursor, Claude Desktop and other JSON-configured clients

Local:

{
  "mcpServers": {
    "thedesignagent": {
      "command": "npx",
      "args": ["-y", "--package=@thedesignagent/mcp", "thedesignagent-mcp"],
      "env": { "THEDESIGNAGENT_API_KEY": "tda_..." }
    }
  }
}

Hosted:

{
  "mcpServers": {
    "thedesignagent": {
      "url": "https://www.thedesignagent.ai/mcp"
    }
  }
}

The client asks you to sign in through the browser. To use a key instead, add "headers": { "Authorization": "Bearer tda_..." }.

The package has two commands, so pass --package and name thedesignagent-mcp as shown. A bare npx @thedesignagent/mcp won't start.

How agents use it

Identify the project. Pass project_id from a .thedesignagent file in the repo root, or repo_hash (SHA-256 of the git remote URL) if there isn't one yet.
Call Discover with the screen you're about to build. On a project's first call it returns needs_setup with an extraction task: the agent scans the repo, builds a project model and calls again. After that, briefs come back immediately.
Build following the brief.
Call Ux and Visual with the built code as artifact. Pass render_url (for example http://localhost:3000/checkout) to Visual for a screenshot-based review.
Fix critical and high findings, then re-check once.

After the first successful Discover, write { "project_id": "<id>" } to .thedesignagent and commit it, so every agent on the repo shares the same project context.

Command line and CI

The same package has a thedesignagent command for terminals, headless agent runs and CI. npx -y --package=@thedesignagent/mcp thedesignagent runs it with no install.

npx -y --package=@thedesignagent/mcp thedesignagent check http://localhost:3000/checkout --threshold 7
npx -y --package=@thedesignagent/mcp thedesignagent check app/checkout/page.tsx --checks ux
npx -y --package=@thedesignagent/mcp thedesignagent brief "Build the forecast approval queue"

Command	What it does
`check [url\|file]`	With no target, checks every page listed in `.thedesignagent` (below). Otherwise scores a page from a screenshot (`visual`) or a source file (`ux`). On a URL, `--checks visual,ux --code <file>` runs both (the UX review reads the page's source). `--task` says what the screen is for.
`brief "<task>"`	Writes a build brief to `.thedesignagent-brief.md` (`--out -` prints it). Point any agent at it from AGENTS.md or CLAUDE.md.
`login [key]`	Saves your API key. Reads it from stdin when piped.

check options: --threshold <n> exits 1 when a check's overall score is below n; --json prints the full result (scores, findings, recommendations, screenshot path) for scripts and agents.

Exit codes: 0 ok, 1 below threshold, 2 error (key, network, usage), 3 the page redirected to a login screen (no review ran, nothing charged).

Both commands find the project from .thedesignagent in the repo, or --project <id>, or THEDESIGNAGENT_PROJECT_ID. Commit .thedesignagent: CI clones often use a different remote URL than your machine, so the fallback (a hash of the remote URL) can point at a different project. A project's first brief needs a project model, which your coding agent builds on its first Discover call; after that the CLI's briefs work anywhere.

Checking a set of pages

List the pages to check in .thedesignagent, and check with no target checks them all:

{
  "project_id": "proj_...",
  "check": {
    "base_url": "http://localhost:3000",
    "threshold": 7,
    "pages": [
      { "path": "/checkout", "task": "Pay for the items in the cart" },
      { "path": "/orders", "code": "app/orders/page.tsx", "checks": ["visual", "ux"], "threshold": 7.5 }
    ]
  }
}

npx -y --package=@thedesignagent/mcp thedesignagent check
npx -y --package=@thedesignagent/mcp thedesignagent check --base-url https://my-app-git-feature.vercel.app

--base-url (or THEDESIGNAGENT_BASE_URL) points the same pages at a preview deploy. A page's own threshold overrides the shared one, and --threshold overrides both. code paths are relative to the repo root. The run exits 1 if any page is below its threshold, and 3 if a page redirected to login.

Only the pages a branch changed

check --changed diffs the branch against origin/main (in GitHub Actions, the pull request's base branch; --base <ref> to choose) and checks the Next.js App Router pages it touched. A changed file counts toward the nearest page.tsx above it, so editing app/orders/_components/table.tsx re-checks /orders. Route groups like (shop) are handled. Dynamic routes ([id]) have no URL to visit, so list a concrete page for them in .thedesignagent (with code pointing at the page file) and it's checked when that file changes. Pages behind your app's sign-in can't be reviewed from a preview, so skip them with check.exclude: "exclude": ["/dashboard", "/admin"] skips those routes and everything under them. List choices you've made on purpose in check.decisions (for example "decisions": ["Show all five credit packs; don't fold them."]), and reviews won't recommend against them.

npx -y --package=@thedesignagent/mcp thedesignagent check --changed --base-url https://my-app-git-feature.vercel.app --threshold 7

Headless agent runs

Ask the agent to run the check and fix what it finds:

claude -p "Build the checkout page. Then run 'npx -y --package=@thedesignagent/mcp thedesignagent check http://localhost:3000/checkout --json' and fix every critical and high finding."
codex exec "Build the checkout page. Then run 'npx -y --package=@thedesignagent/mcp thedesignagent check http://localhost:3000/checkout --json' and fix every critical and high finding."
grok -p "Build the checkout page. Then run 'npx -y --package=@thedesignagent/mcp thedesignagent check http://localhost:3000/checkout --json' and fix every critical and high finding."

Or have the agent write the brief first: npx -y --package=@thedesignagent/mcp thedesignagent brief "Build the checkout page" && claude -p "Read .thedesignagent-brief.md, then build the checkout page."

GitHub Actions

Fail a build when a page scores below 7. Add your key as the repository secret THEDESIGNAGENT_API_KEY. GitHub's Ubuntu runners include Chrome.

name: Design check
on: pull_request

jobs:
  design-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-node@v7
        with:
          node-version: 20
      - run: npm ci
      - run: npm run build
      - run: npm start &
      - run: npx -y wait-on -t 120000 http://localhost:3000/checkout
      - run: npx -y --package=@thedesignagent/mcp thedesignagent check http://localhost:3000/checkout --threshold 7
        env:
          THEDESIGNAGENT_API_KEY: ${{ secrets.THEDESIGNAGENT_API_KEY }}

On Vercel preview deploys: the GitHub Action

The TheDesignAgent design review action runs when a preview deploy is ready, reviews the pages the pull request changed on that preview, comments on the PR and fails below your threshold. For protected previews, pass a Vercel Protection Bypass for Automation secret: the CLI reads it from VERCEL_AUTOMATION_BYPASS_SECRET and sends it only to the preview's own domain. On a deployment_status event, check --changed takes the preview URL from the event and finds the pull request from the deployed commit. Add --dry-run to list the pages a run would cover without reviewing anything.

On pull requests: changed pages only, with a PR comment

Check only the pages the pull request touched and post the scores as one comment, updated on every push:

name: Design check
on: pull_request

permissions:
  contents: read
  pull-requests: write

jobs:
  design-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v7
        with:
          node-version: 20
      - run: npm ci
      - run: npm run build
      - run: npm start &
      - run: npx -y wait-on -t 120000 http://localhost:3000
      - run: npx -y --package=@thedesignagent/mcp thedesignagent check --changed --base-url http://localhost:3000 --threshold 7 --pr-comment
        env:
          THEDESIGNAGENT_API_KEY: ${{ secrets.THEDESIGNAGENT_API_KEY }}
          GITHUB_TOKEN: ${{ github.token }}

fetch-depth: 0 lets --changed diff against the base branch. The comment lists each page's scores against the threshold, with the top findings and fixes folded under each. If commenting fails (for example without pull-requests: write), the check still runs and still sets the exit code.

The score table and the critical and high findings appear on the run's summary page. For pages behind login, set THEDESIGNAGENT_AUTH_SEED to an AuthSeed object, { "cookies": [...] } (the format thedesignagent-auth saves under ~/.thedesignagent/auth/), ideally for a test account.

Screenshots

Visual screenshots render_url with your local Chrome, Edge, Brave or Chromium. If it can't find one, set CHROME_PATH to the browser binary.

Screenshots are saved to ~/.thedesignagent/screenshots/ for 24 hours, so you can see exactly what was reviewed.

When Visual lands on a login page it stops before reviewing (nothing is charged) and tells your agent how to save a session. Sessions are stored per site under ~/.thedesignagent/auth/ (readable only by you) and applied to every later screenshot of that site.

There are two ways to save one:

A login recipe (automatic). A small script in your repo, .thedesignagent-login.mjs, prints either a URL that logs in when opened (a magic link, a dev-only login route) or cookies as JSON. Pipe it into login:

node .thedesignagent-login.mjs | npx -y --package=@thedesignagent/mcp thedesignagent-auth login http://localhost:3000/dashboard

It logs in headlessly, checks the page no longer redirects to login, and saves. The Claude Code plugin's /tda:setup writes a recipe for Supabase apps.

Capture by hand. Opens a browser window; log in and it saves and closes by itself once you leave the login page:

npx -y --package=@thedesignagent/mcp thedesignagent-auth capture http://localhost:3000/dashboard

It uses a dedicated browser profile, so later re-captures are often instant. Agents can run it in the background: it ends with TDA_AUTH_SAVED <origin> or TDA_AUTH_FAILED <reason>, and gives up after 10 minutes.

Check what's saved with thedesignagent-auth status <url>.

Environment variables

Variable	Required	Purpose
`THEDESIGNAGENT_API_KEY`	Yes, unless you ran `thedesignagent login`	Your `tda_` API key
`THEDESIGNAGENT_PROJECT_ID`	No	Project for the CLI when there's no `.thedesignagent` file
`THEDESIGNAGENT_AUTH_SEED`	No	Session cookies as JSON, for screenshots behind login in CI
`CHROME_PATH`	No	Browser binary for screenshots, if it isn't found automatically
`ANTHROPIC_API_KEY`	No	Enables a fallback review through Claude when TheDesignAgent's API is unreachable

Errors

An authentication error means the API key is missing, wrong or revoked.
A rate-limit message means wait briefly and retry.
Account errors are returned as tool errors; the message says what to do.

Keywords

mcp

model-context-protocol

design

ui-review

design-system

FAQs

What is @thedesignagent/mcp?

Is @thedesignagent/mcp popular?

Is @thedesignagent/mcp well maintained?

Package last updated on 06 Oct 2026

@thedesignagent/mcp