Skip to content
Back to Docs
MCP Reference

Troubleshooting

Common errors when using the PromptOT MCP server, their root causes, and exact steps to fix them. If something's still broken after trying these, reach out at support@promptot.com.

401 Unauthorized — Missing or revoked API key

{ "error": { "code": "UNAUTHORIZED", "message": "Missing or revoked API key" } }

Cause

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

Fix

  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.

403 INSUFFICIENT_SCOPE — Missing required scope

{ "error": { "code": "INSUFFICIENT_SCOPE", "message": "Missing required scope: prompts:write" } }

Cause

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.

Fix

  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.

403 AI_CREDITS_EXHAUSTED

{ "error": { "code": "AI_CREDITS_EXHAUSTED", "message": "Monthly AI credit pool exhausted" } }

Cause

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.

Fix

  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.

429 API_QUOTA_EXCEEDED

{ "error": { "code": "API_QUOTA_EXCEEDED", "message": "Monthly API call quota exhausted" } }

Cause

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

Fix

  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.

429 Too Many Requests (rate limit)

{ "error": { "code": "RATE_LIMITED", "message": "Too many requests" } }

Cause

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.

Fix

  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.

MCP server doesn't show up in Claude Desktop

# No "promptot" tool appears in Claude Desktop

Cause

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.

Fix

  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.

Tool calls hang or timeout

# Client shows "timed out waiting for response"

Cause

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

Fix

  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.

Compiled prompt is truncated

# Output ends with "... (truncated at 2000 tokens)"

Cause

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

Fix

  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.

"unknown" shows up as the client name in /admin/mcp

# Admin panel shows client: unknown

Cause

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

Fix

  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.

OAuth consent screen says "Project not found"

# Consent screen: "Project not found or you don't have access"

Cause

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.

Fix

  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.