Diagnosing Connection Issues with MCP.

Your container is running, but nothing loads when you visit it.

This gjuide walks through asking the LLM (for this guide I'll use Claude and refer to the LLM as Claude) to find the cause through the Cycle MCP server, using a common cause as the example: no domain points at the container.

The concept

Traffic from the internet reaches a container in three steps.

1. A domain resolves in DNS to your environment's load balancer.
2. The load balancer matches that domain to a LINKED record.
3. The LINKED record tells it which container to send the request to.

If any step is missing, the request never arrives, even when the container itself is healthy.

When you ask Claude something like:

"Why is the web container in environment acme-web not resolving when I try to visit it in the browser or curl it"

it runs the diagnose tool with the unreachable focus. That check tests each step separately, so a pass at one step can't hide a failure at another:

1. Ingress config. Does a LINKED record point at the container, and are the container's public network and port settings correct?
2. DNS. Does each linked domain resolve, both on its zone's own nameservers and on public resolvers?
3. A live request. Does an HTTP request to each linked domain actually get an answer from the container?

The live request is the ground truth. If it succeeds, the path is verified working, not just configured.

Implementing the Diagnosis

This example uses the web container in the acme-web environment. The connector only needs read access.

1. Ask Claude in plain language. Name the environment and the container, so Claude doesn't have to guess between containers that share a name:

   Why can't I reach the web container in the acme-web environment?

2. Claude finds the environment and runs the diagnosis. It resolves acme-web, then runs diagnose with the unreachable focus on web. In this example, nine checks ran and returned three findings:

   Severity	Finding
   Critical	No LINKED record points to container web, so no ingress traffic is permitted.
   Warning	web has an HTTPS port configured, but no domain pointing at it has TLS enabled.
   Info	Load balancer telemetry isn't available for this environment.

   Every other check passed: the container is running, its instance is healthy, and the environment services are up.
3. Claude confirms the finding from the DNS side. Before concluding, Claude reads the records in each of your hub's DNS zones to check whether any record targets web. None does. This rules out a record that exists but points at the wrong container, or one created without a target.
4. Claude reports the cause and the fix. The container is fine. There's simply no domain for it, so the load balancer has nowhere to route requests from.
5. Add the LINKED record. In the portal, open the example.com zone and add a LINKED record for acme.example.com that targets the web container in acme-web. Turn TLS on, since web serves HTTPS. Cycle issues the certificate automatically once the domain resolves publicly.
   Choosing: target the container directly for a single service. Target a deployment tag instead if you release new versions with deployments, so the domain follows the tag.
6. Ask Claude to check again.

   Check whether acme.example.com reaches web now.

   This time all three steps can run. A successful live request means the path is verified end to end.

What just happened

Only the first of the three steps could run the first time. The DNS check and the live request both need a domain to test, and there wasn't one. The diagnosis doesn't report a step it couldn't test as passing. That's why the fix ends with a re-check: the second run is the one that proves the container is reachable.

The info finding about load balancer telemetry isn't a problem. Cycle has no telemetry for a load balancer that hasn't served traffic, which is expected when nothing points at the container yet. On its own, that finding tells you nothing either way.

The most important point is that the same finding can mean opposite things. "No LINKED record points to this container" is the whole problem here, because you expect web to be public. On a database or an internal API, the identical finding is expected and harmless, because those containers aren't meant to take traffic from the internet. Claude can't know which containers you intend to be public, so ask about one container you expect to reach instead of scanning the whole hub. A narrow question gets you a verdict, while a hub-wide scan tends to flag every internal service as unreachable.

Finally, diagnose suggests a next step with each finding. Here it suggested creating the LINKED record with manage_dns_record. With read-only access, Claude can't make that change for you, so you add the record in the portal yourself. With a write-capable connector, Claude still asks you to confirm before creating anything.

Interested in exploring how the MCP can implement the change with more permissions granted? Check out this guide on managing permissions for the MCP.