MCP Server - LexQ Docs

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

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

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

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

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

Claude Desktop

macOS
Windows

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

{
  "mcpServers": {
    "lexq": {
      "command": "npx",
      "args": ["-y", "@lexq/cli", "serve", "--mcp"]
    }
  }
}

Edit %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "lexq": {
      "command": "npx",
      "args": ["-y", "@lexq/cli", "serve", "--mcp"]
    }
  }
}

Restart Claude Desktop after editing.

VS Code / Cursor

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

{
  "servers": {
    "lexq": {
      "command": "npx",
      "args": ["-y", "@lexq/cli", "serve", "--mcp"]
    }
  }
}

Windsurf / Gemini CLI / Other MCP Clients

Any MCP-compatible client that supports stdio transport:

{
  "mcpServers": {
    "lexq": {
      "command": "npx",
      "args": ["-y", "@lexq/cli", "serve", "--mcp"]
    }
  }
}

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

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 for the complete list with parameters. There is deliberately no PII reveal tool — revealing plaintext stays console-only and audited.

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.

Agent Best Practices

Read skills first. Have the agent read skills/lexq-shared/SKILL.md before any task.
Follow the standard workflow. Create group → version → facts → rules → dry-run → publish → deploy.
Always dry-run before publishing.
Handle the response envelope. Check result === "SUCCESS" — not success === true.
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

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.

stdio: 'API key not found'

Run lexq auth login to store your API key before starting the MCP server.

stdio: 'npx: command not found'

Ensure Node.js 18+ is installed. Run node --version to verify.

stdio: Tools aren't visible after setup

Restart your AI client (Claude Desktop, VS Code, etc.) after adding the MCP configuration.

Next Steps

Command Reference

Full list of all CLI commands mapped to MCP tools.

Policy Rules

Condition syntax and action types for rule creation.

Dry Run

Validate rules before publishing.

​What is MCP?

​Two Connection Methods

​Cloud — Claude.ai Custom Integration

​Setup

​Architecture

​Local — stdio MCP Server

​Prerequisites

​Claude Desktop

​VS Code / Cursor

​Windsurf / Gemini CLI / Other MCP Clients

​Available Tools

​Agent Best Practices

​Troubleshooting

​Next Steps

Command Reference

Policy Rules

Dry Run

What is MCP?

Two Connection Methods

Cloud — Claude.ai Custom Integration

Setup

Architecture

Local — stdio MCP Server

Prerequisites

Claude Desktop

VS Code / Cursor

Windsurf / Gemini CLI / Other MCP Clients

Available Tools

Agent Best Practices

Troubleshooting

Next Steps