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.
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. |
-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. |