1. Docs
  2. AI
  3. MCP & AI assistants
  4. Troubleshooting

Troubleshooting

Find the message or symptom you or your assistant see. Each entry says why it happens, what to check and how to fix it.

6 min read Updated CustomersAdmins

In short

On this page you can

  • Fix a connection that does not show up in Claude, Claude Code or Cursor.
  • Fix sign-in problems with the claude.ai connector.
  • Understand refusals the assistant reports, such as STALE_PREVIEW or READ_ONLY.
  • Unblock a scenario that is BLOCKED after three red runs.

How to use it

  1. Find the message the client or the assistant shows.
  2. Open the entry and work through Check.
  3. Apply Fix, restart the client if the entry says so.
  4. Ask “Which SmartestQA projects can I access?” to test again.

Connecting#

SmartestQA does not appear in Claude (or its tools are missing)Connect
Why
The client did not reload, the extension is off, or the server could not start.
Check
  1. Claude Desktop: you quit it completely, including the tray icon, and opened it again. Settings › Extensions shows SmartestQA switched on.
  2. claude.ai: SmartestQA is enabled in the chat’s tools menu.
  3. Claude Code: claude mcp list shows it; start a new session. Cursor: Settings › MCP.
  4. The client’s MCP log names a missing setting when the server did not start: macOS ~/Library/Logs/Claude/mcp-server-*.log, Windows %APPDATA%\Claude\logs\.
Fix
Restart the client. If it still fails, install again from the MCP tab.
“Select a host to see the command with your API key.”Connect
Why
The command needs a host’s API key, and no host with a key is selected.
Fix
In Device FarmTest Agents, click your host under Localhost (named after your email), then open the MCP tab.
The install command stops: Node.js is missing or too oldConnect
Why
The one-line install and the zip run on Node.js: “Needs Node.js 18 or newer on the machine.”
Fix
Install a current Node.js from nodejs.org, open a new terminal and run the command again. Claude Desktop users can use the .mcpb extension instead, which needs no Node.js.
“No MCP client was found on this machine (Claude Desktop, Claude Code or Cursor).”Connect
Why
The installer registers SmartestQA in the configuration of the clients it finds, and found none.
Fix
Open Claude Desktop once, or run Claude Code once (claude), then run the command again. For Cursor, add --client=cursor to the manual command. For another client, see Another MCP client.
macOS or Linux: ./smartest-mcp says “Permission denied”Connect
Why
The unpacked file lost its permission to run (some unzip tools and copies drop it).
Fix
Start it with sh ./smartest-mcp …, exactly as the manual command on the MCP tab does.
Claude Desktop shows a security warning when installingConnect
Why
“Claude shows a security warning during installation. This is normal for every local extension.”
Fix
Continue the installation if the file came from the MCP tab of your SmartestQA.
I changed the key but the old one is still usedConnect
Why
“After changing the key, quit Claude and open it again — the running server keeps the old one.”
Fix
Quit the client completely and open it again.

Connector sign-in (claude.ai)#

“This account has no password yet. Set one with the link in your email, then try again.”Sign-in
Why
The connector signs you in with email and password, and your account has none yet (for example you were invited and never set one).
Fix
Set your password with the link in your invitation e-mail (see Quick Start), then connect again.
“Wrong email or password.” / “Too many failed attempts. Please try again in 15 minutes.”Sign-in
Why
The sign-in did not match. After 10 failures within 15 minutes, sign-in from that address is paused for 15 minutes.
Fix
Check the address you sign in to SmartestQA with. Reset the password with Forgot Password? on the SmartestQA sign-in page if needed, then wait out the pause.
“This connection request is not valid or has expired. Go back to Claude and start connecting again.”Sign-in
Why
The sign-in window was opened from an old or incomplete link, or waited too long.
Fix
Close the window, go back to Claude and click connect again.
Claude says the SmartestQA connection was rejected or expiredSign-in
Why
The renewal token was not used for 30 days, was revoked, or your access changed.
Fix
In Claude, Settings › Connectors: disconnect SmartestQA and connect it again.

