Guides

Use with Claude, Cursor and other AI apps (MCP)

Connect FactQL to Claude, Cursor, VS Code or any app that speaks MCP, and the assistant can ask questions of your data and get back the answer, the SQL that ran and the rows. Use the hosted server and sign in with your FactQL account, or run the open-source factql-mcp package yourself.

Before you start

A FactQL account, with data in your workspace: a connected database or an uploaded file.
Pick how to connect. The hosted server needs nothing installed and works in web and mobile apps. Running it yourself suits desktop apps when you'd rather keep an API key on your own machine.

Hosted server

One address for every app:

MCP server URL

https://api.factql.ai/mcp

When you add it, the app opens a FactQL sign-in page. Sign in, check the app's name, and click Allow. Its questions then run as you, with your role and your workspaces, and they appear together as one chat in your FactQL history. To disconnect an app, go to Settings → Connected apps on factql.ai.

Claude (web, desktop and mobile)

On claude.ai, open Settings → Connectors → Add custom connector. Name it FactQL, paste the URL, then click Connect and sign in. A connector added on the web also works in the Claude desktop and mobile apps.

Claude Code

Terminal

claude mcp add --transport http factql https://api.factql.ai/mcp

Then run /mcp in Claude Code and choose FactQL to sign in.

Cursor

Add this to the MCP section of Cursor's settings, then sign in when Cursor asks.

mcp.json

{
  "mcpServers": {
    "factql": { "url": "https://api.factql.ai/mcp" }
  }
}

VS Code

Add this to .vscode/mcp.json (or run MCP: Add Server and choose HTTP). VS Code asks you to sign in the first time a tool runs.

.vscode/mcp.json

{
  "servers": {
    "factql": { "type": "http", "url": "https://api.factql.ai/mcp" }
  }
}

Other apps

Any app that can add a remote MCP server over Streamable HTTP can use the URL, for example Microsoft Copilot Studio. Choose OAuth sign-in: FactQL publishes its OAuth details at the standard discovery address and lets apps register themselves, so there is no client ID or secret to copy.

With an API key instead of signing in

Where an app lets you set a request header, send an API key as Authorization: Bearer fl_live_.... Questions then run as the key, with every API-key rule applying. An ask-only key is enough. In Claude Code:

Terminal

claude mcp add --transport http factql https://api.factql.ai/mcp \
  --header "Authorization: Bearer fl_live_..."

Run it yourself

factql-mcp is open source (MIT) on GitHub and published on PyPI. It runs on your machine and talks to FactQL with an API key. You need:

An API key. An ask-only key is enough, and is the safer choice for a tool that runs on someone's laptop.
uv installed, which gives you uvx. It downloads and runs the server; there is nothing else to install. If you prefer pip, pip install factql-mcp and use factql-mcp as the command.

Claude Desktop and Cursor

Add this to the mcpServers section of your client's MCP config. In Claude Desktop that is Settings → Developer → Edit Config; in Cursor, the MCP section of its settings. Restart the client afterwards.

mcpServers

{
  "mcpServers": {
    "factql": {
      "command": "uvx",
      "args": ["factql-mcp"],
      "env": { "FACTQL_API_KEY": "fl_live_..." }
    }
  }
}

Claude Code

Terminal

claude mcp add factql -e FACTQL_API_KEY=fl_live_... -- uvx factql-mcp

Settings

When you run it yourself, the server reads these environment variables.

Environment variables

FACTQL_API_KEYstring · required

Your API key. The server stops at startup if it is missing.

FACTQL_WORKSPACE_IDstring

The workspace to ask in, when your key can see more than one. The assistant can also pick one itself with whoami.

FACTQL_END_USER_IDstring

Who is asking, so their history stays separate. Default mcp:<your OS user name>.

FACTQL_BASE_URLstring

The API address. Default https://api.factql.ai.

Tools

What the assistant can call

whoami()tool

What the key can see: the tenant, the plan, and the workspaces it may ask in.

ask(question, workspace_id?, locale?)tool

Asks a question in plain English. Returns the answer, the SQL that ran and up to 50 rows. Set locale to en-GB or en-US for the wording of the answer.

Both servers have the same two tools. Treat each ask as standing alone: the assistant carries the conversation, so a follow-up question should say what it refers to, such as “revenue for the North region” rather than “and the North?”. When you sign in to the hosted server, its questions are also saved together as one chat in your FactQL history.

What comes back

A normal answer has result: "success", the answer in explanation, the sql, and the rows. When the query returns more than 50 rows, the first 50 are sent with a note saying how many there were.

ask → success

{
  "result": "success",
  "explanation": "East: 555 · North: 550 · South: 540",
  "sql": "SELECT region, SUM(quantity*unit_price) AS total_revenue FROM sales GROUP BY region ORDER BY total_revenue DESC",
  "columns": ["region", "total_revenue"],
  "rows": [["East", 555], ["North", 550], ["South", 540]],
  "row_count": 3
}

When FactQL can't verify an answer, it gives none rather than guess. The server returns result: "declined" with the reason. This is deliberate, not a broken tool, and the note tells the assistant not to make up a figure of its own.

ask → declined

{
  "result": "declined",
  "reason": "I couldn't find a reliable way to answer this from your data. ...",
  "note": "FactQL could not verify an answer, so it gave none rather than guess. ..."
}

result: "needs_clarification" means the question was too vague. The assistant should ask you for the missing detail and try again.

Troubleshooting

Common problems

FACTQL_API_KEY is not setstartup

The server can't start without a key. Add it to the env block of your MCP config.

HTTP 401error

The key is wrong or has been revoked: create a new one. With hosted sign-in, the app was disconnected, unused for 30 days, or you were removed from the company: connect it again.

The sign-in page says the request expiredhosted

A sign-in request lasts 10 minutes. Start connecting again from the app.

HTTP 403 email_unverifiederror

A new account's keys work only after you open the link in the verification email.

HTTP 402error

The spend cap for the month is reached. See Limits and errors.

The server is also listed in the official MCP Registry as io.github.factql/factql-mcp. Report problems on GitHub.