Troubleshooting Guide.

Either no PROMPTOT_API_KEY was sent, or the key was revoked from the dashboard.

1. Check that PROMPTOT_API_KEY is set in your MCP client config (e.g. claude_desktop_config.json for Claude Desktop).
2. Verify the key still exists in the dashboard's API Keys page.
3. If revoked, generate a new MCP key and update your config. Restart the MCP client fully so it re-reads the config.

Your MCP key was generated without the write scopes required for this operation. This most often happens with pre-MCP keys which only have prompts:read.

1. Upgrade the existing key by hitting PATCH /api/api-keys/:id/scopes.
2. Or generate a new MCP key from the dashboard using the Generate MCP Key button — that applies the default MCP scope set automatically.
3. See the scopes reference for the full scope vocabulary.

Your monthly AI credit pool is empty. Free plan = 50 credits/month, Pro = 1,000/month. Each call to an AI-scoped tool consumes credits.

1. Wait for the next billing period — credits reset on the first of the month.
2. Upgrade your plan from the dashboard billing page.
3. Or generate an MCP key with AI features OFF — this gives you the full MCP_DEFAULT_SCOPES set without any AI-scoped tools.

Your plan's monthly API call quota is exhausted. Free plan = 1,000 calls/month, Pro = 100,000 calls/month, Enterprise = unlimited.

1. Check current usage in /admin/mcp on the dashboard.
2. Upgrade to a plan with a larger quota.
3. Wait for the next monthly reset if you're close to the period end.

You've hit the per-key rate limit. Standard API keys cap at 100 req/min; MCP keys get a higher default of 300 req/min because agent traffic is naturally bursty.

1. Slow down or batch requests. The limit is per-minute — back off for 60 seconds and the counter resets.
2. Contact support if you need a higher cap for legitimate bursty workloads.

The config file has a syntax error, the wrong path, or Claude Desktop wasn't fully restarted after editing. Node 20+ is also required to run the MCP server binary.

1. Open ~/Library/Application Support/Claude/claude_desktop_config.json and validate it with a JSON linter — a trailing comma will silently break tool loading.
2. Fully quit Claude Desktop with Cmd-Q (closing the window isn't enough — the process keeps running) and relaunch.
3. Run node --version in a terminal to confirm Node 20+ is installed and on your PATH.

The hosted MCP server runs on Railway with a 30-second function timeout. Long-running tools — especially large evaluation runs — can exceed this window.

1. Split large operations into multiple smaller calls. For example, run evaluations on a subset of test cases per call rather than all at once.
2. For stdio-based clients running the MCP server locally via npx @prompt-ot/mcp, there is no 30s cap — use the local server for heavy workloads.

The MCP server caps text outputs at 2000 tokens by default to protect the host LLM's context window from runaway tool output.

1. Pass truncate: false to the tool call to get the full text.
2. Or raise the cap with max_tokens: 8000.
3. For guaranteed full output, use the promptot://prompts/{id}/markdown MCP resource — resources are never truncated.

The user installed the MCP server with npx @prompt-ot/mcp directly, bypassing the dashboard install snippet that sets PROMPTOT_MCP_CLIENT={slug}.

1. Re-install via the dashboard's Install button. It copies a config snippet that sets the PROMPTOT_MCP_CLIENT env var so the server reports the correct client identifier for attribution.
2. Or manually add "PROMPTOT_MCP_CLIENT": "claude-desktop" (or whichever client you're using) to the env section of your config.

The signed-in user account doesn't have edit access to the project selected on the consent screen. This happens when users bounce between org memberships or when project-level access has been restricted.

1. Confirm the correct user account is signed in to PromptOT in the same browser.
2. Check Settings > Members to verify the user is a member of the org that owns the target project.
3. If using project-level access, confirm the user is listed in member_project_access for that project or has all_projects_access on their org membership.