MCP Connection Troubleshooting

This guide covers common issues when connecting to Eyevinn Open Source Cloud via MCP (Model Context Protocol) in Claude Desktop or other MCP clients.

Verify Your Connection

Once you have connected your AI assistant to OSC via MCP, run a quick sanity check before doing anything else.

Ask your AI assistant:

"List all available OSC services"

If the connection is working, you will see a list of services available on the platform (databases, media tools, storage services, and more). If you get an error or the assistant says it does not have any tools available, work through the troubleshooting steps below.

Finding Your API Token

Several troubleshooting steps and manual configuration options require your personal access token. Here is how to find it:

  1. Sign in at app.osaas.io
  2. Click Settings in the left navigation menu
  3. Select the API tab at the top of the settings page
  4. Your personal access token is displayed on this page. Click the copy icon to copy it to your clipboard.

Keep your token private. Anyone with this token can access your OSC account. If you suspect it has been exposed, regenerate it from the same Settings/API page.

Troubleshooting Common Issues

Invalid or Expired Token

Symptom: Tools stop responding, or you see authentication errors like 401 Unauthorized.

Fix: 1. Go to Settings/API in the OSC web console 2. If your token has expired, click Regenerate to create a new one 3. Update your MCP client configuration with the new token (see the client-specific setup guides for where to paste it) 4. For Claude Desktop, remove the MCP connector and re-add it to trigger a fresh OAuth flow

Wrong MCP Endpoint

Symptom: The connection cannot be established, or you see a "server not found" error.

Fix: Use the correct MCP endpoint for your environment:

Environment MCP URL
Production (global) https://mcp.osaas.io/mcp
Production (Sweden) https://mcp.svc.prod-se.osaas.io/mcp

Make sure the URL ends in /mcp, not /sse or just /.

Node.js Not Installed (Claude Code)

Symptom: The claude mcp add command fails with "node: command not found" or similar.

Fix: Claude Code requires Node.js 18 or later. Install it from nodejs.org or via your package manager:

# macOS with Homebrew
brew install node

# Ubuntu / Debian
sudo apt install nodejs npm

# Windows: download the LTS installer from https://nodejs.org/

After installing Node.js, run the MCP connection command again from the Settings/MCP page in the OSC web console.

Firewall or Proxy Environments

Symptom: Connection times out, or authentication redirects never complete in corporate environments.

Fix: 1. Ensure outbound HTTPS (port 443) is allowed to mcp.osaas.io 2. If your proxy intercepts HTTPS traffic, add mcp.osaas.io and app.osaas.io to your proxy bypass list 3. Try disconnecting from your VPN temporarily to confirm whether it is blocking the connection 4. If the OAuth browser flow is blocked, use a personal access token for direct authentication instead (see the manual configuration instructions in the AI agents guide)

Auth Window Doesn't Open

When you add the OSC MCP server to Claude Desktop and the OAuth authentication window doesn't appear:

Windows

  1. Check default browser: Ensure a default browser is set in Windows Settings → Apps → Default apps
  2. Try opening the auth URL manually: Copy and paste https://mcp.osaas.io/auth into your browser
  3. Check firewall/proxy: Corporate firewalls or VPNs may block the OAuth redirect. Try disconnecting from VPN temporarily
  4. Restart Claude Desktop: Close Claude Desktop completely (check system tray) and reopen it
  5. Update Claude Desktop: Ensure you're running the latest version — older versions may have OAuth compatibility issues

macOS

  1. Check default browser: System Settings → Desktop & Dock → Default web browser
  2. Try opening the auth URL manually: Visit https://mcp.osaas.io/auth in your browser
  3. Check if browser handles https:// links: Open Terminal and run open https://mcp.osaas.io/auth
  4. Restart Claude Desktop: Quit from the menu bar and reopen

Manual Auth Fallback

If the automatic OAuth flow doesn't work, you can authenticate manually: 1. Open https://mcp.osaas.io/auth directly in your browser 2. Complete the sign-in process 3. After successful authentication, return to Claude Desktop 4. The MCP connection should now be established

Connected But No Tools Appear

If Claude Desktop shows the MCP server as connected but no tools are available: 1. Verify the MCP URL: Use https://mcp.osaas.io/mcp (not /sse or other paths) 2. Re-open Claude Desktop: Close and reopen Claude Desktop after connecting 3. Check your plan: Some tools require a paid plan. Use the chat to ask about your current plan

Authentication Expired

MCP authentication tokens expire periodically. If tools stop working: 1. Remove the MCP server from Claude Desktop settings 2. Re-add it with the URL https://mcp.osaas.io/mcp 3. Complete the OAuth flow again

Still Having Issues?

Join the community Slack at https://slack.osaas.io for help from the OSC team.