Getting Ghost MCP Working with Open WebUI: A Practical Troubleshooting Guide

Introduction

Deploying a custom Model Context Protocol (MCP) tool to work with an Open WebUI instance can be straightforward — until subtle networking, runtime, or model-configuration issues surface. This post walks through the pragmatic, step-by-step fixes that took a failing deployment into a stable, usable Ghost MCP service. The emphasis is on reproducible troubleshooting patterns and practical checks rather than on any single environment’s identifiers.

1) Docker networking & compose setup

Problem
The first class of failure comes from network isolation: the MCP service and the Open WebUI instance must share a Docker network so the UI can reach the tool by its internal service name. When services run on different networks, DNS lookups fail and connections cannot be established.

Key actions and guidance

• Discover the running UI container and inspect its network membership to identify the correct internal network to join. Use container inspection tools to verify which network the UI actually uses rather than assuming a default.
• Create a docker-compose definition for the MCP service that explicitly joins the same existing network. In compose, declare that network as external so Docker will attach the new service to the already-running network rather than creating a new isolated one.
• Bring up the service, then validate connectivity from the UI host to the MCP service name (e.g., attempt a simple internal request or check container logs). If DNS resolution is failing, the most common cause is an incorrect network reference in your compose file.

Practical checks

• Verify network names via container inspection before editing compose.
• Use compose’s external network declaration to avoid creating duplicate networks.
• After deployment, confirm the MCP container can stabilize (not crash immediately) and that the UI can resolve and reach the service by its declared hostname.

2) Fixing container crashes & ensuring a persistent MCP process

Problem
A common reason for repeated failures is the service process exiting immediately after startup. Docker may repeatedly restart such containers, leading to persistent “restarting” loops and unreliable behavior.

Key actions and guidance

• Clean up prior failed attempts before redeploying to avoid stale containers and volumes affecting the next run.
• Ensure that any installation steps (for example, installing the MCP package) and the actual service process both run as part of the container’s start command so the container stays up. If an install step completes and then exits without launching the service, Docker will stop the container.
• Make the start command resilient: combine installation and process execution in a way that results in a long-running foreground process.

Practical tips

• Use a shell-based command that performs install steps if needed and then launches the MCP server in the foreground so the container remains alive.
• If the container still exits, inspect logs to determine whether the process is failing due to a missing runtime, permission issues, or environment variables.
• If leveraging a globally installed binary, ensure the binary is invoked correctly within the container environment. If the shell environment does not include the binary’s location in PATH, invoking the installed binary in a way that guarantees the runtime will be found is necessary.

3) Integration with Open WebUI: registration, enabling, and model configuration

Problem
Even with a stable MCP container and open network connectivity, the tool may not appear in the chat interface until it is enabled for the specific model and registered properly.

Key actions and guidance

• Register the MCP service in the Open WebUI admin tools section using the internal service hostname you defined in compose (use the service name, not external URLs).
• After registration, open the model configuration panel for the custom model you plan to use and explicitly enable the newly registered tool for that model. Many UI systems require this explicit association before the tool becomes available in the chat UI.
• Reevaluate model choice: some large models are expensive or have inconsistent tool-calling behavior. For cost-sensitive or high-reliability tool-calling tasks, choose a model that balances reliability, latency, and cost.

Practical tips

• If a tool is registered but not appearing, check: tool registration status, model-to-tool bindings, and any model-level tool permission toggles.
• Test the model and tool interaction with a small, low-cost model first to confirm the call flow, then scale up to more capable or expensive models if needed.
• Add a system-level prompt instructing the model to follow a verification-and-publish protocol: the model should prepare content and explicitly ask for human approval before any publishing action is initiated. This reduces the risk of unintended posts.

Wrap-up checklist

• Confirm both containers are on the same Docker network.
• Ensure the MCP container runs a long-lived server process (not an install-only command).
• Register the tool in the UI and explicitly enable it for the chosen model.
• Use a model that offers robust tool-calling at an acceptable cost.
• Add a system prompt / workflow that requires explicit human approval before publishing actions.