Setup help

Troubleshooting

First identify which path is failing. Hosted MCP uses browser OAuth. The workflow CLI uses an API key and local project files. Fixing one does not reconfigure the other.

Last reviewed July 14, 2026

Claude does not show SolidActions tools

1. Confirm the connector URL is exactly https://app.solidactions.com/mcp.
2. Finish the browser authorization flow; adding the URL alone is not authorization.
3. Return to Claude, start a new conversation, and retry the read-only verification prompt.
4. If you changed workspace access or product areas, remove the connector and authorize it again.

OAuth opened the wrong workspace

Do not approve the connection. Return to the workspace chooser and select the correct workspace. If you already approved it, remove the connector from Claude, revoke the old entry under Settings → MCP Connectionsin SolidActions, and reconnect so the authorization flow runs again.

The browser did not return to Claude

A completed authorization can leave the browser on a confirmation page. Switch back to Claude manually, start a new conversation, and run the verification prompt. Reconnect only if Claude still cannot discover the tools.

CLI authentication fails

• Use an API key from SolidActions settings, not the browser OAuth session used by MCP.
• Run the secret-safe login command from the workflow guide.
• If the key was displayed, logged, or pasted into shell history, revoke it and create a replacement.
• Use solidactions whoami to inspect the active host and workspace without printing the key.

The solidactions command is not found

1. Check Node.js with node --version; this guide uses Node.js 24.
2. Re-run npm install -g @solidactions/cli.
3. Open a new terminal so it reloads your npm global binary path.
4. If npm reports a permissions error, configure a user-owned npm global directory instead of using sudo.

Skills are missing or stale

For a new project, scaffold again in an empty directory with solidactions init project-name --claude. For an existing project, run solidactions ai init --claude from its root. For the shared agent layout, use --agents instead. Then confirm the five solidactions-*.md files exist in.claude/skills/ or .agents/skills/ and the SDK reference exists at.solidactions/sdk-reference.md.

Restart Claude Code after installing or refreshing skills. File presence proves installation; the behavioral verification prompt in the workflow guide proves the restarted agent actually discovers them.

The deploy fails

• Run npm install and npm run build inside the project before deploying.
• Confirm the project name matches the project value declared in solidactions.yaml.
• Confirm solidactions whoami shows the intended workspace.
• Read the complete CLI error before retrying; authentication, validation, and plan errors have different fixes.

A run completed but the result is wrong

Inspect it with solidactions run view RUN_ID. A top-level completed state means execution finished; it does not guarantee every workflow step produced the result you intended.

Clean up a local setup

• Use solidactions logout --global to remove the global CLI credential.
• Delete only the disposable project directory you created; this does not delete a deployed project.
• Remove the connector in Claude, then revoke its server-side credential under Settings → MCP Connections.

Reference: official packages, repositories, and API schema.