Skip to main content
This page covers the failures you’ll most likely run into. If your issue isn’t here, check your client’s MCP logs first — they almost always reveal the underlying HTTP status code or message.

​
Authentication errors

​
401 Unauthorized on every tool call

The ALPHACAST_API_KEY environment variable is missing, empty, or the key is invalid. Fixes:
  • Verify the key is set in your client’s MCP configuration under "env": { "ALPHACAST_API_KEY": "..." }.
  • Regenerate the key in Alphacast → Settings → API Keys if the original was rotated, leaked, or revoked.
  • For Claude Code, run claude mcp list and confirm the environment variable is configured correctly.
  • For Cursor, open Settings → MCP and verify the env block in .cursor/mcp.json.

​
403 Forbidden on a specific tool call

The API key authenticated successfully but does not have the permission required for this action. Fixes:
  • Read access required: ensure the API key’s account has at least Read permission on the target repository.
  • Have the repository owner grant your account the missing permission level.

​
Quota errors

​
402 Payment Required

The action exceeds your plan’s quota — typically downloads or paid-tier provider usage. Fix: upgrade your subscription, or wait until the quota resets. See Error codes.

​
Connection errors

​
Client says “MCP server failed to start” or shows a red status

The client could not spawn the npx -y @alphacast/mcp subprocess. Fixes:
  • Ensure Node.js 18+ is installed and npx is on your system PATH. Run npx --version in a terminal to check.
  • Verify the command in your MCP config: "command": "npx", "args": ["-y", "@alphacast/mcp"].
  • On Windows, you may need the full path to npx.cmd if it’s not on PATH.
  • Check your client’s MCP logs for the specific error message (e.g., Claude Desktop → Developer → Open MCP Logs).

​
Tool calls hang or time out

The server calls the Alphacast REST API internally. If those calls fail or hang, tool calls will too. Fixes:
  • Confirm network access to api.alphacast.io and www.alphacast.io: curl -I https://api.alphacast.io.
  • If you’re behind a corporate proxy or VPN, ensure the proxy allows outbound traffic to those domains on port 443.

​
Data quirks

​
Downloads return a URL instead of rows

CSV downloads return an S3 pre-signed URL as the body instead of streaming the bytes. The MCP server detects this case and follows the URL transparently — but if you are inspecting raw HTTP traffic, you’ll see the URL pattern. Nothing to fix; this is expected.

​
IDs in errors look like strings

Error messages may show IDs as strings even though the API expects integers. The MCP server coerces strings to integers automatically when calling tools, so passing "42" instead of 42 works the same way.

​
Where to get help

  • For server-side issues, contact Alphacast support with the time of failure and the tool name. Server logs include the request ID.
  • For protocol-level questions about MCP itself, see the official MCP spec.
  • For client-specific issues (Claude Desktop, Cursor, etc.), check that client’s documentation — the way each client surfaces tool-call errors varies.