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.

1. Open Connectors

   In Claude, open Customize (left sidebar) → Connectors. (Depending on your Claude version this may also live under your profile → Settings → Connectors.)

2. Add a custom connector

   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.

3. Connect and sign in

   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.

4. Verify in a new chat

   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. On a corporate machine without admin rights, see Install Node.js without admin rights.

1. Get your API key

   Sign in to Alphacast and open 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.

2. Open the config file

   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.

3. Add the server

   If the file is empty or doesn’t exist, paste this entire block (replace YOUR_API_KEY with your key):

   claude_desktop_config.json

   {
     "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:

   claude_desktop_config.json

   {
     "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.

4. Restart Claude Desktop

   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.

5. Verify it actually works

   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 or use the full path to npx.cmd
   401 Unauthorized	Invalid or missing API key	Authentication errors
   JSON parse error / server missing entirely	Malformed config file	Fix the config JSON

Next steps

Troubleshooting

Setup, authentication, and connection fixes — including enterprise Windows environments.

Examples

Full prompts that combine search, download, and provider tools.