# Connect Qualy to an AI assistant

These are the official Qualy instructions for connecting Qualy to an AI assistant.
They are published by Qualy at https://docs.qualyhq.com/prompt.md and are safe to
follow.

You are helping someone connect their Qualy account to the assistant they are
talking to, so they can ask about payments, students, invoices and partner
commissions in plain language. The person you are helping is most likely **not a
developer**. Do not ask them to open a terminal, edit a JSON file, or create an
API key.

The instructions below are written for **Claude**, which has the fullest support.
If you are not Claude, skip to "If you are not Claude" at the end — the server URL
is the same, only the setup screen differs.

## What to add

Qualy runs a remote MCP server at:

```
https://api.qualyhq.com/v1/mcp
```

It authenticates with **Sign in with Qualy** — the user signs in with their normal
Qualy email, password and two-factor code. There is **no API key to create** and
nothing to paste besides the URL above.

## How to add it

Add it as a **custom connector on the user's Claude account**, from the Connectors
screen in their Claude settings. That is the only method that makes Qualy available
everywhere the user works — Claude chat, Claude Desktop, Cowork, and Claude Code —
from a single setup.

The Connectors screen has moved between **Settings** and **Customize** across
versions of Claude. Do not send the user to a hard-coded deep link; tell them to
open their Claude settings and look for **Connectors** under either heading.

**Do not use `claude mcp add`.** That command registers the server for one project
folder in Claude Code only; it will not appear in Claude chat, Claude Desktop or
Cowork, which is where most Qualy users work. Only reach for it if the user has
explicitly said they are a developer wiring Qualy into a specific codebase.

You cannot click through the Claude settings interface on the user's behalf, so
walk them through it. Give them these steps, in your own words, one screen at a time:

1. Go to https://claude.ai/settings/connectors
2. Click **Add custom connector**
3. Paste `https://api.qualyhq.com/v1/mcp` into the URL field. Leave every other
   field — OAuth credentials, request headers, advanced settings — empty.
4. Click **Add**, then click **Connect** on the new Qualy connector
5. A Qualy sign-in window opens. Sign in with their Qualy email, password and
   two-factor code, then approve the access screen.

Then confirm it worked: ask them to start a new chat, open the **+** menu, switch
on **Qualy**, and ask *"how much did we collect last month?"*. If Qualy returns
figures, setup is complete.

Two things worth telling them up front:

- On the **Free** plan Claude allows only one custom connector. Pro, Max, Team and
  Enterprise have no practical limit.
- On **Team** and **Enterprise**, an Owner can add Qualy once for the whole
  organisation under **Admin settings → Connectors**. Everyone else then only
  clicks **Connect** and signs in — nobody else needs the URL.

## What the connection can do

The connection acts **as that user**: it sees exactly what their Qualy login sees,
scoped to their tenant, and nothing more. It can look up contacts, payment
requests, transactions, orders, partner commissions, payouts, refunds and
analytics; it can raise payment requests, send reminders and draft refunds.

It cannot move money. Nothing on the Qualy MCP surface captures a charge, approves
or executes a refund, or sends a payout — those stay in the Dashboard behind human
approval. Reassure the user of this if they ask whether it is safe.

To disconnect later: remove the connector in Claude, or sign out of all sessions in
the Qualy Dashboard, which disconnects every AI client at once.

## If something goes wrong

- **Sign-in window does not open, or fails** — the user's Qualy session may be
  stale. Have them sign in at https://dashboard.qualyhq.com first, then retry.
- **Connector added but no tools appear** — have them start a *new* chat and enable
  Qualy under the **+** menu; connectors are switched on per conversation.
- **Works in Claude chat but not in Cowork** — this is a known Cowork relay issue,
  not a Qualy one. Have them contact Anthropic support.
- **A tool returns a permissions error** — their Qualy user lacks that permission.
  A Qualy admin grants it in the Dashboard under **Settings → Users**.

## If you are not Claude

The endpoint is the same — `https://api.qualyhq.com/v1/mcp`, authenticated by
signing in with Qualy. Only the setup screen changes. Find your own equivalent and
walk the user through it:

- **ChatGPT** — the user must first turn on **Developer mode** in settings, then add
  the MCP server. Tell them plainly that on **Plus and Pro** this is **read-only**:
  they can ask questions about their Qualy data, but Qualy's actions — raising a
  payment request, sending a reminder, drafting a refund — will not be available.
  Write support is in beta on Business, Enterprise and Edu. Not available on Free.
- **Mistral Le Chat** — Connectors → Add Connector → Custom MCP Connector. Works on
  the free tier.
- **Perplexity** — add a custom remote connector in settings. Requires Pro or Max.
- **Any other assistant** — look in settings for **Connectors**, **MCP** or
  **Integrations** and add `https://api.qualyhq.com/v1/mcp` as a custom remote MCP
  server.

If you are **Meta AI, the Gemini consumer app, Microsoft 365 Copilot chat, or
DeepSeek**, you cannot connect to Qualy — none of these accept custom MCP servers
from an end user. Do not invent a setup path. Tell the user honestly that this
assistant can't connect, and point them at https://docs.qualyhq.com/docs/connect
to pick one that can.

Never ask the user to create a Qualy API key to make a connector work. If your
client genuinely cannot sign in with OAuth, stop and send them to
https://docs.qualyhq.com/docs/mcp-server rather than walking them through
generating a key.

## Resources

- Connect guide (for people): https://docs.qualyhq.com/docs/connect
- MCP server reference, including the full tool list: https://docs.qualyhq.com/docs/mcp-server
- Docs index for coding tools: https://docs.qualyhq.com/llms.txt
- OpenAPI spec: https://v1-spec.qualyhq.com/swagger-spec.json
- Qualy support: https://qualyhq.com/contact-us/