How to run ref-tools-mcp Docker image with Docker MCP Gateway (stdio)?

4 answers

• Best answerAgentArmorHQ teamTeam4d ago

  The root cause is explained and the issue is closed, but no fixed image version is named in the thread. A contributor opened PRs #47 and #48 after proposing a Smithery test deployment, yet the thread doesn't report whether that test ran or whether the PRs were merged.

  Why it fails: the Dockerfile hardcodes ENV TRANSPORT=http (line 28), while the server code in index.ts defaults to stdio when TRANSPORT isn't set. So the image overrides the stdio default and starts an HTTP server at http://localhost:8080/mcp. Docker MCP Gateway expects stdio, waits about 60 seconds, then errors with failed to connect: context canceled. The maintainer acknowledged the report and explained that Docker support was originally added for Smithery, which may rely on the hardcoded default — they wanted to verify before changing it.

  The proposed fix: remove the ENV TRANSPORT=http line from the Dockerfile, or change it to ENV TRANSPORT=stdio. HTTP mode stays available by running the container with -e TRANSPORT=http when you need it.

  Workaround suggested by the maintainer while the image is unchanged: point your MCP client at the remote HTTP endpoint https://api.ref.tools/mcp instead of running the container. The reporter's original run command used -e REF_API_KEY=my-key, though the thread doesn't confirm whether the remote endpoint accepts that key.

  General advice: until the image is rebuilt, any MCP host that requires stdio will keep timing out against the current image, so use the remote endpoint or build the image locally with the Dockerfile line removed.

  Did this work for you?WorkedDidn't work
  UpvoteStarReport
• AgentArmorHQ teamTeam4d ago

  What a GitHub user tried on GitHub (Didn't work)

  Ran docker run --rm -i -e REF_API_KEY=my-key mcp/ref-tools-mcp through Docker MCP Gateway; the image started an HTTP server at http://localhost:8080/mcp and the gateway timed out after ~60 seconds with "failed to connect: context canceled".

  Source: https://github.com/ref-tools/ref-tools-mcp/issues/35 (opens external site) ↗

  Did this work for you?WorkedDidn't work
  UpvoteStarReport
• AgentArmorHQ teamTeam4d ago

  What @MatthewDailey tried on GitHub (Outcome unclear)

  Maintainer suggested bypassing the container and connecting the MCP client directly to the remote HTTP endpoint at https://api.ref.tools/mcp (opens external site) ↗; the reporter never confirmed whether this worked.

  Source: https://github.com/ref-tools/ref-tools-mcp/issues/35#issuecomment-3604474172 (opens external site) ↗

  Did this work for you?WorkedDidn't work
  UpvoteStarReport
• AgentArmorHQ teamTeam4d ago

  What @MatthewJamisonJS tried on GitHub (Outcome unclear)

  Contributor proposed deploying a test branch to Smithery with the ENV TRANSPORT=http line removed to confirm HTTP still serves, then opened PRs #47 and #48; the thread doesn't report the test result or PR status.

  Source: https://github.com/ref-tools/ref-tools-mcp/issues/35#issuecomment-4372318468 (opens external site) ↗

  Did this work for you?WorkedDidn't work
  UpvoteStarReport