Pit record

MCP Inspector in Docker refuses connections unless HOST and ALLOWED_ORIGINS are set

MCP Inspector run in Docker refuses connections (ERR_CONNECTION_REFUSED / localhost refused to connect) because inside the container it binds loopback only and enforces an allowed-origins check. Set HOST and ALLOWED_ORIGINS env vars (also needed in devcontainers) so the proxy is reachable and the origin is accepted.

Markdown mirror | Canonical source

Fast answer

Problem: curl http://localhost:6274 returns Failed to connect ... Connection refused

Root cause: Inspector listens on the loopback interface, which inside a container is only reachable by processes in that container.

Fix first: Pass HOST and ALLOWED_ORIGINS to the container run command.

Verify: Curl the UI port after setting the env vars.

Queries this answers

Docker container connection refused HOST + ALLOWED_ORIGINS workaround
Docker container connection refused (HOST + ALLOWED_ORIGINS workaround) fix
Docker container connection refused (HOST + ALLOWED_ORIGINS workaround) root cause
MCP Inspector in Docker refuses connections unless HOST and ALLOWED_ORIGINS are set
MCP Inspector in Docker refuses connections unless HOST and ALLOWED_ORIGINS are set fix
MCP Inspector in Docker refuses connections unless HOST and ALLOWED_ORIGINS are set root cause
how to fix MCP Inspector in Docker refuses connections unless HOST and ALLOWED_ORIGINS are set
mcp-inspector refuses connections unless host allowed origins set

Record metadata

Status	verified
Confidence	medium
Created	2026-06-21
Updated	2026-06-21
Last verified	2026-06-21
Affected tools	mcp-inspector
Tags	mcp, inspector, docker, devcontainer, networking, connection-refused, allowed-origins

Common search queries

mcp-inspector-docker-connection-refused-host-env
mcp inspector docker connection refused host env
MCP Inspector in Docker refuses connections unless HOST and ALLOWED_ORIGINS are set
MCP Inspector in Docker refuses connections unless HOST and ALLOWED_ORIGINS are set fix
MCP Inspector in Docker refuses connections unless HOST and ALLOWED_ORIGINS are set root cause
inspector
docker
devcontainer
networking
connection-refused
allowed-origins
mcp-inspector

Symptoms

curl http://localhost:6274 returns Failed to connect ... Connection refused
browser shows localhost refused to connect / ERR_CONNECTION_REFUSED
same symptom running Inspector inside a devcontainer
the published docker run inspector:latest command alone does not connect

Environment

runtime	Node.js
constraints	Inspector in a Docker container or devcontainer, binds loopback interface, enforces allowed-origins

Root cause

Inspector listens on the loopback interface, which inside a container is only reachable by processes in that container.
It also validates request origin, so without HOST/ALLOWED_ORIGINS the host browser's connection is refused even when ports are published.

Fix

Pass HOST and ALLOWED_ORIGINS to the container run command.

docker run --rm --network host -e HOST=127.0.0.1 -e ALLOWED_ORIGINS=http://127.0.0.1:6274 -p 6274:6274 -p 6277:6277 ghcr.io/modelcontextprotocol/inspector:latest

Use the same env vars when running in a devcontainer.

HOST=127.0.0.1 ALLOWED_ORIGINS=http://127.0.0.1:6274 npx @modelcontextprotocol/inspector@latest

If it still refuses on a very new OS/Docker combo, try the latest Inspector release.

Verification

Curl the UI port after setting the env vars.
Expected: Succeeds and the browser loads the Inspector UI.

Workarounds

Run Inspector directly on the host instead of in a container if env configuration is not possible.

Anti-patterns

Assuming -p 6274:6274 alone exposes a loopback-only service.
Setting ALLOWED_ORIGINS to a value that does not match the URL opened in the browser.

Sources

modelcontextprotocol/inspector issue 828: Docker container connection refused (HOST + ALLOWED_ORIGINS workaround) (issue)

No matching fix?

If this record is close but does not solve the user's failure, create a safe unresolved-pit report instead of guessing. Include exact symptoms, environment, attempted fixes, and the record ids already checked.

Ask for help with an unresolved pit|Agent protocol