Troubleshooting
Fixes for common problems when connecting ToolJet MCP to Claude Code, Codex, or other MCP clients.
| Symptom | Cause and fix |
|---|---|
| The server reports a missing variable | TOOLJET_PAT or TOOLJET_DEPLOYMENT_URL didn't reach the server. Set them where your client reads them: your shell profile or Claude Code settings file for Claude Code, your shell profile for Codex, or the env block in your MCP configuration for other clients. Then restart your client, which reads them at launch. |
| Tools don't appear at all | Your client didn't start the server. Confirm node --version is 20 or newer and that your client can see it. For other MCP clients, also check that the path to bundle/index.js is absolute and correct. |
| Calls fail with an authentication error | The token is expired, revoked, or was copied incompletely. Create a fresh one under Profile settings > Personal access tokens. |
| Calls fail with a connection error | TOOLJET_DEPLOYMENT_URL is wrong or unreachable from your machine. If your API and UI are on different origins, set TOOLJET_URL to the backend origin. |
| The agent can't see the workspace you expected | A token's session is pinned to the workspace it was created in. Create a token in that workspace instead. |
| App links point at localhost | TOOLJET_DEPLOYMENT_URL is still at its default. Set it to your instance URL. |
| OAuth sign-in says AI client connections are unavailable or the request has expired | A connection request is valid for 10 minutes. Start again from your client. OAuth connections are available on ToolJet Cloud only; on a self-hosted instance, use a personal access token. |
| OAuth sign-in says you don't have access to connect an AI client | Your account can't access that workspace. Contact your workspace administrator. |
| OAuth sign-in asks you to open the connection in a separate tab | The sign-in page can't run inside an embedded frame. Open the link in its own browser tab. |
| An OAuth connection that worked before stops working | The connection expired, was disconnected under Profile settings > Connected AI clients, or was revoked after a password, membership, or login-settings change. Reconnect from your client, for example with /mcp in Claude Code or codex mcp login tooljet-oauth in Codex. |
Related​
Need Help?​
- Reach out via our Slack Community
- Or email us at support@tooljet.com
- Found a bug? Please report it via GitHub Issues