# MCP Best Practices

Source: https://userguide.qualytics.io/using-the-platform/mcp/deep-dive/best-practices/

Recommendations for connecting external AI clients to the Qualytics MCP server safely and getting reliable results from them. To set up a client, see [Connecting External AI Clients](https://userguide.qualytics.io/using-the-platform/mcp/connecting-external-ai-clients/requirements/).

## Securing the Connection

### Use One Personal API Token per Client

Every client you authorize is tied to the Personal API Token you pasted on the Qualytics authorization page. Revoking that token ends the authorization of every client that used it. With one token per client, you can disconnect a single client, such as a laptop you no longer use, without touching the others. Name each token after the client it serves so it is easy to find later in **Settings** > **Tokens**.

### Give the Token an Expiration Date

A client never keeps access past the expiration date of the token you authorized it with. A token with an expiration date puts a fixed end on that access, even if the client is forgotten. When the date arrives, generate a new token and reconnect. See [Generate Token](https://userguide.qualytics.io/settings/access-tokens/personal-token/managing/generate-token/).

### Paste the Token Only on the Qualytics Authorization Page

Never put your Personal API Token in a client configuration file, an environment variable, or an `Authorization` header. A token sent that way does not authenticate an MCP connection, and a configuration file is easy to share or commit by accident. The client receives its own short-lived credential once you authorize it, so the token itself never needs to leave the authorization page.

### Request Read-Only Access When You Only Need Answers

A client authorized with read-only access can run the tools that read data, but not the tools that change it. For a client used only for questions and reporting, request read-only access in its configuration. The Qualytics authorization page shows the access the client is asking for before you enter your token, so check it there.

---

## Working With the Client

### Review Actions Before Approving Them

Tools can change Qualytics assets, such as creating a quality check, and can start operations that write to an [enrichment datastore](https://userguide.qualytics.io/source-datastore/enrichment-datastore/deep-dive/introduction/). They never write back to source datastores. Keep your client's approval prompt turned on for tools that change data, and read what the client proposes before you approve it.

### Be Specific About Assets

The client finds datastores, containers, and fields by name. Naming the datastore and the container in your request saves the search step and avoids acting on the wrong asset with a similar name.

| Instead of... | Use... |
| --- | --- |
| *"Check my main table"* | *"Check the `orders` table in the `ecommerce_prod` datastore"* |
| *"Show me anomalies"* | *"List active anomalies in the `transactions` container in `sales_db`"* |

The same prompting guidance applies to AgentQ, since both use the same tools. See [AgentQ Best Practices](https://userguide.qualytics.io/agentq/deep-dive/best-practices/).

### Break Complex Work Into Steps

Ask for one step at a time and check the result before the next. A request such as *"Show me quality scores for `sales_db`"*, followed by *"Now create checks for any container scoring below 80"*, is easier to review and correct than a single request that analyzes, creates, and scans everything at once.

---

## Keeping the Connection Healthy

### Use the Instance URL From Your Administrator

The authorization is tied to the address your Qualytics instance is configured with. A hostname alias that reaches the same instance can still fail authorization. Use the URL your Qualytics administrator gives you, followed by `/api/mcp/`.

### Expect to Reconnect Every 30 Days

An authorization lasts 30 days from the moment you approve it, even when the client refreshes its connection in between. When the client asks you to connect again, reconnect and paste a valid Personal API Token.

### Revoke Tokens You No Longer Use

When you stop using a client, revoke the token you authorized it with. The client loses access on its next request, since Qualytics checks the token behind the authorization every time. See [Revoke Token](https://userguide.qualytics.io/settings/access-tokens/personal-token/managing/revoke-token/).

## See Also

- **Permissions**

  The user roles, tokens, and team permissions behind what a client can do.

  [Permissions](https://userguide.qualytics.io/using-the-platform/mcp/deep-dive/permissions/)
- **Introduction**

  What MCP is, what the Qualytics MCP server offers, and why it matters for data quality.

  [Introduction](https://userguide.qualytics.io/using-the-platform/mcp/deep-dive/introduction/)
- **How It Works**

  How a client, the Qualytics MCP server, and the model work together on a request, and what the model sees.

  [How It Works](https://userguide.qualytics.io/using-the-platform/mcp/deep-dive/how-it-works/)
- **Connecting External AI Clients**

  What you need before connecting a client, and the setup for each company's clients.

  [Connecting External AI Clients](https://userguide.qualytics.io/using-the-platform/mcp/connecting-external-ai-clients/requirements/)
- **Examples**

  Real scenarios built on the prompts the Qualytics MCP server ships with, from explaining an anomaly to judging whether data can be trusted.

  [Examples](https://userguide.qualytics.io/using-the-platform/mcp/deep-dive/examples/)

*Last updated: November 7, 2026.*