Reference · MCP

Athina MCP

The Athina MCP server lets external AI clients (Claude Desktop, Cursor, Codex, Zed) read your projects' design tokens and author components on your behalf. Each call is authenticated with a Personal Access Token and gated by the same row-level security the dashboard uses.

Quick start

In your dashboard, open Account → MCP tokens → New token. Pick Read-only for reconnaissance, or Read & write when you're ready to let the AI author components.
Copy the plaintext token — it starts with ath_pat_ and is shown only once.
Drop it into your MCP client config (snippet below).
Restart the client. Athina tools appear in its tool list.

Client config

Every MCP-compatible client takes a similar JSON. For Claude Desktop on macOS, edit ~/Library/Application Support/Claude/claude_desktop_config.json. For Cursor it's Settings → MCP; for Codex the global ~/.codex/mcp.json. Replace the URL with your deployed host when going to production.

json

{
  "mcpServers": {
    "athina": {
      "type": "http",
      "url": "http://localhost:3000/api/mcp",
      "headers": {
        "Authorization": "Bearer ath_pat_..."
      }
    }
  }
}

Authentication

Every request to /api/mcp must carry an Authorization: Bearer ath_pat_… header. The server hashes the token (SHA-256), looks up the owning user, then forges a short-lived Supabase JWT so standard RLS gates each tool call: you only see and modify projects you'd see and modify in the dashboard.

Scopes: Read-only tokens can call any tool tagged scope: read; calling a scope: edit tool returns an error before touching the database. Read & write tokens have no extra cap — RLS still blocks edits on projects where you're only a viewer.

Read tools · 8

Available to any token. Safe to expose to experimental agents.

list_projectsRead-only

List every project the calling user can see (owned + member-of + public).

get_projectRead-only

Fetch a single project by id.

project_iduuidrequired: UUID of the target project (look it up with list_projects).

list_design_tokensRead-only

Return every design token for a project — fonts, color categories with colors, spacing, icon sizes with icons. All entries include their stable `slug` (e.g. `--color-xp0hw7`) — that's the contract MCP-authored CSS must reference.

project_iduuidrequired: UUID of the target project (look it up with list_projects).

list_pagesRead-only

List pages in a project. `kind` filters to component-pages or work-pages; omit to get both.

project_iduuidrequired: UUID of the target project (look it up with list_projects).
kindstring: One of component / work

list_componentsRead-only

List components in a project. Pass `page_id` to scope to one page. Returns metadata only — call `get_component` for HTML/CSS.

project_iduuidrequired: UUID of the target project (look it up with list_projects).
page_idstring: Optional page filter

get_componentRead-only

Fetch a single component including its HTML and CSS source. CSS should reference token slugs (e.g. `var(--color-xp0hw7)`).

component_idstringrequired: Component identifier. Either the UUID or the stable slug (e.g. `--component-tw4tay`) — get_component / list_components return both.

list_work_categoriesRead-only

List work-page categories for a project.

project_iduuidrequired: UUID of the target project (look it up with list_projects).

list_project_membersRead-only

List members of a project (owner + invited collaborators).

project_iduuidrequired: UUID of the target project (look it up with list_projects).

Write tools · 7

Require a Read & write token. RLS still gates per-project edit access.

upsert_component_codeRead & write

Update a component's HTML and/or CSS. Omit a field to leave it untouched. The preview iframe remounts automatically on save.

component_idstringrequired: Component identifier. Either the UUID or the stable slug (e.g. `--component-tw4tay`) — get_component / list_components return both.
htmlstring: Component HTML body
cssstring: Component CSS (use token slugs)

create_componentRead & write

Create a new component on a page. Optional `html`/`css` seed the body; both default to empty. The component is placed at the next available grid slot.

page_idstringrequired: Page identifier. Either the UUID or the stable slug (e.g. `--page-erj7d2`) — list_pages returns both.
namestringrequired
htmlstring
cssstring

rename_componentRead & write

Rename a component. Slug never changes.

component_idstringrequired: Component identifier. Either the UUID or the stable slug (e.g. `--component-tw4tay`) — get_component / list_components return both.
namestringrequired

delete_componentRead & write

Delete a component permanently. Comments anchored to it are also wiped.

component_idstringrequired: Component identifier. Either the UUID or the stable slug (e.g. `--component-tw4tay`) — get_component / list_components return both.

create_pageRead & write

Create a component-page (kind=component, base components) or work-page (kind=work, design works). Pass `category_id` for work-pages to drop them in a specific group.

project_iduuidrequired: UUID of the target project (look it up with list_projects).
namestringrequired
kindstringrequired: One of component / work
category_iduuid

rename_pageRead & write

Rename a page. Slug never changes.

page_idstringrequired: Page identifier. Either the UUID or the stable slug (e.g. `--page-erj7d2`) — list_pages returns both.
namestringrequired

delete_pageRead & write

Delete a page (and every component on it).

page_idstringrequired: Page identifier. Either the UUID or the stable slug (e.g. `--page-erj7d2`) — list_pages returns both.

Token slugs

Design tokens carry stable random slugs like --color-xp0hw7, --font-erjdzy, or --spacing-mi5mow. These slugs never change, even when the token is renamed — the dashboard's preview iframe injects them as CSS variables, so referencing them from component CSS keeps light / dark theme switching working automatically. Always use the slug; never inline a hex value.