@sentientui/mcp

MCP server for SentientUI — gives AI agents in Claude Code, Cursor, and Copilot direct access to your experiment data and management actions.

Quick start

Prefer no key? You can skip local install entirely and connect your assistant to the hosted endpoint by URL with an OAuth sign-in — this is the only way to use SentientUI from web/app assistants (claude.ai, ChatGPT):

https://api.sentient-ui.com/mcp

Claude Code: claude mcp add --transport http sentientui https://api.sentient-ui.com/mcp. For stdio-only clients: npx mcp-remote https://api.sentient-ui.com/mcp. The rest of this README covers the local, key-based install below.

1. Get a server key

Dashboard → Project → Settings → API key → Server key → Generate (requires Starter or Growth plan).

2. Add to your AI assistant

Claude Code — one command:

claude mcp add sentientui -e SENTIENTUI_API_KEY=sk_your_key_here -- npx -y @sentientui/mcp

Or check a project-scoped .mcp.json into your repo:

{
  "mcpServers": {
    "sentientui": {
      "command": "npx",
      "args": ["-y", "@sentientui/mcp"],
      "env": {
        "SENTIENTUI_API_KEY": "sk_your_key_here"
      }
    }
  }
}

Cursor — ~/.cursor/mcp.json:

{
  "mcpServers": {
    "sentientui": {
      "command": "npx",
      "args": ["-y", "@sentientui/mcp"],
      "env": {
        "SENTIENTUI_API_KEY": "sk_your_key_here"
      }
    }
  }
}

VS Code + Copilot — .vscode/mcp.json:

{
  "servers": {
    "sentientui": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@sentientui/mcp"],
      "env": {
        "SENTIENTUI_API_KEY": "sk_your_key_here"
      }
    }
  }
}

3. Restart your IDE. The server connects at startup.

Demo mode

No account? Run without an API key:

npx @sentientui/mcp

A sandboxed demo token is provisioned automatically — 10 calls/month, read-only (write tools require an account with an sk_ key), no sign-up required. The token is cached in ~/.config/sentientui/mcp-anon.json.

Tools

| Tool | What it does | |------|-------------| | list_projects | List all projects in the account | | create_project | Create a new project and return its pk_ public key (account login required — not usable with an sk_ project key or demo token) | | get_project_stats | Events, sessions, agent calls, and health status | | list_components | All adaptive components with variant counts | | get_variant_performance | CVR, momentum, and impressions per variant (7d vs prior 7d) | | get_insights | AI-generated narrator observations and advisor recommendations | | refresh_insights | Trigger fresh AI insight generation | | get_persona_breakdown | Visitor cluster distribution with reliability scores | | get_goal_funnel | Goal hit counts and conversion rates per variant | | list_guardrail_events | Variants auto-paused by the guardrail (last 24h) | | get_layout_stats | Per-persona section layout rankings and reward weights | | get_integration_guide | SentientUI adaptive-ladder setup guide (static — same for every project) | | get_test_brief | What to test and how, for the project's current state | | get_variant_brief | Insight-driven brief for writing a new code-native variant: performance, audience, insights, data-sufficiency (with a best-practice fallback when there's no data yet), and step-by-step code instructions | | create_variant | Create a no-code (managed) text variant (Starter+) — fallback for text-only variants without a code change | | pause_variant | Pause a variant to stop traffic assignment |

Code-native vs no-code variants. Variants you declare in your app (<Adaptive variants={{…}}>) register automatically the first time the SDK requests an assignment after you deploy — they go live immediately and need no create_variant call. Use create_variant only for no-code variants whose content is stored in SentientUI and rendered without a code change; these start as drafts you activate from the dashboard.

Optimizing a component? Call get_variant_brief first. It returns the component's performance, audience, insights, and a data-sufficiency assessment — then your AI assistant writes a new on-brand variant directly into your code (which auto-registers on deploy). When there's no data yet, the brief falls back to best-practice priors for your project's context type so the assistant still makes a sensible change.

Example prompts

• "What projects do I have?"
• "Show me the CVR trends for the hero banner this week"
• "Are any variants paused by the guardrail right now?"
• "What do the AI insights say about what changed this week?"
• "Refresh insights for project X"
• "Optimize my hero CTA — pull the brief and add a new variant in the code"
• "Create a new variant called 'short-copy' for the pricing CTA"

Configuration

| Environment variable | Default | Description | |----------------------|---------|-------------| | SENTIENTUI_API_KEY | — | Your sk_... server key. Required (or demo mode activates). | | SENTIENTUI_API_URL | https://api.sentient-ui.com | Override for staging or a custom API endpoint. |

Auth model

The server key you provide is passed as a Bearer token on every call to the SentientUI management API. It is scoped to your account — all projects you own are accessible. Keys are never logged or stored by the MCP package; they exist only in the process environment.

Server keys start with sk_ (not pk_). Public keys (pk_) are for the React SDK only and will be rejected by the management API.

AI agent context

AGENTS.md (included in this package) gives your AI assistant deeper context about SentientUI concepts, tool ordering, and common pitfalls. Wire it up once and it applies to every conversation.

| Assistant | How to use | |-----------|-----------| | Claude Code | Copy to ~/.claude/skills/sentientui/SKILL.md | | Cursor | Copy to .cursor/rules/sentientui.mdc | | GitHub Copilot | Append to .github/copilot-instructions.md | | Other | Paste into your assistant's system prompt |

Requirements

• Node.js 18+
• A SentientUI account (or use demo mode)