Troubleshoot MCP Connections

Overview

This document covers the most common failure states when connecting to the Syncro MCP server: authentication errors, tools not appearing in your client, rate limit responses, connection timeouts, invalid input, and record-not-found errors. Each entry describes the symptom, the likely cause, and steps to resolve it.

Know that errors come in two forms. 

1. Transport-level errors fail the request itself and appear as a non-200 HTTP status in your client's error log (for example, 401 or 400). 
2. Tool-level errors are returned inside a successful HTTP 200 response, in an error envelope: { content: [...], isError: true, _meta: { category, retryable, retryAfter } }. The _meta.category field identifies the failure type (permission-denied, invalid-input, record-not-found, rate-limit, or server-error), and _meta.retryable tells you whether retrying is safe. If you filter your logs for 4xx status codes only, tool-level errors won't show up there; check the response envelope instead.

Authentication errors

Symptom

• Transport-level: Your MCP client receives an error immediately, before any tool runs. You see HTTP 401 (invalid or expired OAuth token) or HTTP 400 (missing or malformed subdomain) in your client's error log.
• Tool-level: A specific tool call returns HTTP 200 with _meta.category="permission-denied". The connection itself is fine. The OAuth-authorizing user doesn't have permission to perform that action in Syncro.

For automation builders: the workflow node returns an error and no data. The workflow does not retry automatically.

Cause

• Expired or revoked OAuth token. Tokens are rejected on every request, with no grace period. Returns HTTP 401.
• Missing or malformed subdomain. The X-Syncro-Subdomain header is absent or not a single DNS label (e.g., acme, not acme.syncromsp.com). Returns HTTP 400.
• Insufficient Syncro permissions. A call to a write-oriented tool (e.g., creating a ticket) fails with permission-denied based on what the Syncro user who authorized the OAuth connection is permitted to do in Syncro. Returns HTTP 200 with _meta.category="permission-denied".

Resolution

• Confirm your OAuth token hasn't expired or been revoked. Reauthorize the connection if needed.
• Confirm the X-Syncro-Subdomain header is present and is a single label. Verify it from your account URL. If your account is acme.syncromsp.com, the subdomain is acme.
• If permission-denied appears on a specific tool, check what the OAuth-authorizing user is permitted to do in Syncro. Re-authorizing the connection with a different Syncro user who has the needed permissions resolves this. See also Security Permissions Reference.
• If HTTP 401 appears across all tools after previously working calls, your OAuth token has likely been revoked. Reauthorize the connection.

Tools not appearing in the client

Symptom

After adding the server to your client config and restarting, no Syncro tools appear. The connection appears to succeed but the tool list is empty.

For automation builders: your n8n node cannot find any Syncro MCP tool names when building the workflow.

Cause

• Wrong endpoint. The server only handles POST /mcp/stream. A GET or DELETE returns HTTP 405. The legacy /mcp/sse path is not served.
• Client not restarted. Claude Desktop loads MCP config at startup. Changes require a full quit and relaunch.
• Missing or malformed X-Syncro-Subdomain header. Returns HTTP 400 before the tool list is negotiated.

Resolution

• Use the correct hosted endpoint: https://mcp.services.syncromsp.com/mcp/stream.
• Confirm your client config points to that endpoint and includes your OAuth credentials and the X-Syncro-Subdomain header.
• Fully quit and relaunch your client after any config change.
• Cursor and other MCP clients use the same endpoint and header requirements.

Rate limit errors

Symptom

Tool calls succeed initially, then return an error with _meta.category="rate-limit". In high-frequency automation workflows, this appears as bursts of failures during peak activity.

Cause

The Syncro API enforces an upstream limit of 180 requests per minute. The MCP server does not add its own rate limit. When the upstream limit is hit, the Syncro API returns HTTP 429, and the MCP server surfaces this as a rate-limit error, passing through the upstream Retry-After value. The MCP server never generates rate-limit errors on its own. Every one reflects a 429 from the Syncro API upstream.

Resolution

• Read _meta.retryAfter from the response envelope ({ content: [...], isError: true, _meta: { category: "rate-limit", retryAfter: <seconds> } }). The same value is also in the HTTP Retry-After header. Wait that many seconds before retrying.
• Use _meta.retryable as the authoritative signal for whether to retry at all, rather than branching on category.
• If multiple workflows run against the same account simultaneously, their requests count toward the same limit. Coordinate timing or add deliberate delays between batch executions.
• For automation builders: build retry logic around _meta.retryable and _meta.retryAfter, not the category string. In n8n, read _meta.retryAfter in an error branch and feed it into a Wait node before looping back into the tool call.

Connection timeouts

Symptom

A tool call does not return within the expected window, then resolves with an error. There is no distinct timeout code in the response. It's indistinguishable from an upstream crash.

Cause

The MCP server applies a per-tool-call deadline (default 20 seconds). When the upstream Syncro API doesn't respond in time, the call is terminated.

The MCP server can't distinguish a timeout from an upstream crash; both look the same from the response. For read-only tools, both map to _meta.category="server-error" with HTTP 502, and _meta.retryable=true. For mutating tools (create/update), a timeout instead returns HTTP 200 with _meta.retryable=false, because the upstream write may have already succeeded and blindly retrying risks creating a duplicate record.

Resolution

• Do not auto-retry a timed-out create or update call. The record may already exist so verify it first (e.g., look it up by the identifier or name you expected to create) before retrying or resubmitting.
• Scope "retry with exponential backoff" to read-only tools only: start at 2-5 seconds and double the wait on each subsequent failure.
• Branch retry logic on _meta.retryable, not on _meta.category.
• Check the Syncro platform status page for an active upstream incident. If the API is degraded, retries won't succeed until the upstream issue resolves.
• Don't treat a read-only server-error as permanent unless it persists across multiple retry attempts.

Invalid Input

Symptom

A tool call returns immediately with an error; no retry or backoff resolves it on its own.

Cause

The arguments passed to the tool are missing a required field, have the wrong type, or fail validation. This maps to an upstream HTTP 400/422, surfaced as HTTP 200 with _meta.category="invalid-input" and _meta.retryable=false.

Resolution

Fix the arguments and resubmit. This is not a transient failure. Retrying with backoff will not help until the input itself is corrected. Check the tool's required parameters and types before calling it again.

Record Not Found

Symptom

A tool call returns an error when looking up a specific record. For example, a ticket, customer Organization, or asset ID that doesn't exist.

Cause

The requested ID doesn't exist in Syncro (deleted, or mistyped). This maps to an upstream HTTP 404, surfaced as HTTP 200 with _meta.category="record-not-found" and _meta.retryable=false.

Resolution

Confirm the ID or identifier is correct and that the record still exists in Syncro. This is not a transient or connection issue. Don't retry with backoff; look up the correct identifier instead.