Troubleshooting Common Issues

Solutions to common problems you might encounter when using the ImproveFast MCP server.

Common Errors

Error Message	Cause	Solution
"Variant not found in experiment"	Variant name doesn't match initialized variants	Ensure variant names match exactly (case-sensitive) with those from `initialize`
"Experiment ID mismatch"	Using wrong experiment ID	Use the `experimentId` returned from `initialize`
"No experiment initialized"	Calling `select`, `record`, or `status` before `initialize`	Call `initialize` first to create an experiment
Score validation error	Score outside [0, 1] range	Normalize your metrics to a 0-1 scale before recording

Symptom	Possible Cause	Fix
MCP server not appearing in client	Configuration not loaded	Restart your MCP client (Claude Desktop, Claude Code, Cursor, etc.) after adding the server
Tools not available	Server URL incorrect	Verify you're using `https://improve.fast/mcp` (not `/mcp/` with trailing slash)
"Service temporarily overloaded"	High traffic to hosted service	Wait a moment and retry. The system uses automatic retries with backoff.

Not enough data: Convergence requires about 50 evaluations per variant. With 3 variants, expect ~150 total evaluations before a winner is declared.
No winner appearing: Winners only appear when convergence criteria are met (sufficient data + clear separation). Check status to see progress.
Score range: Scores must be between 0 and 1. The server rejects values outside this range (no automatic clamping).
Variant consistency: Variant names are case-sensitive. "template-A" and "template-a" are different variants.
Experiment isolation: Each experiment ID is separate. Don't mix data across experiments.
Experiment expiration: Experiments automatically expire after 7 days for privacy. Start a new experiment if yours has expired.

If you're still experiencing issues, here are some resources: