MCP API¶

The Qualytics MCP server is reached through the Model Context Protocol, not through REST calls. Compatible clients find and use the endpoints on this page on their own, so connecting ChatGPT, Claude, Cursor, or another supported client needs none of it. This page is for developers who build their own MCP client, or who need to understand what a client does when a connection fails.

Calling Qualytics From Your Own Code

To send prompts or run workflows from a script or an application, use the AgentQ API, which exposes the same capabilities through REST endpoints. For the full Qualytics REST API, see the API docs.

All paths on this page are relative to the address of your Qualytics deployment (for example, https://your-instance.qualytics.io).

Server Endpoint¶

Endpoint: https://your-instance.qualytics.io/api/mcp/

Transport: Streamable HTTP

Every request to the server carries an MCP access token in the Authorization header:

Authorization: Bearer MCP_ACCESS_TOKEN

The MCP access token is issued through the authorization flow below. A Qualytics Personal API Token is not accepted here: sending one returns 401 Unauthorized, and the response points the client to the discovery metadata so it can start the authorization flow.

For the tools, resources, and prompts the server exposes, see How MCP Works and the Tool Catalog.

Authorization¶

The server uses OAuth 2.1 with PKCE and dynamic client registration. The client registers itself, opens the Qualytics authorization page in the browser, and exchanges the result for an MCP access token and a refresh token. The person connecting pastes a Personal API Token on that page, and the token never reaches the client.

Discovery¶

A client reads these metadata documents to find the endpoints below.

Document	Path
Protected resource metadata	`/.well-known/oauth-protected-resource/api/mcp`
Authorization server metadata	`/.well-known/oauth-authorization-server/api/mcp`

For clients that do not use path-aware discovery, the authorization server metadata is also served at /.well-known/oauth-authorization-server and /.well-known/openid-configuration.

Endpoints¶

Endpoint	Method	Purpose	Rate limit
`/api/mcp/register`	`POST`	Registers a new client.	30 requests per minute
`/api/mcp/authorize`	`GET`, `POST`	Starts an authorization and redirects the browser to the Qualytics authorization page.	60 requests per minute
`/api/mcp/oauth/login`	`GET`, `POST`	The Qualytics authorization page, where the person connecting pastes a Personal API Token.	30 requests per minute
`/api/mcp/token`	`POST`	Exchanges an authorization code for tokens, or a refresh token for new tokens.	60 requests per minute
`/api/mcp/revoke`	`POST`	Revokes a refresh token.	No dedicated limit

Rate limits apply per client IP address. A request over the limit returns 429 Too Many Requests with a Retry-After header giving the seconds to wait.

Scopes¶

Scope	Allows
`read`	Tools that read data.
`write`	Tools that change data, and every tool `read` allows.

A client that requests no scopes receives both. The authorization page shows the requested access before the token is entered. A refresh can keep or narrow the granted scopes, but never add to them.

Token Lifetimes¶

Item	Lifetime
Authorization page	5 minutes after the client opens it
Authorization code	10 minutes
MCP access token	15 minutes, and never past the expiration date of the Personal API Token behind it
Refresh token	30 days from the original authorization. Each refresh returns a new refresh token, but the 30-day limit does not reset.

Every request also checks the Personal API Token behind the authorization. If that token is revoked or expires, or its owner is removed, the next request fails and the client must authorize again with a valid token. Revoking a refresh token through /api/mcp/revoke stops further refreshes, while an MCP access token already issued stays valid until it expires.

Errors¶

Error	Returned by	Meaning
`401 Unauthorized`	`/api/mcp/`	The request has no valid MCP access token. Start or repeat the authorization flow.
Invalid API token	Authorization page	The pasted token is not a valid, active Personal API Token.
Session has expired. Please try again.	Authorization page	The page was submitted more than 5 minutes after the client opened it.
`invalid_grant`	`/api/mcp/token`	The authorization code or refresh token is unknown or expired, or the Personal API Token behind it is no longer active.
`invalid_target`	`/api/mcp/token`	The requested resource does not match this server's address, usually because the client used a hostname alias.
`invalid_scope`	`/api/mcp/token`	The client asked for a scope other than `read` or `write`, or tried to add a scope on refresh.
MCP write scope is required for this tool	Tool call	The client is authorized for `read` only and called a tool that changes data.
`429 Too Many Requests`	Authorization endpoints	The rate limit was reached. Wait for the time in the `Retry-After` header.

For the steps to resolve each problem, see MCP Troubleshooting.