Error code reference

This page is the source of truth for the error messages MCPJam Inspector surfaces. Every error rendered in the inspector deep-links to one of the sections below. If you arrived here from an ErrorCard’s “Learn more” link, the page should already be scrolled to the right section. Otherwise, use the index below.

​

JSON-RPC codes

These come from the MCP transport itself. Numeric codes are defined by the JSON-RPC 2.0 spec plus a handful of MCP-specific extensions.

​

Parse error

-32700 — jsonrpc/parse_error The MCP wire contained JSON the inspector could not parse as JSON-RPC. Likely causes

• The server emitted invalid JSON on the response channel.
• A proxy or middleware mangled the response body.
• Server emitted log output on stdout instead of stderr (STDIO transport).
• The inspector sent malformed JSON and the server returned a parse error.

Next steps

• Check the server’s stdout/stderr for unintended log output.
• Use the inspector’s Traffic Log to inspect the raw response.

​

Invalid request

-32600 — jsonrpc/invalid_request The server rejected the payload as not a well-formed JSON-RPC request. Likely causes

• Client sent a request shape the server’s MCP runtime does not accept.
• Outdated server SDK that disagrees with the protocol version advertised.

Next steps

• Verify the negotiated MCP protocol version.
• Update the server’s MCP SDK.

​

Method not found

-32601 — jsonrpc/method_not_found The server does not implement the JSON-RPC method that was called. Likely causes

• The server hasn’t implemented the requested MCP method.
• Client and server are on incompatible MCP protocol versions.
• The capability you expected was not advertised in initialize.

Next steps

• Check the server’s advertised capabilities in the connection info modal.
• Confirm the protocol version negotiated at initialize.

​

Invalid params

-32602 — jsonrpc/invalid_params The server rejected the request parameters. Likely causes

• Required field is missing from the call.
• Field type does not match the tool’s input schema.
• Server-side validator is stricter than the published schema.

Next steps

• Re-check the tool’s input schema in the Tools tab.
• Compare your call payload against the schema in the inspector.

​

Internal error

-32603 — jsonrpc/internal_error The server hit an unexpected error while handling the request. Likely causes

• Unhandled exception inside the server’s tool/resource/prompt handler.
• Downstream dependency (database, API) failed during the call.

Next steps

• Check the server’s logs around the time of the error.
• Retry the request once the server is healthy.

​

Connection closed

-32000 — jsonrpc/connection_closed The underlying transport closed before the response could be delivered. Likely causes

• STDIO server process exited or crashed mid-request.
• HTTP server dropped the streaming connection.
• Network blip between the inspector and the server.

Next steps

• Restart the server and reconnect.
• Check the server logs for a crash or exit message.

Inspector-specific: the inspector synthesizes this code when an active transport goes away mid-request. If you see it on every call, the server is probably exiting immediately after startup — check for a fatal log.

​

Request timeout

-32001 — jsonrpc/request_timeout The server did not respond within the configured request timeout. Likely causes

• Server is overloaded or stuck on the operation.
• Long-running tool call exceeds the inspector’s per-request timeout.
• Network latency between client and server.

Next steps

