> **Building with AI coding agents?** If you're using an AI coding agent, install the official Scalekit plugin. It gives your agent full awareness of the Scalekit API — reducing hallucinations and enabling faster, more accurate code generation. > > - **Claude Code**: `/plugin marketplace add scalekit-inc/claude-code-authstack` then `/plugin install @scalekit-auth-stack` > - **GitHub Copilot CLI**: `copilot plugin marketplace add scalekit-inc/github-copilot-authstack` then `copilot plugin install @scalekit-auth-stack` > - **Codex**: run the bash installer, restart, then open Plugin Directory and enable `` > - **Skills CLI** (Windsurf, Cline, 40+ agents): `npx skills add scalekit-inc/skills --list` then `--skill ` > > `` / ``: `agent-auth`, `full-stack-auth`, `mcp-auth`, `modular-sso`, `modular-scim` — [Full setup guide](https://docs.scalekit.com/dev-kit/build-with-ai/) --- # 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=""` **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-` 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: ```sh 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. --- ## More Scalekit documentation | Resource | What it contains | When to use it | |----------|-----------------|----------------| | [/llms.txt](/llms.txt) | Structured index with routing hints per product area | Start here — find which documentation set covers your topic before loading full content | | [/llms-full.txt](/llms-full.txt) | Complete documentation for all Scalekit products in one file | Use when you need exhaustive context across multiple products or when the topic spans several areas | | [sitemap-0.xml](https://docs.scalekit.com/sitemap-0.xml) | Full URL list of every documentation page | Use to discover specific page URLs you can fetch for targeted, page-level answers |