Fix Claude.ai MCP Connector Timeouts Caused by Server Cold Starts

Introduction

You add your MCP server to claude.ai as a custom connector, it answers “Couldn’t connect to the server,” and then the same server passes a manual health check in under a second. Nothing is misconfigured. Your server was simply asleep, and claude.ai stopped waiting before it woke up.

Quick answer

Keep at least one replica always running, because claude.ai gives an existing connector only about 10 seconds to answer, and about 4.5 seconds while it is being added, while a scale-to-zero cold start can take 20 seconds or more.

What broke, and why

The failure mode is specific to servers on scale-to-zero platforms such as Azure Container Apps, Cloud Run, or Fly Machines. After a quiet stretch, the platform stops all replicas. The next request must schedule a replica, pull the image, start the container, and only then run your code. One measured case on Azure Container Apps took at least 23 seconds from scheduling to a running container, and pulling the image was only 2.84 seconds of that. Almost all of the wait happened before the author’s code ran at all.

That 23 seconds collides with claude.ai’s short handshake budgets. Anthropic’s connector authentication documentation states that Claude gives OAuth discovery, registration, and token endpoints 10 seconds to respond, and refresh requests 30 seconds. Independent measurements of the web client found even tighter limits for the handshake itself: adding a new connector gave up after 4.5 seconds, and pressing Connect on an existing connector gave up after 9.97 seconds, as documented in this measured account of claude.ai’s MCP timeouts. Tool calls get a documented 240 seconds each, so the handshake is the short clock, and a cold start blows past it.

The confusing part is that the failure looks intermittent. Connecting again once the replica is up works, so the second attempt succeeds and the first looks like a fluke. It is not a fluke. It is the first request after idle paying the cold-start tax, and every later request riding on the warm replica.

The fix

Set a minimum of one replica so the platform never scales to zero. On Azure Container Apps, that is one command:

az containerapp update --name <app-name> --resource-group <resource-group> --min-replicas 1

Other hosts have an equivalent minimum-instances setting. This is the fix the measured case used, following Microsoft’s troubleshooting guidance for MCP servers on Container Apps, which describes the same 10 to 30 second first-request delay after inactivity.

The second half of the fix is about state. If your server issues its own OAuth tokens, sign them statelessly, for example as JSON signed with HMAC-SHA256, so a fresh replica accepts tokens an older replica issued. A server that keeps session state in memory cannot survive a replica replacement, and a cold start then becomes a broken login instead of a slow one.

If you would rather keep scale-to-zero, the bar is strict: answer well under 10 seconds for an existing connector, and under 5 seconds while someone is adding it. Measure your own cold start from replica scheduling to first response, not just from container start.

Pitfalls that make the fix look like it failed

First, changing the setting does not warm a replica instantly. The platform still needs to schedule and start one, so test after the new replica reports healthy, not immediately after running the command.

Second, a warm replica does not fix a slow handshake from other causes. If a slow dependency or blocking startup task delays your first response, claude.ai still gives up at the same 10 second mark. Check your logs for the gap between request arrival and first response before blaming the platform.

Third, do not confuse this with an OAuth failure. A server that returns 401 without proper discovery metadata fails with an authorization error, not a timeout. If the error mentions sign-in rather than connection, the problem is authentication, not your replica count. Our guide to connecting an MCP server to Claude Desktop covers the client side of that setup, and the Claude Code MCP setup guide covers the command-line client, which has its own startup timeout controls.

How to verify the fix worked

Let the server sit idle past your platform’s scale-to-zero delay, then reconnect the connector on claude.ai. A warm replica answers in well under a second, so the connector should connect on the first attempt with tools listed. If it still fails, check your replica count: zero before the attempt and one after means the setting did not take effect.

When this article does not apply

This fix is only for servers you host yourself on a scale-to-zero platform. With a vendor-hosted MCP server, you cannot set its replica count, and the timeout is the vendor’s problem. It also does not apply to Claude Code’s local stdio servers, where the timeout is controlled by the MCP_TIMEOUT environment variable on your own machine. And if your connector fails even when the server is provably warm, look next at DNS, firewall rules, redirects, and OAuth discovery.

Conclusion

A claude.ai connector timeout after idle is usually not a bug in your server. It is a scale-to-zero cold start running into a 10 second handshake budget. One warm replica removes the race, and stateless token signing makes the warm replica replaceable. For background, see our MCP server tutorial.

Frequently asked questions