> ## Documentation Index
> Fetch the complete documentation index at: https://alphacastio.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://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:

```json theme={null}
{
  "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](/mcp/configuration/claude-desktop) 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](/mcp/configuration/other-clients#hosted-remote-oauth) 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](https://www.alphacast.io/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](/api/errors#402-payment-required).

## 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](/mcp/configuration/other-clients#hosted-remote-oauth) 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](#no-admin-rights-to-install-nodejs-windows).
* 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](https://modelcontextprotocol.io/).
* For client-specific issues (Claude Code, Codex, etc.), check that client's documentation — the way each client surfaces tool-call errors varies.