MCP Troubleshooting¶

This page documents the known problems with connecting an external AI client to the Qualytics MCP server and the steps to resolve them. A connection goes through three stages in order: the client reaches the server, you authorize it on the Qualytics page, and the client then calls tools. Each section below covers one stage, so work through them top to bottom. Each entry describes a symptom, its cause, and the resolution.

Connecting the Client¶

The Client Lists No Qualytics Tools¶

The client shows the Qualytics server, but no Qualytics tools are available in the chat.

Cause: The server URL is wrong, or the configuration file uses a key the client does not read.

Resolution: Check that the URL is your Qualytics address followed by /api/mcp/. Then check the keys that hold the server: VS Code reads servers with url, Gemini CLI reads mcpServers with httpUrl, and Cursor, Kiro, Windsurf, and Amazon Q Developer read mcpServers with url. See Connecting External AI Clients for the configuration of each client.

The Client Fails to Connect With a Bearer Header¶

The client configuration sends an Authorization: Bearer header with your API token, and the connection is refused.

Cause: A Qualytics API token sent in a header does not authenticate an MCP connection. The token is only accepted on the Qualytics authorization page.

Resolution: Remove the header from the client configuration and reconnect. The client opens the authorization page in your browser, where you paste the token.

The Client Cannot Complete Browser Authorization¶

The client never opens the authorization page, or it stops before the connection is made.

Cause: The client does not support OAuth, which the Qualytics MCP server requires.

Resolution: Use another compatible client, or the CLI MCP Server.

Authorizing on the Qualytics Page¶

The Authorization Page Shows "Invalid API token"¶

You paste a token on the Qualytics authorization page, and the page answers Invalid API token.

Cause: The token was mistyped or cut short, was revoked, or has expired. A password or a SCIM Administration Token is refused the same way, and so is every token when your deployment does not allow API tokens.

Resolution: Generate a new Personal API Token in Settings > Tokens and paste it on the authorization page. See Tokens.

The Authorization Page Shows "Session has expired"¶

The page answers Session has expired. Please try again. when you submit the token.

Cause: The authorization page stays valid for 5 minutes after the client opens it. The token was submitted after that.

Resolution: Start the connection again from the client, and paste the token as soon as the new page opens.

Authorization Fails Even With a Valid Token¶

The token is accepted on the authorization page, but the client still does not connect.

Cause: The server URL in the client uses a hostname alias instead of the address your Qualytics instance is configured with. The authorization is tied to that address, so a different hostname does not match.

Resolution: Use the instance URL shown by your Qualytics administrator, followed by /api/mcp/, and reconnect.

Using the Client¶

A Client That Worked Before Asks You to Connect Again¶

The client was connected and working, and now asks you to authorize it again.

Cause: The authorization reached its 30-day limit, which applies even when the client refreshes its connection. Revoking or letting the Personal API Token behind it expire ends the authorization sooner.

Resolution: Reconnect from the client and paste a valid Personal API Token on the authorization page.

A Tool That Changes Data Returns "MCP write scope is required for this tool"¶

Tools that read data work, but a tool that creates or changes something fails with this message.

Cause: The client requested read-only access when it was authorized. Tools that change data need write access.

Resolution: Change the client configuration so it requests write access, or remove the scope setting so the client receives read and write access. Then reconnect.

A Tool Call Fails on One Datastore¶

A tool works on some datastores and fails on another.

Cause: Every tool runs as you. A datastore you cannot reach in Qualytics is a datastore the client cannot reach on your behalf.

Resolution: Check your role and your team permissions on the datastore involved. See Permissions.