• Increase the per-server request timeout in the Servers tab.
• Use MCP tasks/* for operations that legitimately run long.

​

Header mismatch

-32001 — jsonrpc/header_mismatch The server rejected the request because an HTTP header disagreed with the JSON-RPC body — for example, Mcp-Protocol-Version does not match the version negotiated at initialize, or Mcp-Name does not match the tool name in the request body. Likely causes

• Server is enforcing a different protocol version than the one negotiated at initialize.
• A proxy stripped or rewrote an Mcp-* header.
• A routing header (Mcp-Name, Mcp-Method) was set to a value that disagrees with the request body.

Next steps

• Expand the failing JSON-RPC frame in the traffic log. The collapsed HTTP headers row beneath the JSON body names the disagreeing header (for example, mcp-name disagrees with the body) without requiring you to open a separate view.
• If the inline headers section is absent, open the HTTP source filter in the traffic log to find the matching exchange and inspect its headers directly.
• Verify the server’s protocol-version pinning in the connection settings.
• If you set an explicit protocol version per server, ensure it matches what the server advertises.

The -32001 code is overloaded between request_timeout and header_mismatch. The inspector disambiguates by message; check the raw message in the ErrorCard’s details panel.

​

Unsupported protocol version

-32004 — jsonrpc/unsupported_protocol_version The server does not support any protocol version this inspector offered. Likely causes

• Server pinned to a newer MCP draft your inspector build does not understand.
• Server pinned to a legacy version this build dropped support for.

Next steps

• Update the inspector to a newer build.
• Check the supported versions list in the server’s initialize response.

​

URL elicitation required

-32042 — jsonrpc/url_elicitation_required The server needs the user to visit an external URL to complete the operation. Likely causes

• Server requested a URL elicitation (OAuth, payment, confirmation).
• Operation cannot proceed until the user opens the URL in a browser.

Next steps

• Open the elicited URL and complete the flow.
• Re-issue the request after the external step completes.

---

​

Transport errors

These come from the OS or the HTTP stack. Most of them are recoverable.

​

ECONNREFUSED

transport/econnrefused Nothing is listening on the host and port the server URL points at. Likely causes

• Server isn’t running.
• Port number is wrong in the server URL.
• Server is bound to a different interface (e.g. only 127.0.0.1 but you’re connecting via the LAN IP).

Next steps

• Start the server.
• Double-check the URL’s host and port.
• For Docker/containers, confirm the port is published to your host.

​

ECONNRESET

transport/econnreset The remote side closed the TCP connection abruptly. Likely causes

• Server process crashed mid-request.
• Intermediate proxy or load balancer dropped the connection.
• Server hit an OS-level resource limit.

Next steps

• Inspect the server logs for a crash.
• Retry the request.

​

ETIMEDOUT

transport/etimedout The OS-level TCP connection attempt did not complete in time. Likely causes

• Wrong host/port in the server URL.
• Firewall is silently dropping packets.
• Server is overloaded and never accepted the connection.

Next steps

• Verify the URL is reachable from your machine (e.g. curl).
• Check firewall / VPN rules.

​

ENOTFOUND

transport/enotfound DNS lookup failed for the server’s hostname. Likely causes

• Hostname is misspelled in the URL.
• DNS resolver is misconfigured.
• You’re offline.

Next steps

• Confirm the hostname in the URL is correct.
• Try resolving the host with nslookup or dig.

​

EAI again

transport/eai_again DNS resolution failed with a transient error. Likely causes

• Local DNS resolver is overloaded or restarting.
• Upstream DNS server is briefly unavailable.

Next steps

• Wait a few seconds and retry.
• Switch to a different DNS resolver if this persists.

​

Undici transport error

transport/undici The underlying HTTP client (undici / fetch) reported a low-level transport failure. Common subcodes: UND_ERR_SOCKET, UND_ERR_CONNECT_TIMEOUT, UND_ERR_HEADERS_TIMEOUT. Likely causes

• Server closed the connection mid-response.
• TLS handshake failed.
• Socket-level error during streaming.

Next steps

• Inspect the Traffic Log for the failed request.
• Verify the server’s TLS certificate is valid.

​

Fetch failed

transport/fetch_failed The HTTP request never produced a response. Likely causes

• Server is unreachable (offline, wrong URL, blocked by firewall).
• TLS handshake failed (self-signed cert, expired cert).
• Mixed-content block (HTTPS page calling HTTP endpoint in browser).

Next steps

• Open the URL in a browser to confirm it loads.
• If self-signed, install the certificate or switch to a trusted one.

​

Socket hang up

transport/socket_hang_up The server closed the connection without sending a response. Likely causes

• Server crashed or restarted during the request.
• Reverse proxy timed the request out.

Next steps

• Retry the request.
• Check server-side logs for the crash.

---

​

Auth & OAuth

For the difference between the three “API key” concepts (LLM provider keys, MCPJam API keys, Playground BYOK), see API keys.

​

Unauthorized 401

auth/http_401 The server requires authentication that wasn’t provided or is no longer valid. Likely causes

• Missing or expired bearer token.
• OAuth access token expired and refresh failed.
• Server changed its required authentication scheme.

Next steps

• Re-authenticate using the Reconnect button on the server card.
• If using OAuth, run through the OAuth flow again from Servers.

​

Forbidden 403

auth/http_403 You authenticated successfully but lack permission for the operation. Likely causes

• OAuth scopes granted don’t cover the requested operation.
• Server-side ACL blocks this account.

Next steps

• Re-run OAuth and request the additional scopes if the server allows.
• Ask the server admin to grant the necessary permissions.

​

OAuth refresh failed

auth/oauth_refresh_failed An expired OAuth access token could not be refreshed. Likely causes

• Refresh token was revoked.
• Refresh token expired.
• Server returned invalid_grant to the refresh attempt.

Next steps

• Click Reconnect on the server card to run a fresh OAuth flow.

​

Missing bearer

auth/missing_bearer The API call did not include the required Authorization: Bearer ... header. Likely causes

• Inspector session expired.
• Sign-in token failed to attach to the request.

Next steps

• Refresh the page and sign in again.

​

OAuth invalid grant

oauth/invalid_grant The OAuth server rejected the authorization code or refresh token. Likely causes

• Authorization code was already redeemed.
• Refresh token was revoked.
• Authorization code expired (typical lifetime ~60s).

Next steps

• Start the OAuth flow again from the server card.

​

OAuth invalid client

oauth/invalid_client The OAuth server does not recognize the client credentials. Likely causes

• Client was deleted on the authorization server.
• Dynamic registration cache is stale.
• client_id was rotated server-side.

Next steps

• Re-register the client (Reconnect from the server card triggers DCR if supported).

​

OAuth redirect mismatch

oauth/redirect_mismatch The redirect URI in the request does not match the one registered with the OAuth server. Likely causes

• Authorization server requires the inspector’s callback URL to be registered explicitly.
• Server’s allow-list is wrong.

Next steps

• Add the inspector’s callback URL to the OAuth server’s allowed redirects.
• Verify the inspector’s base URL hasn’t changed.

​

OAuth well-known unreachable

oauth/well_known_unreachable The OAuth .well-known discovery endpoint could not be fetched. Likely causes

• Authorization server is down.
• Wrong issuer URL.
• CORS blocks the discovery request from the browser.

Next steps

• Confirm the issuer URL in the server config.
• Open the .well-known/openid-configuration (or oauth-authorization-server) URL in a browser.

---

​

Inspector-specific

These come from the inspector’s own SDK runtime.

​

Not yet supported in stateless

sdk/not_yet_supported_in_stateless The inspector’s stateless HTTP transport does not yet implement this MCP operation. Likely causes

• Operation requires a server-initiated channel (subscriptions, MRTR) the stateless preview transport hasn’t wired up yet.

Next steps

• Switch the server to the legacy stateful transport in its protocol-mode toggle.

​

Stateless requires HTTP

sdk/stateless_requires_http Stateless mode can only be used with an HTTP-transport server, not STDIO. Likely causes

• You enabled the stateless protocol toggle on a stdio server.

Next steps

• Disable the stateless toggle for stdio servers.

​

Protocol version pin unsupported

sdk/protocol_version_pin_unsupported This connection is pinned to a specific MCP protocol version that the server does not offer. Likely causes

• The client profile you’re using pins a protocol version this server hasn’t adopted — for example, a client set to Latest (2026-07-28) against a server that still speaks a 2025 revision.
• A per-server protocol override is pinned to a version the server dropped or never shipped.

Next steps

• Click Change protocol version in the error banner or toast to open the client’s MCP Protocol tab, then set the version to Automatic to negotiate whatever the server supports.
• Or pick the version the server advertises — server/discover (modern) or the initialize response (legacy) lists the supported versions.

​

Paginated tool / header discovery unsupported

sdk/paginated_tool_header_discovery_unsupported Paginated tools discovery cannot run alongside per-request header overrides on this transport. Likely causes

• Conflicting combination of progressive tool discovery + per-server header overrides.

Next steps

• Disable progressive tool discovery for this server, or move headers into the server config.

---

​

Provider errors

Errors from the LLM provider running behind the playground.

​

Provider invalid tool name

provider/invalid_tool_name An LLM provider rejected a tool name (Anthropic’s strict tool-name validator is the most common source). Likely causes

• Tool name contains characters or length the provider does not allow.
• Two attached servers expose tools whose namespaced names collide after sanitization.

Next steps

• Rename the offending tool on the server.
• Detach one of the colliding servers from the chat surface.

​

Provider auth error

provider/auth_error Your LLM provider rejected the API key for this request. Likely causes

• Key is missing.
• Key is invalid or revoked.
• Key is for a different environment (project, region).

Next steps

• Add or update your API key under Settings → LLM Providers.
• Verify the key in the provider’s dashboard.

​

Provider quota

provider/quota Your LLM provider rejected the request because you hit a rate limit or quota. This is a limit on your own provider key — no MCPJam purchase lifts it. Likely causes

• Per-minute rate limit exceeded.
• Daily or monthly quota exhausted.
• Free tier limits hit.

Next steps

• Wait for the limit window to reset, then retry.
• Switch the host to a different model or provider.
• Upgrade your plan on the provider’s own dashboard.

MCPJam account limit vs. provider throttle — If the session pane shows a billing or credit message instead of this card, the limit is on your MCPJam account, not your provider key. Adding credits or switching to BYOK resolves that case; the steps above do not apply.

​

MCPJam model limit reached

provider/mcpjam_limit_daily · provider/mcpjam_limit_monthly · provider/mcpjam_limit MCPJam refused the call before it reached a provider, because the account’s own allowance is spent. Which allowance depends on the plan: free accounts share a daily bucket per organization, Team plans spend a monthly per-seat allowance that renews with the billing period. The error card names the one you hit. Next steps

• Top up credits or upgrade the plan — the limit dialog offers both.
• Wait for the daily reset, or for the billing period to renew.
• Add your own API key under Settings → LLM Providers for chat.

---

​

Environment errors

These codes come from the environment resolution service. They appear in the Playground, the Environment Tools pane, and on scenario shared links when a project environment cannot be resolved to a usable set of servers. The error card offers an action where one exists — for example, Open Servers for ENV_NO_SERVERS — rather than a generic retry that would fail identically. When a visitor opens a scenario shared link and the scenario’s environment is archived, they see “This link has been archived” instead of a generic failure message. For other unresolvable environment states they see “This link isn’t available right now”. Signing in cannot change either state — the environment itself must be restored or reconfigured by the scenario owner.

​

No servers

ENV_NO_SERVERS This environment has no servers. Likely causes

• The client this environment points at has no servers connected.
• The attached server group is empty.
• Every server contributed by a pinned plugin has been removed.

Next steps

• Connect a server to the client, or attach a server group.
• Check the environment’s pinned plugins if it relied on one for servers.

​

Archived

ENV_ARCHIVED This environment is archived. Likely causes

• Someone archived it after this was configured.

Next steps

• Restore it from the Environments list, or pick a different environment.

​

Client missing

ENV_HOST_MISSING This environment’s client no longer exists. Likely causes

• The client was deleted after the environment was created.

Next steps

• Point the environment at a different client, or recreate it.

​

Server group missing

ENV_ATTACHMENT_MISSING This environment’s server group is gone. Likely causes

• The attached server group was deleted.

Next steps

• Attach a different server group, or clear the attachment.

---

​

Unknown error

internal/unknown An error occurred that the inspector could not classify. Likely causes

• Unhandled error path.
• New error class the inspector hasn’t been taught about yet.

Next steps

• Open the details panel of the ErrorCard and copy the raw message.
• File an issue with the raw message so we can add it to the catalog.