Using the tools#

The assistant says the SmartestQA key was rejected (401)Access
Why
The key is wrong, its host was deleted, or the key belongs to another SmartestQA environment than the package.
Check
Your host still exists in Test Agents, and you installed the package from the same SmartestQA you copied the key from.
Fix
Copy the key again with Copy API Key, paste it in the extension settings (or run the install command again) and restart the client.
“not allowed for this account (403)” or ACCESS DENIEDAccess
Why
The key works, but your user may not do this, or may not open this project. The message from SmartestQA says what.
Fix
Ask an Admin for access to the project. For an action your role cannot do, ask an Admin to do it: roles are fixed, so an Admin cannot add a single permission to your role. Do not renew the key: it is fine.
The assistant cannot reach the SmartestQA server, or it times outNetwork
Fix
Check the internet or VPN connection of the machine the MCP runs on, and that a company proxy allows SmartestQA. Then ask again.
The assistant works on the wrong projectUse
Fix
Name the project in each request: “In project Web Shop, …”. The assistant may not guess a project; if it did not ask, tell it which one.
“this connection to … is read-only”Use
Why
This install was set up read-only (SMARTEST_READONLY=true): only reading tools are offered.
Fix
Use a normal install for writing, or make the change in SmartestQA. See Read-only connection.
The assistant reports STALE_PREVIEWChanges
Why
The preview was already applied, the records changed since it was made, it is older than 30 minutes, or the MCP restarted. Nothing was written.
Fix
Let the assistant propose again and read the new diff. See Previews.
“NOT DONE - the user declined the confirmation dialog.” / “NOT DONE - this action needs the user's click…”Changes
Why
The action needs your click in a dialog: you declined, or your client cannot show dialogs. Nothing was changed.
Fix
If you meant to do it, ask again and confirm. If the client shows no dialogs, do it in SmartestQA. See Actions that need your click.
“only an admin can remove records (your role: …); nothing was removed”Changes
Fix
Ask an Admin to approve and confirm the removal, or archive the records in SmartestQA if your role allows it.
A scenario is BLOCKEDScenarios
Why
Its dry run was not green three times. The assistant stops so it does not keep changing steps blindly.
Fix
Decide with the assistant (see The scenario flow): you fixed the cause (app, data, environment), the proof it checks must change, or the scenario must be split. It runs again only after you confirm “Run it again?”.
A dry run on my agent does not startScenarios
Fix
The agent must be online in Test Agents. See the agent fix, or ask for the dry run on the server.
The assistant reports UNKNOWN_TOOL or RULES_OUTDATEDUse
Why
UNKNOWN_TOOL: the assistant used a tool name the server does not have, often from an older conversation. RULES_OUTDATED: the step rules changed; the assistant must read them again. Nothing was written.
Fix
Let the assistant continue; it re-reads the tool list or the rules. If it keeps happening, update the MCP (smartest-mcp --update, or a new .mcpb) and start a new chat.
A write is refused because of the languageUse
Why
Content is written in the project’s language. The assistant tried another one, or the project has none set.
Fix
Tell the assistant the project’s language (it can save it if none is set). You can keep chatting in your own language.

Still stuck: write to info@smartestqa.ai with the client you use, the time and the message.

Didn’t find your answer?Write to support with your project name and what you see on screen.

info@smartestqa.ai
© 2026 Selenity Technology · SmartestQAsmartestqa.aiThis page as MarkdownChecked against smartest-mcp-server 1.31.1 (index.ts, core/api.ts, core/registry.ts, next/flow.ts, next/run.ts, install.ts, mcp-install.sh), smarttest-fe predev 2a8c79cc (ConnectToClaude, OAuthConsent, en.json), smarttest-be 633c2a03 (oauth/Lang, OAuthController)