MCPTokenBridge

MCPTokenBridge runs a single Python process that serves an OpenAI-compatible HTTP endpoint for chat completions while simultaneously acting as a persistent MCP tool, enabling MCP-style request handling through a background hook. This setup lets you forward chat-like requests to an MCP workflow and receive results with MCP headers in the same runtime.

How to use

You run the bridge and then connect your MCP client to the local HTTP endpoint. When you send a request to the HTTP endpoint, it is placed in a queue and forwarded to the hook worker. The hook worker keeps running, processes items from the queue, and returns the results along with MCP headers. You can also send MCP requests via standard input to the same process if you choose to use the stdin-based flow.

How to install

Prerequisites you need before starting: a Python 3 environment and a copy of the project files. You will also need a virtual environment for isolation.

pip install --upgrade pip
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Additional configuration and usage notes

Start the bridge so it exposes an HTTP endpoint on a chosen host and port. You can bind to all network interfaces or a specific one depending on your networking setup.

python mcptb.py --host 0.0.0.0 --port 8000

You can also feed an MCP initialize sequence via stdin to the same process, for example:

echo '{"jsonrpc":"2.0","id":1,"method":"initialize"}' | python mcptb.py --host 0.0.0.0 --port 8000

Configuration examples

{
  "mcpServers": {
    "token_bridge": {
      "type": "http",
      "name": "token_bridge",
      "url": "http://127.0.0.1:8000",
      "args": []
    },
    "token_bridge_stdio": {
      "type": "stdio",
      "name": "token_bridge_stdio",
      "command": "python",
      "args": ["mcptb.py", "--host", "127.0.0.1", "--port", "8000"]
    }
  },
  "envVars": []
}

This JSON shows both a local HTTP endpoint and a local stdio MCP entry that point to the same runtime, with no extra environment variables required by default.

## Available tools

### chatEndpoint

OpenAI-compatible HTTP endpoint at /v1/chat/completions that enqueues requests and returns responses.

### hookWorker

A persistent background worker thread that drains the request queue, forwards items to MCP, and appends X-MCP-\* headers to responses.