> For the complete documentation index, see [llms.txt](https://help.qonic.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.qonic.com/documentation/qonic-application/data-and-collaboration/connecting-ai-assistants-mcp.md).

# Connecting AI Assistants (MCP)

Connect an AI assistant such as Claude, Codex or Mistral Le Chat to Qonic, so it can work with your projects and models.

Qonic has an MCP (Model Context Protocol) server. Through it, an AI assistant you already use can look up your projects and models, query and quantify elements, make changes and work in your open Qonic session. Qonic currently supports:

* **Claude Code** (command line)
* **Codex** (command line)
* **Claude** (claude.ai and Claude Desktop)
* **Mistral Le Chat**

The server URL is `https://api.qonic.com/mcp`.

{% hint style="info" %}
Working with Qonic through MCP doesn't use Qonic [tokens](https://help.qonic.com/getting-started/plans-and-add-ons.md#tokens): your AI assistant does the reasoning, and its usage is billed by its own provider.
{% endhint %}

## Before You Start

* You need a Qonic account with a verified email address that belongs to an organization. If your account isn't set up yet, your assistant tells you to sign in to the Qonic dashboard first to finish signing up.
* You sign in with your Qonic account in the browser. You don't need a client secret or an API token, and you don't need an account with any other service. A personal access token doesn't work for MCP: if your assistant's configuration for Qonic contains a bearer token or an authorization header, remove it, otherwise you never get to the sign-in.
* For Claude Code and Codex, run the sign-in command from a terminal, because it waits for you to finish signing in in the browser. Afterwards, start a new session of your assistant: the Qonic tools only appear in sessions started after you signed in.

## Claude Code

1. In a terminal, add the Qonic server:

   ```bash
   claude mcp add --scope user --transport http qonic https://api.qonic.com/mcp
   ```

   `--scope user` makes Qonic available in all your projects. Without it, the server is only added to the current project folder.
2. Sign in:

   ```bash
   claude mcp login qonic
   ```
3. A browser window opens. Sign in with your Qonic account.
4. Start a new Claude Code session.

## Codex

1. In a terminal, add the Qonic server:

   ```bash
   codex mcp add qonic --url https://api.qonic.com/mcp
   ```
2. Sign in:

   ```bash
   codex mcp login qonic --oauth-client-registration cimd
   ```
3. A browser window opens. Sign in with your Qonic account.
4. Start a new Codex session.

{% hint style="warning" %}
Keep the `--oauth-client-registration cimd` option. Without it, Codex may not be able to sign in to Qonic.
{% endhint %}

## Claude (claude.ai and Claude Desktop)

1. In Claude, open *Customize* > *Connectors* (in some versions *Settings* > *Connectors*).
2. Click *+ Add* > *Add custom connector*.
3. Name it `Qonic` and enter the server URL `https://api.qonic.com/mcp`.
4. Leave the authentication and OAuth settings on their defaults. Don't enter a client ID or secret.
5. Click *Add*, then *Connect*. A sign-in window opens: sign in with your Qonic account.

On Claude Team and Enterprise plans, only an organization owner in Claude can add a custom connector: *Organization settings* > *Connectors* > *Add* > *Custom* > *Web*, with the same name and URL. Members then click *Connect* on it under *Customize* > *Connectors*.

To change the URL later, remove the connector and add it again.

## Mistral Le Chat

Le Chat needs Qonic's client ID, which you enter by hand. The client ID isn't a secret: it only works for Le Chat.

1. In Le Chat, go to *Connectors* > *Add custom connector*.
2. Name it `Qonic` and set *Server* to `https://api.qonic.com/mcp`.
3. Set the authentication to *OAuth2.1* and switch on *Advanced OAuth Settings*.
4. Enter the client ID `tpc_qP8X3Xd62zueGdcByb9uhP`. Leave *Client Secret* empty.
5. Create the connector and connect. Sign in with your Qonic account.

{% hint style="warning" %}
If *Advanced OAuth Settings* is off, Le Chat can't connect and shows *We couldn't connect to the MCP server. Check your connection configuration.* Switch it on and enter the client ID. If the *Server* field briefly shows *Invalid URL*, type the URL again.
{% endhint %}

## What Your Assistant Can Do

Your assistant can only do what your role allows in each project and model.

Without the Qonic application open, it can:

* list your projects and their models,
* query elements and their properties, and calculate quantities,
* export a model to IFC,
* change or delete elements, and publish or discard those changes,
* view and manage library items.

Changes it makes are saved as your personal changes, just like changes you make in the application, until they are published.

When the Qonic application is open and you are signed in, your assistant can also work in your current session, the same way as [Qonic AI](https://help.qonic.com/documentation/qonic-application/data-and-collaboration/qonic-ai.md): find, select, show and hide elements, and edit or draw in the open models. To do this, you need edit rights on every model that is open in the session, even if the assistant only reads data. Tools of an add-on that isn't available in the project can't be used.

{% hint style="info" %}
If you have Qonic open in several windows or browser tabs, each of them carries out the assistant's requests. Keep one Qonic window open while your assistant works in your session, keep it in the foreground, and close older tabs.
{% endhint %}

## Troubleshooting

* **The Qonic tools don't appear after signing in.** Start a new session of your assistant. In Claude Code, also check that you added the server with `--scope user`, or from the project folder you are working in.
* **Claude Code loses the Qonic connection in all sessions at once.** Run `/mcp` in one session, choose the Qonic server and sign in again. Then start new sessions, or reconnect the server through `/mcp` in the open ones.
* **A sign-in error page offers to create an account.** You don't need one: stop there and contact Qonic support.
* **Your assistant isn't in the list above.** Other assistants can't sign in to Qonic yet.
