Troubleshooting MCP Server Errors

Diagnose and resolve common MCP Server errors using MCP metrics and pipeline execution logs.

SnapLogic provides two sources of diagnostic information for MCP Servers:

  • MCP Metrics: View request-level details including authentication type, MCP method, tool invocations, latency, and error rates.
  • Pipeline Execution logs: From the MCP Metrics detail view, click the link to the associated pipeline execution to review:
    • Execution status (Completed, Failed, Running)
    • Total execution duration and Snaplex used
    • Snap-level statistics (execution time, documents in/out, errors)
    • Execution logs with error details and stack traces

Common Issues

Issue Indicator Action
Authentication failures 401/403 errors in MCP Metrics Verify client credentials and policy configuration
Timeout errors Request timeout or Pipeline timeout Increase timeout settings or optimize Pipeline
High latency Response time > expected threshold Review Pipeline performance, consider Ultra mode
Tool not found -32601 Method Not Found errors Verify tool name in request matches Pipeline definition
Invalid parameters -32602 Invalid Params errors Check parameter types and required fields
Pipeline failures Failed Pipeline executions Review execution logs for error details

Snaplex compatibility warning

The Snaplex selection step shows a non-blocking compatibility warning when the selected nodes don't support the latest MCP specification, for example:

Your current Snaplex version does not support the latest MCP specification. Fallback version X will be used. Upgrade your Snaplex nodes to 4.45.2 or later to use the latest MCP specification.

Important: The fallback version named in this warning depends on which protocol revisions your installed nodes support — it is not always the same version. Treat the warning as informational: the server still serves requests using whichever revision your nodes support, it just isn't the newest one. This warning does not mean MCP Server is unsupported on your nodes, only that modern-protocol features aren't available until you upgrade.

During a mixed-node rolling upgrade, a modern request can succeed or fail depending on which node handles it. Upgrade all serving nodes, not just the control plane, before relying on modern-protocol behavior being consistently available.

Protocol errors

These errors come from the MCP protocol layer itself, rather than from pipeline or tool execution. See MCP protocol compatibility for background on dual-era protocol support.

Condition Response Action
A mirrored protocol, method, or tool-name header disagrees with the request body HTTP 400; -32020 HeaderMismatch Compare the MCP-Protocol-Version, Mcp-Method, and Mcp-Name headers against their body values.
A required client capability is unavailable -32021 MissingRequiredClientCapability Inspect which capability the request requires and confirm your client supports it.
Client requests an unsupported modern protocol version HTTP 400; -32022 UnsupportedProtocolVersion, with supported and requested version data Select a protocol revision both the client and server support. This is not a generic server failure.
Required modern _meta fields are missing HTTP 400; -32602 Supply protocol version and client capabilities in _meta.
Unknown method from a modern client HTTP 404; -32601 MethodNotFound Correct the method name or check the server's supported capabilities.
Unknown method from a legacy client HTTP 200 with -32601 in the body This matches legacy status-code behavior and is expected for older clients.
Runtime tool-pipeline failure A tool result containing isError: true, instead of -32603 Inspect the tool result content and correct inputs where applicable.
Request from an untrusted browser origin HTTP 403 Add the origin to MCP_ALLOWED_ORIGINS if it should be trusted.
GET, DELETE, or PATCH sent to the MCP endpoint HTTP 405 Use the supported POST-based interaction instead.
An older JCC receives a modern protocol request it doesn't support A plain-text HTTP 400, for example Unsupported MCP protocol version: 2026-07-28 Upgrade the serving nodes, or use a client capable of legacy fallback.
Note: -32002 is deprecated for MCP Server errors. New audit categories (origin_not_allowed, header_mismatch, unsupported_protocol_version, method_not_found) replace cases that were previously grouped under a generic internal error.

Token Exchange Rule Issues

Issue Indicator Action
Token exchange request fails 4xx error from STS; tool call returns an error Verify the Token Endpoint URL, Client ID, and Client Secret. Confirm that the configured client is permitted to authenticate at the token endpoint for your IdP (see IdP considerations).
STS rejects the subject token Token exchange fails with a token validation error Set Subject Token Type to ACCESS_TOKEN. Use this value even if the inbound token is JWT-encoded — the type describes the token's role, not its wire format.
Delegation actor token not fetched automatically Exchange fails in Delegation mode; Actor Token field is blank Provide a static actor token (such as a machine-user PAT) in the Actor Token field. The automatic client_credentials fetch only works if the configured client has that grant. See MCP Token Exchange rule — Limitations.
Downstream pipeline receives double Bearer prefix Downstream authentication fails; the injected header value has a duplicated scheme prefix Clear the Target Header Prefix field if the downstream pipeline constructs the Authorization header itself, or set it to match exactly what the downstream expects.