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.

Most clients do not need the CLI

Every Qualytics deployment exposes its MCP server at https://your-qualytics-instance.qualytics.io/api/mcp/, and clients such as Claude Desktop, Claude Code, and Cursor connect to it directly with a Personal API Token. Follow Connecting External AI Clients for that setup. This page covers the CLI bridge, qualytics mcp serve, for the cases where you want the assistant to reuse your CLI login or the client only supports command-based (stdio) MCP servers.

Permissions

The bridge 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 snippets below cover Claude Code; the pattern is similar in other clients that support command-based MCP servers.

CLI workflow

graph LR
    Client[Claude Code / Cursor] -->|MCP stdio| Bridge[qualytics mcp serve]
    Bridge -->|HTTPS| MCP[Qualytics MCP server at /api/mcp/]

Run the bridge (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

Register the bridge as a command-based server:

claude mcp add qualytics -- qualytics mcp serve

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

Wire into other clients

Register a command-based (stdio) MCP server whose command is qualytics and whose arguments are mcp serve. Each client stores this in a different place; check its documentation.

Behind the scenes

The bridge forwards every tool call to the MCP server built into your Qualytics deployment, adding your CLI token to each request. The tool list is whatever your deployment exposes, so it stays current with your Qualytics version. The bridge adds one local tool, auth_status, which reports the CLI's configured URL and token expiry.

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, an MCP-native client pointed at the deployment's MCP endpoint is much less work than rolling your own.

Variations and advanced usage

Per-project tokens

Different projects can use different tokens. The QUALYTICS_URL and QUALYTICS_TOKEN environment variables take precedence over the saved CLI login, so register one bridge per environment with its own variables. Include the /api suffix in QUALYTICS_URL: the bridge appends /mcp to the value as given, so a bare hostname would target the wrong path.

claude mcp add -e QUALYTICS_URL=https://dev.qualytics.io/api -e QUALYTICS_TOKEN=$DEV_QUALYTICS_TOKEN qualytics-dev -- qualytics mcp serve

claude mcp add -e QUALYTICS_URL=https://prod.qualytics.io/api -e QUALYTICS_TOKEN=$PROD_QUALYTICS_TOKEN qualytics-prod -- qualytics mcp serve

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 bridge 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 bridge isn't registered, or the client config is wrong In Claude Code, run /mcp or restart and check the status panel.
Bridge starts but tools fail with 401 Token expired Ask the assistant to call auth_status to confirm, then run qualytics auth login --url https://your-instance.qualytics.io, replacing the example URL with your deployment URL.
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 deployment The bridge adds minimal overhead; latency is dominated by the upstream HTTPS request. Run the bridge closer to the deployment.
Assistant invents a tool that doesn't exist The model is hallucinating The bridge exposes the deployment's tool list; if the assistant tries something that fails, it usually corrects on retry. Pin the model or rephrase the prompt.