# @sentientui/mcp

[![smithery badge](https://smithery.ai/badge/carlos-sanchez/sentientUI)](https://smithery.ai/servers/carlos-sanchez/sentientUI)

MCP server for [SentientUI](https://sentient-ui.com) — 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:
```bash
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:
```json
{
  "mcpServers": {
    "sentientui": {
      "command": "npx",
      "args": ["-y", "@sentientui/mcp"],
      "env": {
        "SENTIENTUI_API_KEY": "sk_your_key_here"
      }
    }
  }
}
```

**Cursor** — `~/.cursor/mcp.json`:
```json
{
  "mcpServers": {
    "sentientui": {
      "command": "npx",
      "args": ["-y", "@sentientui/mcp"],
      "env": {
        "SENTIENTUI_API_KEY": "sk_your_key_here"
      }
    }
  }
}
```

**VS Code + Copilot** — `.vscode/mcp.json`:
```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:

```bash
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` | Per-(component, variant) conversion with its sample, plus the server's evidence verdict vs the baseline (windowed rates: range 7d/30d/90d/all or from/to; default 7d; the verdict judges the windowed rate, with all-time reliability reported separately — all-time only on APIs without window evidence) |
| `get_insights` | Ranked measured findings with tier and sample (low samples flagged), plus AI narrations marked as unmeasured |
| `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 (windowed; default 30d), plus all-time per-variant rates with their n |
| `list_goals` | Defined goals (id, role, event, status) — includes goals with no conversions yet, so agents can wire a dashboard-defined goal into code |
| `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` | Ready-to-paste test code (RTL, mock server, Playwright/Cypress) that forces one of the component's real variants |
| `get_variant_brief` | Evidence-driven brief for writing a new **code-native** variant: per-arm rates with n and evidence verdicts, audience, measured findings, an evidence state (with a best-practice fallback while nothing is decided), 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 |
| `get_cell_matrix` | The "Who sees what" matrix: which visitor types have an AI-generated version live in each personalizable region, with traffic share and auto-fill status |
| `get_cell_detail` | One cell's story: the generated option, why it was written (stored rationale), and how it performs vs the original |
| `generate_cell` | Queue AI generation of a version for one (visitor type, region) cell — brand-locked, live in under a minute (paid plan) |

> **Generated versions.** An `<Adaptive id="…">` that wraps your original as children (no `variants`) registers as a personalizable region once it is mounted and deployed. Its versions per visitor type are written in SentientUI — inspect and fill them with `get_cell_matrix`, `get_cell_detail`, and `generate_cell` — with no code change or redeploy.
>
> **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 each variant's rate with its sample and the server's evidence verdict, the audience, measured findings, and an evidence-state assessment — then your AI assistant writes a new on-brand variant directly into your code (which auto-registers on deploy). While nothing is decided, 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)