> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lexq.io/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Server

> Connect Claude, VS Code, Cursor, and other AI tools to LexQ via MCP.

## What is MCP?

The **Model Context Protocol (MCP)** is an open standard for connecting AI assistants to external tools and data sources. LexQ provides a **full MCP toolset** covering the entire policy lifecycle.

When connected, AI agents can manage your policies directly:

* "Create a discount rule for VIP customers"
* "Dry-run this version with loyalty\_tier='PLATINUM'"
* "Run an Impact Simulation comparing v3 and v4"

## Two Connection Methods

| Method                         | Best For                        | Setup                 | Auth                  |
| ------------------------------ | ------------------------------- | --------------------- | --------------------- |
| **Cloud (Custom Integration)** | Claude.ai web/mobile            | URL only — no install | OAuth (automatic)     |
| **Local (stdio)**              | Claude Desktop, VS Code, Cursor | npm install required  | API Key (config file) |

***

## Cloud — Claude.ai Custom Integration

The fastest way to connect. No installation, no terminal — just a URL.

### Setup

1. Go to **Claude.ai → Settings → Connectors**
2. Click **Add Custom Connector**
3. Enter: `https://mcp.lexq.io`
4. Claude opens the LexQ login page
5. Sign in with **Google**, **email/password**, or paste an **API Key** directly
6. Select or generate an API Key → click **Authorize**
7. Done — the full toolset is now available in all conversations

<Info>
  Claude.ai handles the full OAuth flow automatically. Your API Key is securely stored as a Bearer token — no config files needed.
</Info>

### Architecture

```
Claude.ai ──► mcp.lexq.io (OAuth + Streamable HTTP)
                   │
                   ▼
          LexQ Engine (api.lexq.io)
```

***

## Local — stdio MCP Server

For desktop AI tools that support local MCP servers.

### Prerequisites

1. **Node.js 18+** installed
2. Run `lexq auth login` once to store your API key

### Claude Desktop

<Tabs>
  <Tab title="macOS">
    Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:

    ```json theme={null}
    {
      "mcpServers": {
        "lexq": {
          "command": "npx",
          "args": ["-y", "@lexq/cli", "serve", "--mcp"]
        }
      }
    }
    ```
  </Tab>

  <Tab title="Windows">
    Edit `%APPDATA%\Claude\claude_desktop_config.json`:

    ```json theme={null}
    {
      "mcpServers": {
        "lexq": {
          "command": "npx",
          "args": ["-y", "@lexq/cli", "serve", "--mcp"]
        }
      }
    }
    ```
  </Tab>
</Tabs>

Restart Claude Desktop after editing.

### VS Code / Cursor

Create `.vscode/mcp.json` (or `.cursor/mcp.json`):

```json theme={null}
{
  "servers": {
    "lexq": {
      "command": "npx",
      "args": ["-y", "@lexq/cli", "serve", "--mcp"]
    }
  }
}
```

### Windsurf / Gemini CLI / Other MCP Clients

Any MCP-compatible client that supports stdio transport:

```json theme={null}
{
  "mcpServers": {
    "lexq": {
      "command": "npx",
      "args": ["-y", "@lexq/cli", "serve", "--mcp"]
    }
  }
}
```

<Info>
  The stdio server reads the API key from `~/.lexq/config.json`. Run `lexq auth login` before starting.
</Info>

***

## Available Tools

| Domain                    | Tools                                                                          |
| ------------------------- | ------------------------------------------------------------------------------ |
| **Status**                | `lexq_whoami`                                                                  |
| **Groups**                | CRUD + A/B test (start, stop, adjust)                                          |
| **Versions**              | CRUD + clone                                                                   |
| **Rules**                 | CRUD + reorder + toggle                                                        |
| **Facts**                 | CRUD + action metadata + unregistered                                          |
| **Domain Templates**      | list, preview, apply                                                           |
| **Deploy**                | publish, live, rollback, undeploy, history, detail, overview, deployable, diff |
| **Analytics**             | dry-run, compare, requirements, simulation, dataset upload/template            |
| **Profile**               | group latency overview, single-rule detail                                     |
| **History**               | list, get, stats                                                               |
| **Replay**                | decision, start, status, list, cancel                                          |
| **Provenance**            | lineage get, PII reveal audits                                                 |
| **Integrations**          | list, get, save, delete, config-spec                                           |
| **Logs**                  | list, get, action, bulk-action                                                 |
| **Webhook Subscriptions** | list, get, save, delete, test                                                  |

Tool names share a consistent `lexq_` namespace grouped by resource — for example `lexq_rules_create`, `lexq_versions_clone`, `lexq_deploy_rollback`. Both connection methods expose the same full toolset; see the [Command Reference](/cli/commands) for the complete list with parameters. There is deliberately no PII reveal tool — revealing plaintext stays console-only and audited.

<Warning>
  LexQ exposes a large MCP toolset. Some MCP clients cap the number of active tools they send to the model, or degrade as the tool count grows — tools beyond a client's limit may be dropped, sometimes with only a warning. If your client reports a tool limit, or the agent can't find a tool you expect, disable the LexQ tools you don't currently need in your client's MCP settings.
</Warning>

## Agent Best Practices

1. **Read skills first.** Have the agent read `skills/lexq-shared/SKILL.md` before any task.
2. **Follow the standard workflow.** Create group → version → facts → rules → dry-run → publish → deploy.
3. **Always dry-run before publishing.**
4. **Handle the response envelope.** Check `result === "SUCCESS"` — **not** `success === true`.
5. **Register facts you reference.** When a rule references a key that isn't a Fact Definition, the `create`/`update` response includes a non-blocking warning naming it. Register it with `lexq_facts_create` to enable type validation, or call `lexq_facts_unregistered` to audit the whole version.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Claude.ai: 'Authorization with the MCP server failed'">
    Remove the connector in Settings → Connectors, then re-add `https://mcp.lexq.io`. Ensure you complete the login and API key selection steps.
  </Accordion>

  <Accordion title="stdio: 'API key not found'">
    Run `lexq auth login` to store your API key before starting the MCP server.
  </Accordion>

  <Accordion title="stdio: 'npx: command not found'">
    Ensure Node.js 18+ is installed. Run `node --version` to verify.
  </Accordion>

  <Accordion title="stdio: Tools aren't visible after setup">
    Restart your AI client (Claude Desktop, VS Code, etc.) after adding the MCP configuration.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Command Reference" icon="terminal" href="/cli/commands">
    Full list of all CLI commands mapped to MCP tools.
  </Card>

  <Card title="Policy Rules" icon="list-check" href="/guides/policy-rules">
    Condition syntax and action types for rule creation.
  </Card>

  <Card title="Dry Run" icon="flask-vial" href="/guides/dry-run">
    Validate rules before publishing.
  </Card>
</CardGroup>