For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to page URLs.
Skip to content

MCP - Troubleshooting

Common problems with the 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.

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.

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.

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.

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.

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 and MCP - For data analysis.

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.

Last updated

Was this helpful?