Docker image doesn't work with Docker MCP Gateway (TRANSPORT=http hardcoded)

[mikecfisher]

Hi Team

I was trying to use the Ref MCP server through Docker MCP Toolkit/Gateway (the new Docker Desktop feature for managing MCP servers), and ran into an issue where it just times out every time.

What's happening

Docker MCP Gateway expects MCP servers to communicate via stdio, but when I run the container:

docker run --rm -i -e REF_API_KEY=my-key mcp/ref-tools-mcp

I get:

Ref MCP Server running on HTTP at http://localhost:8080/mcp

It starts an HTTP server instead of listening on stdio, so the gateway waits ~60 seconds for a stdio response that never comes, then times out with failed to connect: context canceled.

The culprit

Looking at the Dockerfile, line 28 hardcodes:

ENV TRANSPORT=http

But in index.ts, the code defaults to stdio when TRANSPORT isn't set:

const TRANSPORT_TYPE = (process.env.TRANSPORT || 'stdio') as 'stdio' | 'http'

So the Dockerfile is overriding the sensible default.

Suggested fix

Either remove ENV TRANSPORT=http from the Dockerfile entirely (so it defaults to stdio), or change it to ENV TRANSPORT=stdio.

The HTTP mode can still be used by explicitly passing -e TRANSPORT=http when needed.

Context

Docker MCP Toolkit is becoming a popular way to run MCP servers - it handles pulling images, managing secrets, and connecting to clients like Cursor, Claude Desktop, etc. The Ref server is listed in the Docker MCP Catalog, but it's currently broken because of this env var.

All the other MCP servers in the catalog (GitHub, Neon, Playwright, etc.) work fine - Ref is the only one timing out.

Thanks for the awesome tool btw - just need this small tweak to make it work with Docker :)

[MatthewDailey]

Thanks for debugging that @mikecfisher !

Some background is that Docker support was originally added for Smithery and I suspect they are relying on the hardcoded TRANSPORT default but will need to test that to be sure which is why I've procrastinated this fix.

As a work around for now, are you able to use the remote http directly from https://api.ref.tools/mcp ?