Skip to content

Connect MCP clients

Goal

Let an AI assistant (Claude Code, Cursor, Claude Desktop, or any other MCP-aware tool) talk to your Qualytics instance directly. The assistant can then list datastores, draft checks, summarize anomalies, and take other actions on your behalf, using natural language as the interface and the Qualytics API as the backend.

Permissions

The MCP server uses the same authentication as your CLI: whatever role and team permissions your token has, the assistant inherits.

Layer Minimum Notes
User role Member The assistant can only do what your token can do. For mutations (create/update), the same Author / Editor team permissions apply.
Team permission Reporter for read-only assistance Bump to Author / Editor if you want the assistant to make changes.

Use a dedicated, scoped token

Don't point the assistant at a Manager/Admin token unless you actively need it. A Reporter-only token gives the assistant safe read access while preventing accidental writes from a typo in a prompt.

Prerequisites

  • The CLI is installed and authenticated.
  • An MCP-aware client. The setup snippets below cover Claude Code; the pattern is similar in Claude Desktop and Cursor.

CLI workflow

graph LR
    Claude[Claude Code / Cursor] -->|MCP stdio| Server[qualytics mcp serve]
    Server -->|HTTPS| API[Qualytics API]

Run the MCP server (stdio, default)

qualytics mcp serve

This is what an MCP client launches in the background; you don't usually run it manually.

Run as a network-accessible HTTP server

qualytics mcp serve --transport streamable-http --host 0.0.0.0 --port 8000

Useful when the assistant runs on a different machine than the CLI.

Wire into Claude Code

Add to ~/.claude.json:

{
  "mcpServers": {
    "qualytics": {
      "command": "qualytics",
      "args": ["mcp", "serve"]
    }
  }
}

Restart Claude Code. The Qualytics tools become available the next time you start a conversation.

Wire into Cursor

Cursor follows the same pattern; add the same mcpServers block to Cursor's MCP configuration. See the Cursor docs for the exact location, which has changed between versions.

Behind the scenes

The MCP server proxies the assistant's tool calls to the Qualytics API. Every tool call is authenticated with your CLI token.

Action Method Path
List datastores GET /api/datastores
Get a single datastore GET /api/datastores/{id}
List anomalies GET /api/anomalies
Create a check POST /api/quality-checks
Run an operation POST /api/operations/run

The full surface is whatever the deployment exposes; the MCP server enumerates available tools at startup.

Python equivalent

MCP is a tool-use protocol, not a REST API; there isn't a Python "equivalent" in the same sense as the other examples. If you want an LLM-style integration in Python, you'd typically:

  1. Use Anthropic's SDK (or any LLM client) to drive a conversation.
  2. Define your own tools that wrap the Qualytics REST API (see the Python sections of every other example page).
  3. Hand those tool definitions to the model.

A minimal sketch:

from anthropic import Anthropic
import httpx, os

QUAL = httpx.Client(
    base_url=os.environ["QUALYTICS_URL"].rstrip("/"),
    headers={"Authorization": f"Bearer {os.environ['QUALYTICS_TOKEN']}"},
    timeout=30.0,
)

def list_datastores():
    return QUAL.get("/api/datastores").json()

# Hand list_datastores (and others) to the LLM as tools.
client = Anthropic()
# ... build a tool-using conversation; route tool calls to QUAL.* helpers.

For most teams, qualytics mcp serve plus an MCP-native client is much less work than rolling your own.

Variations and advanced usage

Per-project tokens

Different projects can use different tokens. Set QUALYTICS_URL and QUALYTICS_TOKEN as environment variables in the MCP server invocation:

{
  "mcpServers": {
    "qualytics-dev": {
      "command": "qualytics",
      "args": ["mcp", "serve"],
      "env": {
        "QUALYTICS_URL":   "https://dev.qualytics.io",
        "QUALYTICS_TOKEN": "${DEV_QUALYTICS_TOKEN}"
      }
    },
    "qualytics-prod": {
      "command": "qualytics",
      "args": ["mcp", "serve"],
      "env": {
        "QUALYTICS_URL":   "https://prod.qualytics.io",
        "QUALYTICS_TOKEN": "${PROD_QUALYTICS_TOKEN}"
      }
    }
  }
}

Run on a remote host

For shared environments, run qualytics mcp serve --transport streamable-http on a known host and point clients at it. Mind the network exposure: the server has whatever permissions the token has.

Sample prompts

Once wired in, useful prompts: - "Which datastores have the most active anomalies this week?" - "Draft a satisfiesExpression check for total >= 0 on the orders table in datastore 42." - "Summarize the anomalies for check ID 555 over the last 30 days."

Troubleshooting

Symptom Likely cause Fix
Assistant says "no Qualytics tools available" The MCP server isn't running, or the client config is wrong In Claude Code, run /mcp or restart and check the status panel.
Server starts but tools fail with 401 Token expired qualytics auth login to refresh.
HTTP transport works locally but not remotely Listening on 127.0.0.1, not 0.0.0.0 Use --host 0.0.0.0 for network access (and make sure the firewall allows it).
Tool calls are slow Network latency to the Qualytics API The MCP server adds minimal overhead; latency is dominated by the upstream HTTPS request. Run the server closer to the API.
Assistant invents a tool that doesn't exist The model is hallucinating The MCP server enumerates available tools; if the assistant tries something that fails, it usually corrects on retry. Pin the model or rephrase the prompt.