Troubleshooting MCP auth

This guide helps you diagnose and resolve common issues when integrating Scalekit as an authentication server for your MCP servers. When you add authentication to MCP servers, you may encounter configuration problems, network issues, or client-specific limitations. This reference covers the most common scenarios and provides step-by-step solutions.

Use this guide to troubleshoot setup problems, resolve CORS and network issues, understand client-specific behavior, and implement best practices for your authentication setup.

Configuration & Setup Issues

I’m getting an access token but no refresh token

Add the offline_access scope to your authorization request. Without it, Scalekit does not issue a refresh token alongside the access token.

Include it with your other scopes:

openid profile email offline_access

Once added, subsequent logins will return both an access token and a refresh token.

---

My MCP server is not connecting to the MCP Inspector

When your MCP server fails to connect to the MCP Inspector, this typically indicates a problem with the authentication handshake or metadata configuration. Follow these diagnosis steps to identify the issue.

Verify the MCP server is responding correctly:

1. Open your browser’s developer tools (Network tab)
2. Navigate to your MCP server URL (e.g., http://localhost:3002/)
3. Confirm the response returns a 401 status code
4. Check the response headers for www-authenticate containing resource_metadata="<metadata-url>"

Validate the metadata:

1. Copy the metadata URL from the www-authenticate header
2. Open it in your browser
3. Confirm the JSON structure matches what you see in your Scalekit dashboard

Note

If all checks pass but the connection still fails, check the CORS & Network Issues section below.

I’m getting a redirect_uri mismatch error during authorization

This error typically occurs when your MCP client has cached an old MCP server domain after you’ve changed it. The client continues sending requests to the old URL, which doesn’t match your current Scalekit configuration.

Clear cached authentication by client type:

MCP-Remote:

1. Delete the cached configuration folder: ~/.mcp-auth/mcp-remote-<version>
2. Reconnect to your MCP server

VS Code:

1. Open the Command Palette (Cmd/Ctrl + Shift + P)
2. Search for Authentication: Remove Dynamic Authentication Provider
3. Select and remove the cached entry
4. Reconnect to your MCP server

Claude Desktop:

Caution

Claude Desktop does not currently support clearing cached authentication data. As a workaround, use a different domain or subdomain for your MCP server, or contact Claude support for assistance.

GitHub Copilot CLI: stale cached credentials after environment switch

GitHub Copilot CLI caches OAuth client credentials locally. If you switch your Scalekit environment (for example, from US to EU), the cached client_id no longer matches the new environment and login fails with unable to retrieve client by id.

Resolution:

1. Locate and delete the cached OAuth config files:

   rm -rf ~/.copilot/mcp-oauth-config

2. Reconnect your MCP server in GitHub Copilot CLI — it will register a fresh client against the correct environment.

Note

If you cannot find the files using the path above, also check ~/.config/github-copilot/ for any cached MCP auth files.

---

CORS & Network Issues

I see CORS errors in the network logs when using MCP Inspector

CORS errors occur when your MCP client cannot make cross-origin requests to your Scalekit environment during the authentication handshake. This prevents the authentication flow from completing successfully.

Resolution:

1. Navigate to Dashboard > Authentication > Redirect URLs > Allowed Callback URLs
2. Add your MCP Inspector URL to the allowed list: http://localhost:6274/
3. Retry the connection

Development vs Production URLs

Ensure you add callback URLs for both your development (http://localhost:6274/) and production environments to avoid CORS errors in either environment.

Calls from the MCP client are not reaching my MCP server

If requests from your MCP client silently fail to reach your server, a proxy or firewall may be blocking them. This often happens in corporate environments or when using CDN services.

Troubleshooting steps:

1. Check if you’re using a proxy (e.g., Cloudflare, AWS WAF, corporate proxy)
2. Configure your proxy to allow or exempt requests from your MCP client to your server domain
3. Review proxy logs to confirm whether requests are being blocked
4. Test direct connectivity from your client machine to your MCP server (without proxy, if possible)

Note

Some corporate proxies require explicit whitelisting of authentication endpoints. Contact your network administrator if you suspect this is the case.

---

Client-Specific Issues

Claude Desktop ignores custom ports when connecting to MCP servers

Claude Desktop currently only supports standard HTTPS traffic on port 443. If your MCP server runs on a custom port (e.g., https://mymcp.internal:8443/), Claude Desktop will still attempt to connect to port 443, causing the connection to fail.

Workaround options:

1. Expose your MCP server on port 443 (requires a proxy or load balancer)
2. Use a reverse proxy that listens on 443 and forwards requests to your custom port

Note

Future versions of Claude Desktop may add custom port support. Check the Claude Desktop release notes for updates.

Multiple authentication tabs open when using both MCP-Remote and Claude Desktop

Recent versions of Claude Desktop have introduced Connectors functionality, eliminating the need to run MCP-Remote separately. Claude Desktop includes a Custom Connector feature that allows you to configure MCP servers directly without additional tools.

Recommendation:

• Use Claude Desktop’s built-in Custom Connector feature for MCP server management
• Disable or stop MCP-Remote if you’re only using Claude Desktop
• If you have a specific use case requiring both, contact Claude’s official support

Tip

To avoid duplicate authentication flows, ensure you’re using only one MCP client at a time.

My browser is not getting invoked during authentication

Some MCP clients require permission to open your default browser during the authentication flow. If your browser doesn’t launch, the authentication handshake may timeout, preventing successful authentication.

Resolution by operating system:

macOS:

1. Open System Preferences > Security & Privacy > App Management
2. Ensure the MCP client has permission to open applications
3. Restart your MCP client

Windows:

1. Navigate to Settings > Privacy > App permissions
2. Enable Allow apps to manage your default app settings
3. Restart your MCP client

Linux:

1. Ensure xdg-open or your default browser opener is installed: which xdg-open
2. Verify the command is accessible from your terminal
3. Restart your MCP client

Note

After updating permissions, always restart your MCP client to ensure the changes take effect.

---

Best practices

Follow these best practices to avoid common issues and maintain a robust MCP authentication setup:

1. Use separate Scalekit environments for development and production to prevent configuration conflicts
2. Register MCP servers with environment-specific domains:
   • Development: https://mcp-dev.yourdomain.com/
   • Production: https://mcp.yourdomain.com/
3. Update your MCP client configuration to point to the correct Scalekit environment for each deployment
4. Test authentication independently in each environment before deploying to production
5. Monitor authentication logs in Dashboard > Authentication > Logs to identify and resolve issues quickly
6. Keep callback URLs updated whenever you change domains or ports

Environment management

Maintain separate environment variables for your MCP server configuration (e.g., SCALEKIT_ENVIRONMENT_URL, MCP_SERVER_URL) to easily switch between development and production environments.