MCP-Bridge

Author: SecretiveShell

Description: Middleware/bridge that exposes OpenAI-compatible REST endpoints and connects them to MCP (Model Context Protocol) tools/servers. It injects MCP tool definitions into OpenAI-style requests, executes tool calls against configured MCP servers, and feeds tool results back to the inference engine. Also provides an SSE endpoint so MCP-native clients can use it like an MCP server. Note: README states the project is 'soft deprecated' because Open WebUI supports MCP natively as of v0.6.31, and the project is seeking additional maintainers.

Stars: 923

Forks: 115

License: MIT License

Category: Open Source

GitHub Documentation Discord

Overview

Installation

## Docker installation (recommended)

1. Clone the repository.

2. Edit `compose.yml` and provide configuration via one of these options:Example environment variables (as shown in README):```bash

environment:

- MCP_BRIDGE__CONFIG__FILE=config.json # mount the config file for this to work

- MCP_BRIDGE__CONFIG__HTTP_URL=http://10.88.100.170:8888/config.json

- MCP_BRIDGE__CONFIG__JSON={"inference_server":{"base_url":"http://example.com/v1","api_key":"None"},"mcp_servers":{"fetch":{"command":"uvx","args":["mcp-server-fetch"]}}}

volumes:
  - ./config.json:/mcp_bridge/config.json

- Mount a `config.json` file and set `MCP_BRIDGE__CONFIG__FILE=config.json`.

- Set `MCP_BRIDGE__CONFIG__HTTP_URL` to download `config.json` over HTTP.

- Inline the config using `MCP_BRIDGE__CONFIG__JSON=...`.

3. Run the service:```bash

docker-compose up --build -d


## Manual installation (no docker)

1. Clone the repository.
2. Install dependencies:```bash
uv sync

3. Create a `config.json` file in the repository root (example from README):```json

{

"inference_server": {

"base_url": "http://example.com/v1",

"api_key": "None"

"mcp_servers": {

"fetch": {

"command": "uvx",

"args": ["mcp-server-fetch"]

}

4. Run the application:```bash
uv run mcp_bridge/main.py

## Runtime docs

- After starting, view API docs at:

- `http://localhost:8000/docs` (or `http://yourserver:8000/docs`)

Notes from README:

- Requires an inference engine with tool-call support; tested with vLLM, and ollama “should also be compatible”.

FAQs

Which Ollama models support tool calling and are compatible with MCP-Bridge?

Ollama models that support tool calling include Llama 3.1 and 3.2, Mistral Large, Qwen 2.5, Command R, and Llama 3.3. These models work with MCP-Bridge when served through Ollama's OpenAI-compatible endpoint. Check model cards on Ollama's library to confirm tool-calling capability before deployment, as quantization can affect function-calling reliability in smaller variants.

What is the difference between MCP-Bridge and mcp-proxy, and when should I use each one?

MCP-Bridge transforms OpenAI API calls into MCP tool executions and bridges inference workflows, while mcp-proxy simply translates MCP transport protocols like STDIO to SSE without handling inference. Use mcp-proxy for transport compatibility between MCP components. Use MCP-Bridge when your OpenAI-compatible client needs to invoke MCP tools through an inference engine lacking native MCP support.

What are the known issues with MCP-Bridge v0.5.1 and how do they affect production deployments?

Version 0.5.1 predates config schema changes for security and CORS settings, causing startup failures with newer examples. The critical issue is that tool execution behavior is affected by open bugs, though specific failure modes aren't documented. Without active maintenance, teams face unpredictable behavior and no fix timeline, making production risk assessment difficult.

How do I configure MCP-Bridge to work with vLLM or Ollama as the inference backend?

Set base_url in config.json to point at your inference engine's /v1 endpoint, using host.docker.internal instead of localhost when running in Docker. For Ollama on the host, the URL is http://host.docker.internal:11434/v1 with api_key set to the string "None" rather than null. Ensure your chosen model supports function calling; quantized Ollama models may lack this capability and silently fail to invoke MCP tools.

What are the common challenges when setting up an MCP server?

Common MCP server setup challenges include dependency conflicts between Python environments, transport protocol mismatches (STDIO versus SSE), authentication errors when integrating with host platforms, versioning incompatibilities across MCP implementations, and debugging tool invocation failures without clear error messages. Configuration schema changes between versions can break existing setups, requiring careful testing before deployment.

How can I optimize the performance of an MCP server?

Performance optimization depends on your MCP server's workload and infrastructure. Implement autoscaling with request batching to share GPU resources, reducing idle time up to fifty percent. Apply quantization and model pruning for resource-constrained deployments. Use Streamable HTTP over SSE, cache embeddings with proper invalidation, and route latency-sensitive traffic through geo-distributed endpoints with health-check fallbacks.