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

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.