> ## 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.
# Connect Claude Desktop
> Connect Claude Desktop to the Alphacast MCP server — the hosted server as a custom connector (OAuth), or the local npm package via npx.
Claude Desktop can reach the Alphacast MCP server two ways: as a **hosted connector** (no install, sign in with OAuth) or as a **local process** launched via `npx` and defined in `claude_desktop_config.json`.
## Hosted (remote, OAuth) — recommended, no terminal
This is the simplest path: no JSON file to edit, no Node.js, no API key.
In Claude, open **Customize** (left sidebar) → **Connectors**. (Depending on your Claude version this may also live under your profile → **Settings → Connectors**.)
Click the **+** button → **Add custom connector**, and fill the two fields:
| Field | Value |
| ----- | ------------------------------ |
| Name | `Alphacast` |
| URL | `https://mcp.alphacast.io/mcp` |
The **OAuth Client ID / Secret** fields under **Advanced settings** are optional — leave them empty. Click **Add**.
The Alphacast connector opens showing *"You are not connected to Alphacast yet"* → click **Connect**. Claude opens your browser to sign in with your Alphacast account and authorize the `mcp:read` / `mcp:write` scopes. Once authorized, the connector shows the 32 tools.
Open a new chat, confirm the **Alphacast** tools appear in the tools menu, and send *"List my Alphacast repositories."* — you should see a `list_repositories` tool call.
**Usage notes for the hosted connector.** This version sometimes disconnects on its own, and it also disconnects if you log out of the Alphacast platform. To reconnect, go back to **Connectors** and click **Connect** again. You can check the state on that same Connectors screen: if Alphacast is really connected a check mark (✓) shows in the **Status** column; otherwise you'll see a **Connect** button.
Custom connectors require a Claude plan that supports them. If you don't see **Add custom connector**, use the local path below, or bridge the hosted server through `mcp-remote`: set `"command": "npx"`, `"args": ["-y", "mcp-remote", "https://mcp.alphacast.io/mcp"]` (no `env` block) in `claude_desktop_config.json` — it opens the same browser login.
## Local (npm package)
Claude Desktop launches the server as a local process defined in `claude_desktop_config.json`. The server runs via `npx` and communicates over stdio.
`npx` ships with Node.js. If `npx` is not found, install Node 18 or later from [nodejs.org](https://nodejs.org/). On a corporate machine without admin rights, see [Install Node.js without admin rights](/mcp/troubleshooting#no-admin-rights-to-install-nodejs-windows).
Sign in to Alphacast and open [Settings](https://www.alphacast.io/settings). Copy your API key. If you belong to multiple teams, make sure your active team subscription is selected first — the key inherits that team's permissions.
The most reliable way — it works no matter where Claude Desktop is installed:
1. In Claude Desktop, open your profile → **Settings** → **Developer**.
2. Click **Edit Config**. This opens the folder containing `claude_desktop_config.json`.
3. Open `claude_desktop_config.json` in any text editor.
For reference, the standard locations are:
| OS | Path |
| ------- | ----------------------------------------------------------------- |
| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| Windows | `%APPDATA%\Claude\claude_desktop_config.json` |
| Linux | `~/.config/Claude/claude_desktop_config.json` |
Enterprise deployments of Claude Desktop may use a different directory (for example `%LOCALAPPDATA%\Claude-3p\` on Windows). If the standard path doesn't exist on your machine, use the **Edit Config** button above, or search for `claude_desktop_config.json` with Windows Search.
**If the file is empty or doesn't exist**, paste this entire block (replace `YOUR_API_KEY` with your key):
```json claude_desktop_config.json theme={null}
{
"mcpServers": {
"alphacast": {
"command": "npx",
"args": ["-y", "@alphacast/mcp"],
"env": {
"ALPHACAST_API_KEY": "YOUR_API_KEY"
}
}
}
}
```
**If the file already has content** (other MCP servers or settings), add the `alphacast` entry inside the existing `mcpServers` object — don't paste the whole block again:
```json claude_desktop_config.json theme={null}
{
"mcpServers": {
"some-other-server": {
"command": "..."
},
"alphacast": {
"command": "npx",
"args": ["-y", "@alphacast/mcp"],
"env": {
"ALPHACAST_API_KEY": "YOUR_API_KEY"
}
}
}
}
```
The most common failure at this step is invalid JSON: a missing comma between server entries, an extra trailing comma, or unbalanced braces. If Claude Desktop silently ignores your server after a restart, the JSON is almost certainly malformed. Quick fix: paste the full file content into a Claude chat and ask it to find and fix the JSON error.
When saving on Windows, if your editor offers **Save As**, set "Save as type" to **All Files** so the file isn't saved as `claude_desktop_config.json.txt`.
Quit Claude Desktop completely — right-click the menu bar / system tray icon and choose **Quit**. Closing the window is not enough; the app keeps running in the background and won't reload the config. Then relaunch it.
The "running" badge next to the server in **Settings → Developer** is **not** proof that the server works. It can show "running" even when the server failed to start or authenticate. Always verify in the chat itself.
1. Open a **new chat** and click the tools menu (the slider icon). You should see the **alphacast** server listed with its 32 tools enabled.
2. Send a test prompt:
> "List my Alphacast repositories."
3. Confirm that Claude **calls a tool** — you'll see a `list_repositories` tool-call block in the response. If Claude answers from general knowledge with no tool call (and no tools icon appears), the server is not actually connected, even if the Developer tab says "running".
If verification fails, open **Settings → Developer → Open MCP Logs** — the logs are the only reliable way to diagnose a failed server. What to look for:
| Log message | Cause | Fix |
| ------------------------------------------ | ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `npx` not found / spawn error | Node.js missing or not on PATH | [Install Node.js](/mcp/troubleshooting#no-admin-rights-to-install-nodejs-windows) or use the [full path to `npx.cmd`](/mcp/troubleshooting#client-says-mcp-server-failed-to-start-or-shows-a-red-status) |
| `401 Unauthorized` | Invalid or missing API key | [Authentication errors](/mcp/troubleshooting#401-unauthorized-on-every-tool-call) |
| JSON parse error / server missing entirely | Malformed config file | [Fix the config JSON](/mcp/troubleshooting#the-config-json-is-invalid-server-disappears-or-never-loads) |
## Next steps
Setup, authentication, and connection fixes — including enterprise Windows environments.
Full prompts that combine search, download, and provider tools.