@experia-labs/design-mcp

Model Context Protocol server for editing Experia tenant landing pages and event landing pages through an AI agent (Claude Desktop, Claude Code, Cursor, etc.).

"Move the testimonials section above the gallery, and change the hero headline to 'Welcome home.'" → done.

What it does

Exposes a handful of tools the agent can call on your behalf:

• list_organizations, list_events — discover what you can edit
• get_tenant_landing_page, update_tenant_landing_section, update_tenant_global, reset_tenant_landing_page
• get_event_page, update_event_page_draft, add_event_block, update_event_block, reorder_event_blocks, delete_event_block
• publish_event_page, list_event_page_versions, revert_event_page
• list_event_block_types, describe_event_block_type — the block palette

Every mutation goes through the same authenticated organizer API the dashboard uses — there are no shortcuts. Event-page mutations write to the draft only; you have to call publish_event_page to make the changes go live.

Setup

1. Issue an API key

Go to /dashboard/settings/api-keys in your org and click Issue API Key. Pick the scopes the agent should have:

• landing-page:read, landing-page:write — tenant homepage
• event-page:read, event-page:write, event-page:publish — event pages

The dashboard will show you the plaintext token exactly once (format: eok_xxxxxxxx_…). Copy it — you cannot retrieve it later. Revoke it any time from the same page.

2. Wire the server into your AI client

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "experia-design": {
      "command": "npx",
      "args": ["-y", "@experia-labs/design-mcp"],
      "env": {
        "EXPERIA_API_URL": "https://api.experialabs.com/api/v1",
        "EXPERIA_API_KEY": "eok_xxxxxxxx_…"
      }
    }
  }
}

Restart Claude Desktop.

Claude Code

claude mcp add experia-design \
  --env EXPERIA_API_URL=https://api.experialabs.com/api/v1 \
  --env EXPERIA_API_KEY=eok_xxxxxxxx_… \
  -- npx -y @experia-labs/design-mcp

Cursor

Add to ~/.cursor/mcp.json (or project-local .cursor/mcp.json):

{
  "mcpServers": {
    "experia-design": {
      "command": "npx",
      "args": ["-y", "@experia-labs/design-mcp"],
      "env": {
        "EXPERIA_API_URL": "https://api.experialabs.com/api/v1",
        "EXPERIA_API_KEY": "eok_xxxxxxxx_…"
      }
    }
  }
}

3. Try it

In your AI client, ask something like:

Read my tenant landing page, change the hero headline to "Welcome home," and move the testimonials section above the gallery.

The agent will:

1. Call list_organizations (and pick the only one — keys are single-org)
2. Call get_tenant_landing_page
3. Call update_tenant_landing_section with the new hero config
4. Call update_tenant_global with the reordered sectionOrder array

For event pages:

On event "Friday Night Lights", swap out the HERO block for an EDITORIAL_HERO with the tagline "Game day, every day," then publish.

The agent will use list_events, get_event_page, update_event_block (or delete_event_block + add_event_block), and finally publish_event_page.

Safety

• Draft-by-default for event pages. Mutations on event pages don't go live until you explicitly ask the agent to publish.
• Tenant pages go live immediately. There is no draft layer yet for the tenant homepage. If you want to preview before committing, use a separate test org. (A preview layer is planned for v1.1.)
• Revoke any time. Visit /dashboard/settings/api-keys and click revoke. The key stops working immediately.
• Scopes are enforced server-side. A key issued with only landing-page:write can't touch event pages, etc.
• Image uploads are NOT supported by this MCP. Tools accept URLs only. Upload images via the dashboard, then reference their URLs.

Local development

cd creatoros-api/packages/design-mcp
npm install
npm run build
npm run verify

# Smoke test against a local API
EXPERIA_API_URL=http://localhost:4001/api/v1 \
EXPERIA_API_KEY=eok_…local-key… \
npx @modelcontextprotocol/inspector node dist/cli.js

Limitations & future work

• Tenant landing page has no draft / preview mode (mutations go live).
• No image generation / upload (out of scope; reference existing URLs).
• No custom CSS editing on EventTheme.customCss (security review needed).
• Motion presets exist in the data model but aren't yet wired to the studio.
• The block-type registry mirror is hand-maintained; new block types added in creator-os-fe/src/components/event-page/blocks/registry.ts need to be reflected here.