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 loyaltyTier=‘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 22+ 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, dataset file upload (local only)
Profile	group latency overview, single-rule detail
History	list, get, stats
Replay	decision, start, status, list, cancel
Provenance	lineage get, PII reveal audits
Logs	list, get
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 toolset, except that only the local server has lexq_dataset_upload_file (below); see the Command Reference for the complete list with parameters. There is deliberately no PII reveal tool — revealing plaintext stays console-only and audited. Failure logs can be listed and read, but resolving or ignoring one is console-only: an organization admin does it under Management → Failure Logs.

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.

Dataset files

lexq_dataset_upload_file uploads a CSV or JSON file from the computer the local server runs on. The server reads the file from disk, so its content never passes through the conversation. The cloud server does not have this tool: there, it would read files on LexQ’s server, not on your computer.

file is an absolute path. A leading ~/ stands for your home directory.
The name must end in .csv or .json. A symbolic link is followed, and the file it points to must end in .csv or .json too.
A .json file must hold an array of records. The engine also accepts a single object such as {"facts": {...}}, but this tool refuses it; wrap it in [ ] first.
Size and encoding limits are the same as for any dataset upload.

It returns the stored path and a dataset block to pass to lexq_simulation_start. lexq_dataset_upload, which both servers have, sends the content inside the tool call, so it suits small datasets, and the cloud server limits the size of a request. For a larger file on Claude.ai, upload it in the Console or with lexq analytics dataset upload and give the agent the returned path.

The agent chooses the path. Instructions hidden in a web page or a file it has read can make it upload a different .csv or .json file than the one you meant. When your client asks you to approve the call, check the path.

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. Register every action target (the targetVar of SET_FACT and MUTATE_FACT) before saving the rule; otherwise the save fails with ACT-032. For a key the rule only reads, 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.
Check the rules a value domain change lists. When lexq_facts_update changes a fact’s value domain and rules compare the fact with values the new domain does not accept, the result ends with a warning that lists them by version. The update is already saved. Fix the listed conditions in drafts, or in a clone of the deployed version, before publishing (details).
Read the group before rolling back. lexq_deploy_rollback requires expectedCurrentVersionId and expectedCurrentDeploymentId. Pass the currentVersionId and currentDeploymentId that lexq_groups_get returned. A 409 with P-062 or P-063 means the group changed after that read: read it again and confirm with the user before retrying (details).

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 22+ 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

​Dataset files

​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

Dataset files

Agent Best Practices

Troubleshooting

Next Steps