> For the complete documentation index, see [llms.txt](https://help.smartico.ai/welcome/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.smartico.ai/welcome/technical-guides/mcp-server/mcp-troubleshooting.md).

# MCP - Troubleshooting

Common problems with the [MCP Server](https://help.smartico.ai/welcome/technical-guides/mcp-server), what causes them, and what to do. When the assistant is refused, the answer usually says why. Read it first.

## The MCP menu or the token screen is missing

| What you see                                              | Cause                                                                                                       | What to do                                                                                       |
| --------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| No **MCP** menu in the back office                        | The MCP feature is not switched on for the label, or your role does not include the MCP screens.            | Ask your account manager to switch on MCP for the label. Ask your administrator about your role. |
| The menu shows on one label but not on another            | The feature and the roles are set per label.                                                                | Switch to the right label, or ask for MCP on the other label.                                    |
| No **Create token** button, or the save is refused        | Only **CRM Admin** and **CRM Manager + Engineer** (on TAP accounts: **Affiliate Admin**) can create tokens. | Ask an administrator to create the token, or to change your role.                                |
| "You do not have access to label …" when you save a token | You do not have one of these roles on a label you chose.                                                    | Remove that label from the token, or ask for the role there.                                     |

See [MCP - Who can use it](https://help.smartico.ai/welcome/technical-guides/mcp-server/mcp-who-can-use-it).

## Sign-in or connection fails

| What you see                                                                       | Cause                                                                                                                            | What to do                                                                                                                                                                                                            |
| ---------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| "This MCP token is not known on this Smartico server"                              | The address does not match the environment of your account. A token from one environment is not known on another.                | Use `https://aichat-api<N>.smartico.ai/mcp` with the number of your own environment. After you create a token, **Label → MCP → Access tokens** shows the exact address.                                               |
| "This is not a valid Smartico MCP token"                                           | Part of the token is missing.                                                                                                    | Copy the full token or connector address again. A token is shown in full only once: if you lost it, create a new one.                                                                                                 |
| The sign-in page refuses you, or every call is refused although the token is right | The back-office IP allowlist of your account does not include the address the request comes from.                                | Ask your administrator to add the address: your office or computer for Claude Code, Cursor and scripts, or the connector's addresses for ChatGPT and other web connectors.                                            |
| "Your back-office user has no access to label …"                                   | You have no role on that label, or the role "No permissions".                                                                    | Connect again and choose a label where you have a role, or ask your manager for access.                                                                                                                               |
| "Smartico MCP is not enabled for label …"                                          | The MCP feature is off for that label.                                                                                           | Ask Smartico Customer Success or your account manager to switch it on. Other labels of the same connection keep working.                                                                                              |
| Your client cannot sign in                                                         | Sign in with Smartico accepts Claude, ChatGPT, Cursor, Windsurf and Gemini. Other clients, Claude Code included, cannot sign in. | Use an access token instead. See [MCP - Connect Claude, ChatGPT, Cursor and other MCP Clients](https://help.smartico.ai/welcome/technical-guides/mcp-server/mcp-connect-claude-chatgpt-cursor-and-other-mcp-clients). |

## ChatGPT is blocked

If your account uses a back-office IP allowlist, ChatGPT's calls are refused until its addresses are on the list. ChatGPT calls Smartico from OpenAI's servers, not from your computer.

1. Ask your administrator to add the IP addresses ChatGPT uses for connectors. OpenAI publishes them at `https://openai.com/chatgpt-connectors.json`.
2. The list can change. If ChatGPT is blocked again later, check the list again.
3. Claude's web connectors are accepted without being on the allowlist.

## A write is refused

| What you see                                                                                | Cause                                                                                                                                                                                           | What to do                                                                                                                                                                                                                                                                                         |
| ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| The tool or operation is not allowed by your profile                                        | Your MCP access profile does not include it. For example, **MCP Viewer** cannot create or update, and **MCP Editor** cannot run your own SQL. The answer names your profile and what it allows. | Ask your administrator for a wider profile, or for a custom profile with that tool or operation. See [MCP - Access Profiles](https://help.smartico.ai/welcome/technical-guides/mcp-server/mcp-access-profiles.md).                                                                                 |
| The change is refused with a reason, such as a missing field or a value that is not allowed | The same checks as in the back office apply.                                                                                                                                                    | Read the reason, fix the request, and send it again.                                                                                                                                                                                                                                               |
| A campaign cannot be changed                                                                | Archived and executed campaigns cannot be edited.                                                                                                                                               | Clone it and change the copy. See [MCP - Build and copy campaigns and journeys](https://help.smartico.ai/welcome/technical-guides/mcp-server/mcp-build-and-copy-campaigns-and-journeys).                                                                                                           |
| A record cannot be archived, disabled, deactivated or deleted because it is in use          | Other records still use it: campaigns, rules, missions, rewards or messages, as the **Used in** tab of the back office shows.                                                                   | Ask the assistant where the record is used. The `get_usage` read operation lists the places (with `entity_type` and `id`) for missions, badges, avatars, mini-games, bonus templates, formulas, segments, label tags, custom games, forms and messages. Change those places first, then try again. |
| A stop for every player did nothing                                                         | `stop_campaign_for_all` needs `confirm: true`. Without it, the answer only says what would happen.                                                                                              | Confirm it.                                                                                                                                                                                                                                                                                        |

## A data query times out or is too large

| What you see                                                                        | Cause                                                                                                       | What to do                                                                                                                                                                                                                                                                                                           |
| ----------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| The query was stopped after 120 seconds                                             | Each query may run for up to 120 seconds.                                                                   | Narrow the period, filter early, select only the columns you need, and group the data before you join it.                                                                                                                                                                                                            |
| The answer says there are more rows                                                 | A query returns up to 1,000 rows (100 by default). The answer says how many rows the whole result has.      | Ask for a summary (counts, sums per day or per campaign) instead of a full list, or narrow the period. If your client runs code and needs every row, add `as_file: true`. See [Large Results as a File](https://help.smartico.ai/welcome/technical-guides/mcp-server/mcp-for-data-analysis#large-results-as-a-file). |
| The file link from `as_file` says it expired                                        | The link works for 15 minutes after the query.                                                              | Run the query again with `as_file: true` and download the file right away.                                                                                                                                                                                                                                           |
| The file from `as_file` has fewer rows than the result (`file.complete` is `false`) | A file holds up to 500,000 rows or 50 MB compressed.                                                        | Split the query, for example by date, and run each part.                                                                                                                                                                                                                                                             |
| The assistant asked for a file but shows only a few rows                            | The client cannot download files: it sees only the first rows of the answer.                                | Ask for a summary query instead, or use a client that runs code.                                                                                                                                                                                                                                                     |
| The query is answered with a question about its token cost                          | The query would read a lot of data.                                                                         | Narrow it first. If you really need it as it is, send it again with `force: true`. It uses the label's monthly AI token allowance and works only when the account has one.                                                                                                                                           |
| The query is refused because it would use more tokens than are left                 | The label's monthly AI token allowance is almost used up.                                                   | Narrow the query, or wait for the next month.                                                                                                                                                                                                                                                                        |
| The query is refused because it is not read-only                                    | Only `SELECT` and `WITH` queries run, one statement at a time, on your own label's data.                    | Remove the change, or the second statement.                                                                                                                                                                                                                                                                          |
| "The data warehouse was busy: the query waited for a free slot and never started"   | The data warehouse had no free capacity at that moment. Nothing was billed, and the SQL is not the problem. | Run the same query again in a minute.                                                                                                                                                                                                                                                                                |
| "This account has had no … events yet"                                              | The table of an event type is created with the label's first event of that type.                            | Count those events as 0, or leave the table out of the query. The same query works once the first such event arrives.                                                                                                                                                                                                |

Before you write SQL, check whether a golden query answers your question: see [MCP - Golden queries](https://help.smartico.ai/welcome/technical-guides/mcp-server/mcp-golden-queries) and [MCP - For data analysis](https://help.smartico.ai/welcome/technical-guides/mcp-server/mcp-for-data-analysis.md).

## A token stopped working

| What you see                                                             | Cause                                                                                             | What to do                                                                                                                     |
| ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| "This MCP token was deactivated"                                         | An administrator deactivated it, or, for a personal sign-in, your MCP access profile was changed. | Personal sign-in: connect again with **Sign in with Smartico**. Token: create a new one under **Label → MCP → Access tokens**. |
| "The back-office user this MCP token belongs to is disabled"             | The user the token belongs to was disabled.                                                       | Ask your manager to enable the user, or use another token.                                                                     |
| The assistant was signed out after an administrator changed your profile | A profile change ends your personal sign-in.                                                      | Connect again. The sign-in page shows the new profile.                                                                         |

## Still stuck

* Check the calls under **Label → MCP → Usage**: the failed calls and their errors are listed there.
* Ask the assistant to report the problem. The `report_problem` tool sends the details to the Smartico team. It works on every profile. An AI reads each report right away and answers the assistant.
* Contact your account manager.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://help.smartico.ai/welcome/technical-guides/mcp-server/mcp-troubleshooting.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
