Skip to main content
AI tutorials

Build an OpenAPI Gateway for Local MCP Services with Open MCP Gateway

Learn how to install Open MCP Gateway, configure local MCP services, generate OpenAPI-compatible routes, integrate them with Open WebUI, manage external plugins, monitor logs, and compile the gateway into a standalone native executable.

About 20 min read
Build an OpenAPI Gateway for Local MCP Services with Open MCP Gateway

What Is Open MCP Gateway?

Open MCP Gateway, abbreviated as OMG, is a high-performance gateway that exposes locally deployed Model Context Protocol services through HTTP REST routes conforming to OpenAPI 3.1.0. It is built with Bun 1.4 and TypeScript for the Open WebUI ecosystem, although it is a community project and is not affiliated with the Open WebUI team.

The gateway sits between an external client and one or more MCP services. A client such as Open WebUI communicates with the gateway over HTTP or HTTPS, while the gateway manages the underlying MCP transports and converts their tools into an OpenAPI-compatible interface.

OMG supports native binary stdio services, Node or Bun script-based stdio pipelines, and SSE or HTTP network transports. This makes it possible to provide a consistent HTTP interface for MCP services that use different execution and communication models.

Key Features

  • Strict OpenAPI 3.1.0 output: Tool input schemas are placed under requestBody.content['application/json'].schema. Generated operationId values preserve the original MCP tool names instead of adding names such as tool_*_post.
  • Multiple MCP transports: Native binary stdio, script stdio, SSE, and HTTP services can be managed through one gateway.
  • Blue-green session pool: Service sessions are hot-swapped behind an AsyncMutex, allowing configuration updates without interrupting requests already in progress.
  • Lifecycle management: The gateway provides protocol wrapping, lifecycle self-healing, and hot reloading for managed services.
  • Cross-platform XDG layout: Configuration, application data, runtime state, and cache files are kept outside the source repository.
  • Standalone builds: Bun can compile the gateway into a native executable that has no runtime dependencies.
  • Reverse-proxy support: The gateway reads X-Forwarded-* headers so the generated OpenAPI servers.url reflects the external address seen by clients.

Prerequisites

Running the project from source requires Bun 1.4 or later. You also need at least one MCP service to register. That service can be a local native executable, a JavaScript or TypeScript package launched through Bun, or an MCP service available over SSE or HTTP.

Install and Run the Gateway

Run from source

Clone or download the repository, enter its directory, install its dependencies, and start the development command:

bun install
bun run dev

The development process reads the gateway configuration from the platform's XDG configuration directory rather than from the repository itself.

Build a standalone executable

To create a native executable, run:

bun run build

The output is written to build/mcp-gateway on Unix-like systems or build/mcp-gateway.exe on Windows. The compiled binary does not require a separate Bun runtime when deployed.

Understand the XDG Directory Layout

Open MCP Gateway separates files by purpose. This prevents generated data, installed plugins, logs, and caches from polluting the source tree.

  • Configuration: XDG_CONFIG_HOME contains the main mcp-gateway/config.json5 file.
  • Data: XDG_DATA_HOME contains the external MCP plugin repository and its own package.json.
  • State: XDG_STATE_HOME stores runtime state and persistent logs.
  • Cache: XDG_CACHE_HOME stores cached specification documents and transient runtime data.

The main configuration path is:

$XDG_CONFIG_HOME/mcp-gateway/config.json5

The file uses JSON5, so comments and trailing commas are supported.

Configure MCP Services

Create the configuration directory if necessary, then add config.json5. The following example registers one native MCP executable and one package-based MCP service:

{
    mcpServers: {
        // Native Binary Stdio
        codebase_memory: {
            command: "${HOME}/.local/bin/codebase-memory-mcp",
            args: [],
            env: {},
        },

        // Script Stdio
        another_mcp: {
            command: "bun",
            args: [
                "run",
                "${APP_DATA_DIR}/node_modules/<pkg>/dist/index.js",
            ],
            env: {},
        },
    },

    host: "127.0.0.1",
    port: 9090,
}

Each key inside mcpServers identifies an MCP service. For a native binary, set command to the executable path. For a package-based service, use Bun as the command and pass the installed script path through args. Service-specific environment variables can be added to env.

