Install

Agent integrations

MCP

Connect Pax to MCP-compatible agents with a local server, structured tools, and no hosted inference.

3 min readUpdated GitHubMcp

Pax ships an MCP server in @pax-sh/mcp with 23 tools covering project initialization, brand inspection, scene creation, validation, preview, quality checks, export, documentation retrieval, the effects and blocks registries, motion personalities, and deterministic demo video render. All tools run locally. Pax never hosts inference on your behalf.

Architecture

Agent (Cursor, Claude Code, Codex, OpenCode)
        |
        |  MCP over stdio / configured transport
        v
@pax-sh/mcp server  --->  paxfx CLI + packages (local)
        |
        +-- scenes, recipes, preview, export, docs

Installation

Install Pax from source

pnpm
git clone https://github.com/pax-design/pax.git
cd pax
corepack enable
pnpm install
pnpm build
pnpm paxfx install mcp

Usage

List available tools and inspect capabilities:

pnpm paxfx mcp tools
pnpm paxfx mcp serve

Example tool invocation shape (JSON varies by host):

{
  "tool": "create_scene",
  "arguments": {
    "recipe": "title-card",
    "params": { "title": "Launch" }
  }
}

Examples

create_scene

Create a scene from a released recipe, then validate before preview. The CLI equivalent writes under .pax/scenes/:

pnpm paxfx recipes run title-card
pnpm paxfx scene validate .pax/scenes/title-card.scene.json

validate

Run validation on a scene or compiled package before export.

preview

Start a local preview server for supported scene outputs. Preview remains on localhost.

retrieve_docs

Fetch documentation excerpts for in-editor agent context. Maps to public /docs/* content and llms.txt.

API Reference

MCP tools

All 23 tools, catalogued in packages/mcp/src/server.ts. Tools marked dangerous write files and require explicit agent approval in your host.

initialize_project

type: tool

Initialize a Pax project with .pax/ scaffolding and default config files. Idempotent.

inspect_brand

type: tool

Read the local brand profile from .pax/brand.json, deriving one from a repository scan when absent.

list_recipes

type: tool

List every runnable recipe with parameters, outputs, and tags.

create_scene

type: tool

Create a scene from a recipe id and parameters. Writes the scene JSON and a DOM preview under .pax/scenes/.

validate

type: tool

Validate a Pax scene or Lottie document and return structured issues.

preview

type: tool

Prepare a local preview document and return the studio command to serve it.

capture_frames

type: tool

Capture deterministic frames of a scene by sampling animation tracks. Writes SVG frames and a manifest under .pax/reports/frames/.

inspect_quality

type: tool

Run deterministic critic checks (motion, accessibility, overflow, performance budget) and write .pax/reports/check.json.

repair
dangerous

type: tool

Apply high-confidence repairs. May modify project files.

export
dangerous

type: tool

Export a scene to lottie, dotlottie, svg, react, vanilla, or capability-gated media formats. Writes .pax/exports/ with a reproducibility manifest.

retrieve_docs

type: tool

Search Pax documentation and return the most relevant excerpts.

capabilities

type: tool

Report Pax capabilities: tool count, export formats, effects, blocks, recipes, and local machine capabilities.

list_effects

type: tool

Browse the 25 canvas and WebGL effects with tiers, engines, and install commands.

get_effect

type: tool

Read one effect's props, performance tier, reduced-motion behavior, and install commands.

install_effect

type: tool

Return the shadcn install command for an effect and framework.

blocks_list

type: tool

List blocks registry assets, optionally filtered by kind or category.

blocks_search

type: tool

Search blocks registry assets by id, title, description, or category.

blocks_inspect

type: tool

Inspect one blocks asset: metadata, tier, dependencies, and install command.

blocks_add
dangerous

type: tool

Install a blocks asset into components/pax/<id>/ in the current project.

list_effects

type: tool

Browse Pax canvas and WebGL effects with tiers and framework support.

get_effect

type: tool

Read effect props, performance tiers, and install commands for one effect.

install_effect
dangerous

type: tool

Return the shadcn install command for an effect. May guide file writes in the host project.

blocks_list

type: tool

List Pax blocks registry assets. Accepts kind, category, and collection filters; summaries carry collection membership.

blocks_search

type: tool

Search Pax blocks registry assets by query with optional category and collection filters.

blocks_collections

type: tool

List curated collections (acid, editorial) with titles, descriptions, and member counts.

blocks_inspect

type: tool

Inspect a Pax blocks asset: metadata, dependencies, files, tier, and reduced-motion behavior.

motion_personalities

type: tool

List the five Pax motion personalities with durations, easing, stagger, and reduced-motion strategies.

blocks_add
dangerous

type: tool

Install a Pax block into components/pax/ in the host project.

demo_templates

type: tool

List demo video templates and presets.

render_demo
dangerous

type: tool

Render a demo document or template to video. Writes video artifacts.

Was this page helpful?

Edit this page

Answers are not recorded or transmitted. Pax has no telemetry.