Skip to main content
Looking for a specific error code? See the error code reference — every ErrorCard in the inspector deep-links to a section there.
This guide covers common errors you might encounter when working with MCP servers and how to resolve them.

​
Connection Issues

​
Diagnose a connection failure

Most “failed to connect” / fetch failed / ECONNREFUSED / MCP error -32000: Connection closed / MCP error -32001: Request timed out reports come down to one of five root causes. Work through them in order — each step takes seconds.
  1. Is the server actually running? Open a second terminal and run the same command you’d ask Inspector to run. If it exits or prints a stack trace, fix that first — Inspector can only attach to a server that stays alive.
    A clean stdio process should sit waiting on stdin; a healthy HTTP server should respond with something other than Connection refused (the exact code varies — common responses are 405 Method Not Allowed for GET, 406 Not Acceptable if Accept headers are missing, or 400 Bad Request if the server expects a session header).
  2. Right port, right path? ECONNREFUSED 127.0.0.1:5555 means nothing is listening on that port — typo, wrong port, or the server is bound to 127.0.0.1 only while you’re calling it via a different hostname (or vice versa). SSE error: Non-200 status code (404) means the port is correct but the path is wrong: most MCP servers mount under /mcp or /sse, not /.
  3. Right transport selected? In the server card, the transport dropdown must match what your server speaks. STDIO servers won’t respond to HTTP attempts and vice versa. If you used a url: field in config.json, Inspector picks HTTP; if you used command: + args:, Inspector picks STDIO.
  4. Right auth setting? New servers default to Auto, which connects without credentials and escalates to OAuth on 401. For local development servers that have no auth, pick No Authentication to skip the escalation prompt. If you get 401, see Getting 401 Unauthorized errors below.
  5. Did the server actually finish booting before the handshake? MCP error -32001: Request timed out during initialize means the server didn’t respond to the handshake in time — usually because it’s still loading models, opening a database, or waiting on an upstream. Raise the Request timeout in Clients → your client → Request timeout (default 30,000ms), or reduce the server’s startup work.
If all five check out and you still see a failure, copy the full error from the JSON-RPC log into a GitHub issue or Discord thread.

​
(intermediate value).subtle is undefined

The browser’s Web Crypto API (crypto.subtle) is only available in secure contexts — that means HTTPS, or http://localhost / http://127.0.0.1. If you’re hitting Inspector over a non-localhost HTTP URL (for example, a LAN IP like http://192.168.1.10:6274), the browser disables crypto.subtle and OAuth/PKCE flows fail. Fix: open Inspector at http://localhost:6274 or http://127.0.0.1:6274, or put HTTPS in front of it. The hosted app and the desktop app are unaffected.

​
Server fails to start or connect

  • Use absolute paths: Specify the full path to your server
    • ✅ Good: /Users/yourname/project/server.py
    • ❌ Bad: ./server.py or server.py
  • For uv projects: Use the --directory flag with absolute path
  • Test your command first: Run the server command manually in a terminal to verify it works before adding it to Inspector
  • For HTTP servers: Verify the URL is accessible
    • Test with curl or a browser first

​
”Invalid host header” when connecting to an HTTP server

This response comes from your MCP server, not from MCPJam Inspector. The server’s HTTP layer is rejecting the request because the Host header isn’t on its allowlist. Most common culprits:
  • Next.js / webpack-dev-server — both block unknown hosts by default in dev mode. Add your host to allowedHosts (webpack-dev-server) or experimental.allowedDevOrigins (Next.js).
  • FastAPI / Starlette (Python) — TrustedHostMiddleware rejects hosts not in allowed_hosts. Add the host the inspector is calling from, or temporarily set allowed_hosts=["*"] for local testing.
  • Reverse proxies (nginx, Caddy) — check the server_name / host_match config.
Quick check: test the same URL with curl http://localhost:PORT/mcp — if curl gets the same error, it’s definitely server-side, not inspector.

​
Authentication Issues

​
Server fails to connect with authentication errors

If your server is failing to connect, first verify you’ve selected the correct authentication option:
  • Auto (default) - Connects without credentials first; if the server returns 401, MCPJam prompts you to continue with OAuth. Use this when you’re unsure what the server requires.
  • No Authentication - Use this for local or development servers that don’t require authentication
  • Bearer Token - Use this if you already have an API token from the server
  • OAuth 2.0 - Use this for servers that require OAuth authorization flow

​
”resolves to a private/reserved IP address” during OAuth discovery

The web app at app.mcpjam.com runs on our servers, so it can only reach authorization servers that are reachable from the public internet. A local authorization server — on localhost, on your LAN, or on a hostname like auth.local that resolves to 127.0.0.1 — is not, and discovery is refused with a message naming the address it resolved to. Solution: use the local inspector for a local OAuth setup:
The local inspector reaches loopback, LAN, CGNAT, and unique-local addresses, including hostnames that resolve to them, because it runs on your machine. No flag or configuration is needed. The same applies to the CLI, which reaches private targets by default and takes --https-only when you want to reproduce the hosted policy. Link-local and cloud-metadata addresses (169.254.169.254 and friends) are refused everywhere, including locally. If you see the message naming a “link-local or cloud-metadata host”, something is pointing discovery at an instance-metadata endpoint rather than at an authorization server.

​
”Saved credentials were not sent” (403 on connect)

If a connection fails with a message like:
“my-server” was not connected. Its saved credentials were entered for https://old.example.com, and it now points at https://new.example.com. Re-enter the credentials for the new address to connect.
This means the server’s URL was changed to a different origin (scheme, host, or port) after credentials were saved, and MCPJam refused to send those credentials to the new destination. When this error occurs, MCPJam automatically opens the server’s Configuration panel so you can re-enter the credentials immediately. Solution: Re-enter the server’s credentials for the current URL.
  1. In the Connection overrides or Environment variables section of the configuration panel, reveal and re-enter the credentials.
  2. Save the server. The new credentials are now bound to the current origin.
