Agent or MCP server running in a Docker container can't reach a service on the host: 'connection refused' or 'could not resolve host.docker.internal' on Linux. How do I connect container to host correctly?

Cause: Inside a container, localhost and 127.0.0.1 mean the container itself, not your machine. Docker Desktop provides the special name host.docker.internal, which resolves to the host's internal address. Docker's CLI reference notes that Docker Desktop resolves this name automatically; on plain Docker Engine on Linux you generally have to map it yourself. Separately, a host service listening only on the loopback interface is, as a general networking matter, usually not reachable from the container's network, so it may also need to listen on an address the container can reach. Fix (best first): 1. Use host.docker.internal as the hostname in the agent or MCP client config (for example http://host.docker.internal:8000) instead of localhost. 2. On Linux Docker Engine, add the mapping when starting the container: docker run --add-host=host.docker.internal:host-gateway ... . Docker documents host-gateway as a special value that resolves to the host's internal IP. In Compose the equivalent is an extra_hosts entry with the same value. 3. If the service on the host binds only to loopback, change it to listen on the interface the container can reach, and restrict exposure with a firewall rule so it is not open to your whole network. Do not bind to every interface on an untrusted network just to make it work. 4. Alternative for Linux: host network mode (--network host) makes the container share the host's network namespace so host ports are reachable directly. Docker notes that published ports (-p) are ignored in this mode, and that on Docker Desktop host networking needs version 4.34 or later and must be switched on in settings. It removes network isolation, so use it only for trusted containers. 5. Reverse direction: to expose a container's port to the host, publish it with -p, optionally bound to 127.0.0.1 to keep it local. Verify: From inside the container, request the host service via host.docker.internal and its port (for example with curl). A response, rather than a refusal or a resolution error, confirms the path. Then check the host service is not reachable from other machines unless you intended that. Sources: https://docs.docker.com/reference/cli/docker/container/run/ https://docs.docker.com/desktop/features/networking/networking-how-tos/ https://docs.docker.com/engine/network/drivers/host/