MCP Troubleshooting

Common errors and fixes when connecting clients to the Alphacast MCP server, authenticating, or running tools.

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.

Setup issues

claude_desktop_config.json is not where the docs say

Enterprise deployments of Claude Desktop can install under a different directory than the standard %APPDATA%\Claude\ — for example %LOCALAPPDATA%\Claude-3p\. The documented paths are defaults, not guarantees.

Fixes:

• In Claude Desktop, open your profile → Settings → Developer → Edit Config. This always opens the folder containing the config file that your installation actually reads — use it instead of navigating to a hardcoded path.
• Alternatively, search for claude_desktop_config.json with Windows Search (or Spotlight on macOS).

No admin rights to install Node.js (Windows)

The standard Node.js .msi installer requires administrator privileges, which many corporate machines don’t allow. You don’t need admin rights to run the MCP server — use the portable binary instead:

1. Download the Windows Binary (.zip) from nodejs.org/en/download (choose “Standalone binary”, not the installer).
2. Extract it to a folder you own, for example C:\Users\<you>\nodejs\.
3. Add that folder to your user-level PATH (no admin needed): open the Start menu, search for “Edit environment variables for your account”, select Path → Edit → New, and add the folder. Then fully restart your MCP client so it picks up the new PATH.
4. Verify in a new terminal: npx --version.

If you can’t (or don’t want to) modify PATH, skip step 3 and point your MCP config at the binary directly with an absolute path:

{
  "mcpServers": {
    "alphacast": {
      "command": "C:\\Users\\<you>\\nodejs\\npx.cmd",
      "args": ["-y", "@alphacast/mcp"],
      "env": {
        "ALPHACAST_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

Note the doubled backslashes — JSON requires \\ for each \ in Windows paths.

The config JSON is invalid (server disappears or never loads)

If your client ignores the server after a restart — it doesn’t appear in the server list at all — the config file is almost certainly malformed JSON.

Common causes:

• A missing comma between two server entries, or an extra trailing comma after the last one.
• Unbalanced braces after pasting a snippet into an existing file.
• The file was saved as claude_desktop_config.json.txt (Windows hides extensions by default).

Fixes:

• Paste the full file content into a Claude chat and ask it to find and fix the JSON error — this catches formatting mistakes immediately.
• If it still fails, replace the entire file content with the complete config block from the Claude Desktop guide instead of merging snippets.
• When saving with Save As on Windows, set “Save as type” to All Files to avoid the hidden .txt extension.

Authentication errors

Hosted server: browser login doesn’t open or won’t complete

On the hosted server (https://mcp.alphacast.io/mcp) the first connection triggers an OAuth login in your browser. If nothing opens, or the flow never finishes:

Fixes:

• In Claude Code, run /mcp, select alphacast, and choose Authenticate to trigger the login manually. In Cursor, open Settings → MCP and click the server’s Login button.
• If the browser opened but the page errored, make sure you can reach https://auth.alphacast.io and https://www.alphacast.io directly (a VPN or proxy may block them).
• Using the mcp-remote bridge? Clear its cached state and retry: delete the ~/.mcp-auth folder, then restart the client so a fresh login is requested.
• Confirm your client actually supports remote MCP servers. If it doesn’t, reach the hosted server through the mcp-remote bridge instead, or use the local npm package.

Hosted server: 401 Unauthorized after it was working

The OAuth token expired or was revoked, and the client didn’t refresh it.

Fixes:

• Re-authenticate: in Claude Code run /mcp → alphacast → Authenticate; in other clients, reconnect / log in again from the MCP settings.
• If you revoked the session in your Alphacast account, that’s expected — sign in again to mint a new token.
• For the mcp-remote bridge, delete ~/.mcp-auth and restart the client to force a fresh login.

Local server: 401 Unauthorized on every tool call

The ALPHACAST_API_KEY environment variable is missing, empty, or the key is invalid. (This applies to the local npm package; the hosted server uses OAuth — see above.)

Fixes:

• Verify the key is set in your client’s MCP configuration under "env": { "ALPHACAST_API_KEY": "..." }.
• Regenerate the key in Alphacast → Settings if the original was rotated, leaked, or revoked.
• For Claude Code, run claude mcp list and confirm the environment variable is configured correctly.
• For Codex, run codex mcp list and verify the env block in your config.toml.

403 Forbidden on a specific tool call

Authentication succeeded (OAuth token or API key) but your account does not have the permission required for this action.

Fixes:

• Read access required: ensure your account has at least Read permission on the target repository.
• Write tools (pipeline authoring) need Write access on the repository, and — on the hosted server — the mcp:write scope, which is granted during the OAuth consent step.
• 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

Hosted server: client can’t connect to the URL

The client can’t establish the Streamable HTTP connection to https://mcp.alphacast.io/mcp.

Fixes:

• Confirm the URL is exact — https://mcp.alphacast.io/mcp, including the /mcp path. A trailing typo or a missing path returns a 404 the client reports as a connection failure.
• Check outbound network access to mcp.alphacast.io and auth.alphacast.io on port 443: curl -I https://mcp.alphacast.io/mcp should return 401 (auth required), not a timeout or DNS error.
• If your client doesn’t support remote MCP servers at all, it will silently ignore the url field. Use the mcp-remote bridge or the local npm package instead.

Local server: 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. No admin rights to install it? See the portable install.
• Verify the command in your MCP config: "command": "npx", "args": ["-y", "@alphacast/mcp"].
• On Windows, if npx is not on PATH, use the full path to npx.cmd as the command, e.g. "command": "C:\\Program Files\\nodejs\\npx.cmd" (or wherever Node is installed — note the doubled backslashes).
• Check your client’s MCP logs for the specific error message (e.g., run claude mcp list in Claude Code or codex mcp list in Codex).

Server shows “running” but no tools appear in chat

In Claude Desktop, the server can show a “running” badge in Settings → Developer even when it failed to start or authenticate. The chat gives no error: there’s no tools icon, and Claude answers your questions from general knowledge as if the MCP server didn’t exist.

Fixes:

• Don’t trust the badge — verify in a new chat: the tools menu (slider icon) should list alphacast with 32 tools, and a test prompt like “List my Alphacast repositories” should produce a visible tool call. An answer with no tool call means the server isn’t connected.
• Open Settings → Developer → Open MCP Logs. The logs are the only reliable way to diagnose this state. Typical causes: npx not found (Node.js missing or not on PATH), an invalid ALPHACAST_API_KEY, or a malformed config file.
• After fixing, quit Claude Desktop completely from the system tray (closing the window is not enough) and relaunch.

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 Code, Codex, etc.), check that client’s documentation — the way each client surfaces tool-call errors varies.