MCP setup issues
Common problems connecting Claude Desktop, Cursor, or a custom MCP client to the ArbiSim MCP server.
"arbisim-guard" not appearing in tool list
→ Restart Claude Desktop or Cursor after editing the config file. Changes do not take effect until the app restarts.
→ Check that your config file is valid JSON. A trailing comma or missing brace will silently break the entire MCP section.
→ Verify the file path. Claude Desktop config on macOS is at:
~/Library/Application Support/Claude/claude_desktop_config.json
→ Cursor MCP config on macOS is at:
~/.cursor/mcp.json
Tool call fails with "connection refused"
The MCP server process is not running or crashed on startup.
→ Make sure the gateway is built: npm run build --prefix gateway
→ Verify the path in your config points to the correct index.js:
{
"mcpServers": {
"arbisim-guard": {
"command": "node",
"args": ["/absolute/path/to/ArbiSim/gateway/dist/index.js", "--mcp"],
"env": { "GATEWAY_API_KEY": "ask_free_a1b2_..." }
}
}
}Use an absolute path, not a relative one — the MCP host may run the process from a different working directory.
Tool returns "API key missing"
The GATEWAY_API_KEY environment variable was not passed to the MCP server process.
→ Confirm the env block is inside the server config, not at the top level.
→ The key must start with ask_ — if you copied a partial key, regenerate it from the API Keys page.
Simulation runs but always returns FAILED
The MCP layer is working but the simulation worker is not reachable.
→ Check that the Python worker is running: python3 workers/src/main.py
→ Confirm .env has valid DATABASE_URL pointing to your Neon Postgres instance.
→ Try the REST API directly to isolate whether the issue is MCP-specific or deeper.