If you see this error and did not intentionally change the server’s URL, check the Destination history in the server detail panel to see when the origin changed and who made the edit.

​
”Credential export policy” (403 on connect)

If a connection fails with a message like:
“my-server” uses saved credentials that your organization keeps inside MCPJam-hosted connections. Connect it from MCPJam in the browser, or ask an organization admin to change the credential export policy.
This means your organization has a credential export policy that prevents saved credentials from being used outside MCPJam-hosted connections. Re-authorizing will not help — the policy applies to the credential itself, not to your session. Solutions:
  • Connect from MCPJam in the browser — open the server from app.mcpjam.com instead of a local inspector or CLI.
  • Ask an organization admin to change the policy — an admin can update the credential export policy in the organization settings to allow credentials to be used from outside hosted connections.

​
Getting 401 Unauthorized errors

If you’re seeing 401 Unauthorized errors when trying to connect to your server, this typically means the server requires authentication that hasn’t been set up yet. Solution:
  • If you’re using Auto (the default): MCPJam will prompt “Continue with OAuth?” when it receives a 401. Accept the prompt to start the OAuth flow.
  • If you’re using No Authentication: Change your authentication type to Auto or OAuth 2.0 in the server configuration and go through the OAuth authorization flow.
  • Use the OAuth Debugger to troubleshoot any issues with the OAuth process.
The OAuth Debugger helps you step through each part of the authorization process and identify where things might be going wrong.

​
OAuth connection failures

When an OAuth flow fails, Inspector surfaces the failure directly in the connection UI so you can diagnose the problem without leaving the Servers tab. Connection card — a banner above the error message identifies the exact OAuth step that failed (for example, “OAuth failed during Token Request”). Server detail panel — open the server’s detail view to see the full Last OAuth Trace, which includes:
  • Each OAuth step with its status (pending / success / error) and a short message
  • The specific error for any failed step
  • An HTTP History log of every request and response made during the flow, with sensitive values automatically redacted
Use the trace to pinpoint whether the failure occurred during discovery, client registration, PKCE generation, the authorization redirect, or the token exchange, then cross-reference with the OAuth Debugger for a guided walkthrough of the same steps.

​
Toggle shows a re-authentication error for an OAuth server

The enable/connect toggle on a server card or detail modal reuses existing credentials only. If your tokens are expired or missing, the toggle will report a re-authentication error rather than opening the OAuth consent screen. Solution: Use the Reconnect button on the server card or detail modal to start a full OAuth flow and obtain new credentials. The toggle is intentionally non-interactive for OAuth to avoid unexpected browser redirects.

​
Common Configuration Mistakes

  • Missing required environment variables
  • Incorrect transport type selection
  • Typos in server URLs or commands
  • Missing file permissions or executable flags

​
Chat Model Limit

​
”MCPJam model limit reached” warning

MCPJam provides free frontier models for chat. When you hit the daily usage limit, the chat surface shows a warning:
MCPJam model limit reached. Add your own API key under LLM Providers in Settings to continue now, or try again in N minutes.
This is an expected quota state, not an error with your MCP server. To continue immediately:
  1. Go to Settings → LLM Providers
  2. Add an API key for any supported provider (OpenAI, Anthropic, Gemini, etc.)
  3. Select that provider’s model in the chat model picker
To wait for the limit to reset: The warning includes the retry window. Free quota resets daily.

​
Desktop app startup failures

​
App bounces in the dock and disappears (macOS) or closes immediately

If the desktop app fails to start, it now shows a recovery dialog instead of quitting silently. The dialog offers three options:
  • Reset app data and quit — removes cached data (Cache, Code Cache, GPUCache, Local Storage) from the app’s user data folder and relaunches. Use this when the app crashes consistently after an update or when local data appears corrupted.
  • Open logs folder — opens the folder containing electron-log output, then quits. Use this to inspect the error before deciding whether to reset.
  • Quit — exits without making any changes.

​
Port 6274 is already in use

The desktop app defaults to port 6274. If another process holds that port, the app automatically tries the next available port up to port 6283. A warning is written to the app logs when a fallback port is used. No action is required — the app starts normally on the fallback port. If you need to free port 6274 manually, find and stop the process occupying it:

​
App crashes after an automatic update

The desktop app automatically clears stale GPU and HTTP caches (Cache, Code Cache, GPUCache) the first time it launches after a version change. This handles most renderer or GPU process crashes caused by cached data from a previous build. If the app still fails to start after an update, use the Reset app data and quit option in the recovery dialog.

​
Update button does nothing after a download completes

If you click Update and nothing happens — or the app refuses to quit after a download finishes — this was a known bug fixed in 3.8.1. The app was continuing to check for updates even after a build was already staged, which caused the system to forget the staged build. After that, both the Update button and quitting were silently refused. The fix is included in 3.8.1 and later. If you are on an affected version:
  • Quitting: quit normally (Cmd+Q / Alt+F4). The app now always completes the quit even if the install fails.
  • Update button stuck: click Update once. If the staged build has gone missing, the app relaunches automatically, re-downloads the update, and installs it without a second click.
  • If neither works: use the Reset app data and quit option in the recovery dialog, or download the latest release manually from the releases page.

​
Getting Help

If you’re still experiencing issues:
  1. Check server documentation
    • Review the MCP server’s specific documentation
    • Look for known issues or troubleshooting guides
  2. Community support