AI Agents

An MCP server that feeds coding agents Astralis's current component APIs, props, and theming, instead of guesses.

The problem it solves#

Ask an AI agent to write Astralis code and it may invent props, guess variants, and reach for APIs that don't exist, working from stale or second-hand knowledge instead of the real component contracts. The astralis-mcp server closes that gap: it exposes the live documentation over the Model Context Protocol, so the agent reads the same component docs you do (current props tables, demo source, and theming guides) at the moment it writes code.

Setup#

The fastest path is the CLI, which walks you through connecting one client:

npx astralis-cli connect-mcp

It supports Claude Code, Codex, Cursor, Claude Desktop, and Antigravity, and configures the one you pick: running its mcp add command, or writing its JSON config with your existing config backed up first.

Configure a client by hand#

Claude Code (and Codex) take an mcp add command directly:

claude mcp add astralis -- npx -y astralis-mcp

Any other MCP client takes the same server entry in its config file:

{
  "mcpServers": {
    "astralis": {
      "command": "npx",
      "args": ["-y", "astralis-mcp"]
    }
  }
}

What the agent gets#

The server exposes eight tools:

Tool	Returns
`list_components`	Every docs page (components and guides) with slug, title, description, section, and kind. The agent calls this first to discover what exists.
`get_component`	Full docs for one component: usage, the complete props table, accessibility notes, and runnable demo source.
`get_guide`	One guide page (installation, theming, tokens, and the rest) as markdown.
`search_docs`	Full-text search across all documentation, with a snippet around each hit.
`get_theming`	The complete theming reference: token system, dark mode, runtime brand color, the accent channel, and every design-token scale.
`list_blocks`	Every block (prebuilt page sections) with id, description, category, and the components it composes.
`get_block`	One block's metadata plus the complete source of its files, ready to write into a project.
`validate_code`	A verdict on Astralis TSX the agent wrote, checked against the design system's machine-readable spec: unknown components or parts, off-token values, invalid recipe values (`variant="primary"` is a Chakra habit, not a Button variant), dead `astralis:*` classes, broken compound anatomy, a11y mistakes. Errors name the valid alternatives, so the agent fixes its own code and validates again before showing it to you.

The last one is the difference between retrieval and verification: the other tools help the agent write against the system; validate_code proves what it wrote is inside the system. Validation is pure computation: it runs locally in the server process, uses no model, and prefers the spec of the astralis-ui version installed in your project. It is the same validator as astralis validate, so the rules the agent checks against are the ones you run in CI.

The spec itself (dist/system-spec.json in the installed package, or /system-spec.json on this site) also records each component's client field (none, leaf, or required), classified from the shipped module graph at build time. No tool returns it yet, but an agent that reads the spec can check whether a component ships client JavaScript before putting it in a Server Component.

How it stays current#

The server holds no copy of the docs. It reads them from this site's machine-readable endpoints, the same single pipeline that renders the pages you are reading now, so its answers can never drift from what's published. Ship a doc update and every connected agent sees it. If the site can't be reached, every tool returns an error that says so, never an answer the agent might trust, such as a real component reported as unknown.

When you're working on unpublished docs, point the server at a local build:

ASTRALIS_DOCS_URL=http://localhost:3000

Browsing agents#

An agent that browses the web rather than speaking MCP can read the docs directly: llms.txt is the index of every page, and llms-full.txt is the entire documentation inlined into one file.