Skip to main content

​
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

MethodBest ForSetupAuth
Cloud (Custom Integration)Claude.ai web/mobileURL only — no installOAuth (automatic)
Local (stdio)Claude Desktop, VS Code, Cursornpm install requiredAPI 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
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

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

​
Claude Desktop

Edit ~/Library/Application Support/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

DomainTools
Statuslexq_whoami
GroupsCRUD + A/B test (start, stop, adjust)
VersionsCRUD + clone
RulesCRUD + reorder + toggle
FactsCRUD + action metadata
Domain Templateslist, preview, apply
Deploypublish, live, rollback, undeploy, history, detail, overview, deployable, diff
Analyticsdry-run, compare, requirements, simulation, dataset upload/template
Historylist, get, stats
Integrationslist, get, save, delete, config-spec
Logslist, get, action, bulk-action
Webhook Subscriptionslist, 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.
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

  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.

​
Troubleshooting

Remove the connector in Settings → Connectors, then re-add https://mcp.lexq.io. Ensure you complete the login and API key selection steps.
Run lexq auth login to store your API key before starting the MCP server.
Ensure Node.js 18+ is installed. Run node --version to verify.
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.