---
title: "Troubleshooting"
section: "MCP & AI assistants"
description: "Fixes for the SmartestQA MCP: Claude does not show SmartestQA, key rejected, no password set, Node.js missing, read-only, STALE_PREVIEW, declined dialogs, BLOCKED scenarios."
url: https://docs.smartestqa.ai/en/mcp-troubleshooting.html
audience: [customer, admin]
updated: 2026-11-08
keywords: "mcp error claude desktop not showing extension key rejected 401 403 password not set too many failed attempts node.js no mcp client permission denied read-only stale_preview declined confirmation unavailable blocked unknown_tool"
---
# MCP & AI assistants: 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.

## 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

### Problem: 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](https://docs.smartestqa.ai/en/mcp-connect.html#claude-desktop).

### Problem: “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 Farm** › [**Test Agents**](https://docs.smartestqa.ai/en/agent-pool-agents.html#agent-list), click your host under **Localhost** (named after your email), then [open the **MCP** tab](https://docs.smartestqa.ai/en/agent-pool-agents.html#mcp-tab).

### Problem: The install command stops: Node.js is missing or too old _(Connect)_

- **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](https://docs.smartestqa.ai/en/mcp-connect.html#claude-code). Claude Desktop users can use the [.mcpb extension](https://docs.smartestqa.ai/en/mcp-connect.html#claude-desktop) instead, which needs no Node.js.

### Problem: “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](https://docs.smartestqa.ai/en/mcp-connect.html#claude-code). For Cursor, add `--client=cursor` to [the manual command](https://docs.smartestqa.ai/en/mcp-connect.html#manual-zip). For another client, see [Another MCP client](https://docs.smartestqa.ai/en/mcp-connect.html#other-client).

### Problem: 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](https://docs.smartestqa.ai/en/mcp-connect.html#manual-zip) on the MCP tab does.

### Problem: Claude Desktop shows a security warning when installing _(Connect)_

- **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](https://docs.smartestqa.ai/en/agent-pool-agents.html#mcp-tab) of your SmartestQA.

### Problem: I changed the key but the old one is still used _(Connect)_

- **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)

### Problem: “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](https://docs.smartestqa.ai/en/company-settings-users.html#add-user) and never set one).
- **Fix:** Set your password with [the link in your invitation e-mail](https://docs.smartestqa.ai/en/company-settings-users.html#password-email) (see [Quick Start](https://docs.smartestqa.ai/en/quick-start-troubleshooting.html#fix-password-not-set)), then connect again.

### Problem: “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?**](https://docs.smartestqa.ai/en/quick-start-troubleshooting.html#fix-link-expired) on the SmartestQA sign-in page if needed, then wait out the pause.

### Problem: “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](https://docs.smartestqa.ai/en/mcp-connect.html#claude-ai).

### Problem: “Could not save your decision. Please try again.” _(Sign-in)_

- **Why:** Your **Allow** or **Deny** could not be sent: the connection dropped or your SmartestQA session expired.
- **Fix:** Click again. If it repeats, sign in to SmartestQA in the same browser and [start connecting again](https://docs.smartestqa.ai/en/mcp-connect.html#claude-ai) from Claude.

### Problem: Claude says the SmartestQA connection was rejected or expired _(Sign-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](https://docs.smartestqa.ai/en/mcp-connect.html#claude-ai).

## Using the tools

### Problem: 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](https://docs.smartestqa.ai/en/agent-pool-agents.html#agent-list), and you installed the package from [the same SmartestQA](https://docs.smartestqa.ai/en/mcp-connect.html#api-key) you copied the key from.
- **Fix:** Copy the key again with [**Copy API Key**](https://docs.smartestqa.ai/en/agent-pool-agents.html#api-key), paste it in the [extension settings](https://docs.smartestqa.ai/en/mcp-connect.html#claude-desktop) (or [run the install command again](https://docs.smartestqa.ai/en/mcp-connect.html#claude-code)) and restart the client.

### Problem: “not allowed for this account (403)” or ACCESS DENIED _(Access)_

- **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](https://docs.smartestqa.ai/en/company-settings-users.html#project-access). For an action your role cannot do, ask an Admin to do it: [roles are fixed](https://docs.smartestqa.ai/en/company-settings-roles.html#matrix), so an Admin cannot add a single permission to your role. Do not renew the key: it is fine.

### Problem: The assistant cannot reach the SmartestQA server, or it times out _(Network)_

- **Fix:** Check the internet or VPN connection of the machine the MCP runs on, and that a company proxy allows SmartestQA. Then ask again.

### Problem: The assistant works on the wrong project _(Use)_

- **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.

### Problem: “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](https://docs.smartestqa.ai/en/mcp-connect.html#manage).

### Problem: The assistant reports STALE_PREVIEW _(Changes)_

- **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](https://docs.smartestqa.ai/en/mcp-safe-changes.html#previews).

### Problem: “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](https://docs.smartestqa.ai/en/mcp-safe-changes.html#confirmations).

### Problem: “only an admin can remove records (your role: …); nothing was removed” _(Changes)_

- **Fix:** Ask an [Admin](https://docs.smartestqa.ai/en/company-settings-roles.html#matrix) to approve and [confirm the removal](https://docs.smartestqa.ai/en/mcp-safe-changes.html#confirmations), or archive the records in SmartestQA if your role allows it.

### Problem: A scenario is BLOCKED _(Scenarios)_

- **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](https://docs.smartestqa.ai/en/mcp-safe-changes.html#scenario-flow)): you **fixed** the cause (app, [data](https://docs.smartestqa.ai/en/data-source-variables.html), [environment](https://docs.smartestqa.ai/en/automate-editor.html#environment)), the **proof** it [checks](https://docs.smartestqa.ai/en/automate-steps-assertions.html) must change, or the scenario must be **split**. It runs again only after you confirm “Run it again?”.

### Problem: A dry run on my agent does not start _(Scenarios)_

- **Fix:** The agent must be [online in Test Agents](https://docs.smartestqa.ai/en/agent-pool-agents.html#agent-status). See [the agent fix](https://docs.smartestqa.ai/en/quick-start-troubleshooting.html#fix-agent-offline), or ask for [the dry run on the server](https://docs.smartestqa.ai/en/automate-dry-run.html#web-targets).

### Problem: The assistant reports UNKNOWN_TOOL or RULES_OUTDATED _(Use)_

- **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](https://docs.smartestqa.ai/en/mcp-connect.html#manage) (`smartest-mcp --update`, or a new .mcpb) and start a new chat.

### Problem: A write is refused because of the language _(Use)_

- **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.