The gateway supports environment-variable interpolation in paths. Variables include ${APP_DATA_DIR}, ${XDG_DATA_HOME}, ${HOME}, and %USERPROFILE%. Interpolation makes a configuration easier to reuse across computers without hard-coding every absolute path.

Keep the service identifier stable. For example, a service named codebase_memory is exposed under the corresponding URL path used when retrieving its OpenAPI document.

Manage External MCP Plugins

Business-specific MCP packages should not be installed in the gateway repository. Install and maintain them in the gateway's XDG data directory instead:

cd "$XDG_DATA_HOME/mcp-gateway"
bun add <mcp-package-name>

To upgrade an installed package, run:

cd "$XDG_DATA_HOME/mcp-gateway"
bun update <pkg>

After installation, reference the package entry point from config.json5 using ${APP_DATA_DIR}, as shown in the script stdio example. This keeps gateway dependencies separate from MCP extension dependencies.

Basic Usage

  1. Install the gateway dependencies or build the native executable.

  2. Create $XDG_CONFIG_HOME/mcp-gateway/config.json5.

  3. Add one or more services under mcpServers.

  4. Start the gateway with bun run dev or launch the compiled executable.

  5. Retrieve the OpenAPI document for the configured service and register it with your external client.

For a service named codebase_memory, the documented OpenAPI URL pattern is:

http://<gateway-host>:8444/codebase_memory/openapi.json

In this example, 8444 is the externally accessible port. It may be a reverse-proxy port rather than the gateway's internal port, such as 9090 in the configuration example.

Integrate with Open WebUI

A reverse proxy such as Caddy or Nginx can expose the gateway over the desired external host, port, and protocol. Configure the proxy to send the appropriate X-Forwarded-* headers. Open MCP Gateway reads these headers when generating the OpenAPI document, ensuring that its servers.url points to the public address instead of the internal listener.

  1. Start Open MCP Gateway behind the reverse proxy.

  2. Open the Open WebUI administration panel.

  3. Go to the Functions, Tools, or OpenAPI area.

  4. Register the OpenAPI document URL for each configured MCP service:

    http://<gateway-host>:8444/codebase_memory/openapi.json

  5. Allow Open WebUI to load the specification. The MCP service's tools can then be consumed as native tools through the generated OpenAPI operations.

Because operation IDs preserve the original MCP tool names, clients see clean tool identifiers without gateway-generated suffixes or prefixes.

Testing and Log Monitoring

Run the project's test command after changing the gateway or its configuration:

bun run test

On Windows, the repository also provides a PowerShell test script:

.\ps1_scripts\test-gateway.ps1

The end-to-end assertions cover the health check, MCP handshake, and proxy origin alignment.

On Unix-like systems, follow the persistent gateway log with:

tail -f "$XDG_STATE_HOME/mcp-gateway/logs/gateway.log"

This is useful when diagnosing process startup problems, invalid executable paths, MCP handshake failures, or reverse-proxy configuration issues.

Advanced Tips

Use portable paths

Prefer interpolated paths such as ${HOME} and ${APP_DATA_DIR} over machine-specific absolute paths. On Windows, %USERPROFILE% can be used where appropriate. This makes it easier to share a configuration across systems.

Keep plugins outside the source checkout

Install external MCP packages in $XDG_DATA_HOME/mcp-gateway. This preserves a clean source tree and allows the gateway and its business extensions to be upgraded independently.

Separate internal and external addresses

Binding the gateway to 127.0.0.1 keeps the internal listener local. A reverse proxy can then provide the external TLS endpoint. Ensure that forwarded headers describe the public scheme, host, and port so generated OpenAPI documents advertise the correct URL.

Take advantage of hot updates

The blue-green session pool swaps service sessions while protecting the transition with an AsyncMutex. This design allows configuration updates without terminating requests that are already running. Hot reloading and lifecycle self-healing further reduce the need for manual process management.

Compile for deployment

Use bun run build when the target server should not need Bun or project dependencies installed. Deploy the generated executable together with the required XDG configuration and any separately managed MCP binaries or packages.

Conclusion

Open MCP Gateway provides a unified bridge from local MCP services to strict OpenAPI 3.1.0 routes. By combining multi-transport support, portable XDG-based configuration, external plugin management, reverse-proxy awareness, and standalone builds, it offers a practical way to make local MCP tools available to Open WebUI and other OpenAPI-capable clients.