Skip to content

About

A lightweight, zero-dependency Go bridge that connects llama.cpp and stdio-only MCP clients to remote SSE and Streamable HTTP endpoints. Features bearer token authentication, automatic tool namespacing/prefixing, and resilient stream handling.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

8 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

mcp-bridge

A lightweight Go bridge that connects llama.cpp and other stdio-only MCP clients to remote MCP servers via SSE or Streamable HTTP. Rewritten to use the official modelcontextprotocol/go-sdk v1.8.0 for full spec compliance.

Stdio interface: The bridge presents a JSON-RPC stdio interface to the calling client. Stderr logging can be silenced by setting EnableStderr = false in main.go.

Features

  • Protocol Agnostic: Supports legacy MCP SSE and modern Streamable HTTP. Transport is selected via MCP_TRANSPORT.
  • Automatic Namespacing: Prefixes tool names prefix_<name> to prevent collisions. If a tool name already starts with prefix_, it is left unchanged to avoid double-prefixing.
  • Secure Authentication: Bearer token via MCP_BEARER_TOKEN injected via HTTP client transport.
  • Zero Runtime Dependencies: Single static binary, no external runtime required.
  • Spec Compliant: Uses official go-sdk for transport, session management, protocol version negotiation, and per-request headers.

Building

docker run --rm -v "${PWD}:/app" -w /app golang:1.22-alpine \
  sh -c 'go mod download && go build -ldflags="-w -s" -o mcp-bridge .'

Stderr logging is controlled by the EnableStderr boolean at the top of main.go. Set it to false to silence stderr output.

Usage

mcp-bridge <prefix> <url> [log]

Environment variables:

  • MCP_TRANSPORT = sse | streamable | http (default sse)
  • MCP_BEARER_TOKEN = Bearer token for auth
  • LOGFILE = path for stdio logging when third arg is log (default /config/mcp-bridge.log)

Optional third argument log enables stdio logging of inbound/outbound JSON-RPC to LOGFILE.

llama.cpp example

mcp.json:

{
  "mcpServers": {
    "wikipedia": {
      "command": "/app/mcp-bridge",
      "args": ["wikipedia", "https://example.com/sse"],
      "env": { "MCP_TRANSPORT": "sse" }
    }
  }
}

Mount the binary into the llama.cpp container and pass --mcp-servers-config.

Architecture

  • Local side: reads JSON-RPC from stdin, writes to stdout, handles initialize reply locally
  • Remote side: mcp.Client with SSEClientTransport or StreamableClientTransport
  • Tools are listed via SDK, names are prefixed unless already prefixed, calls are forwarded with prefix stripped

Notes

  • Built with github.com/modelcontextprotocol/go-sdk v1.8.0
  • Bearer token is injected via custom HTTP roundtripper
  • Stderr logging is controlled by EnableStderr boolean in main.go; set to false to silence stderr

Limitations

  • Only tools/list and tools/call are proxied. Other MCP methods are passed through only if the client uses the SDK server path; the manual stdio parser is intentionally minimal for the llama.cpp use-case.
  • Modern 2026-07-28 per-request Mcp-Param-* mirroring from x-mcp-header annotations is handled by the SDK defaults; custom annotation extraction is not implemented.
  • Standalone SSE stream is disabled via DisableStandaloneSSE:true for compatibility with test servers that reject GET without session.

About

A lightweight, zero-dependency Go bridge that connects llama.cpp and stdio-only MCP clients to remote SSE and Streamable HTTP endpoints. Features bearer token authentication, automatic tool namespacing/prefixing, and resilient stream handling.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages