mpc-bridge

stdin/stdout json-rpc to http stream sse for llama.cpp

0 stars GoOthers Updated Mar 12, 2026

Documentation

Go MCP HTTP Bridge - Master Documentation

Overview

A Go application that wraps MCP (Model Context Protocol) servers with HTTP streaming (SSE), fully compatible with llama.cpp's StreamableHTTP transport. This bridge allows web-based MCP clients to communicate with subprocess-based MCP servers.

Architecture

code

┌─────────────────┐
│   Client        │
│   (LLM/App)     │
└────────┬────────┘
         │
         │ HTTP POST + SSE Stream
         ▼
┌──────────────────────────────┐
│  Go MCP HTTP Bridge          │
│  ┌────────────────────────┐  │
│  │ HTTP Server            │  │
│  │ - POST /mcp/{ns}/msg   │  │
│  │ - GET  /mcp/{ns} (SSE) │  │
│  └────────────────────────┘  │
│  ┌────────────────────────┐  │
│  │ Protocol Handler       │  │
│  │ - initialize           │  │
│  │ - tools/list           │  │
│  │ - tools/call           │  │
│  └────────────────────────┘  │
│  ┌────────────────────────┐  │
│  │ Subprocess Manager     │  │
│  │ - test-server          │  │
│  └────────────────────────┘  │
└──────────────────────────────┘

Features

✅ Implemented (All Phases 1-6 Complete)

1. HTTP Streaming Server

2. Subprocess Management

3. JSON-RPC 2.0

4. MCP Protocol Support

5. Security

6. Logging

7. Debug Tools

8. Health Checks

9. Prometheus Metrics

10. Enhanced Debug Streaming

🔧 Configuration

Full configuration example:

yaml

bridge:
  port: 8080
  allowed_origins:
    - http://localhost:3000
    - http://127.0.0.1:3000
  request_timeout: 30s
  idle_timeout: 5m
  connection_limit: 5
  request_size_limit: 1048576
  response_size_limit: 10485760

servers:
  filesystem:
    name: "filesystem"
    binary: "/usr/bin/node"
    args:
      - "/path/to/mcp-filesystem-server/index.js"
    env:
      HOME: "/home/user"
    timeout: 30s
    max_restarts: 3
    auto_start: true

  git:
    name: "git"
    binary: "npx"
    args:
      - "-y"
      - "@modelcontextprotocol/server-git"
    timeout: 60s
    max_restarts: 5
    auto_start: false

For complete configuration options, see docs/CONFIG.md.

🚀 Quick Start

1. Build

bash

cd go-mcp-bridge
   make build

2. Configure

Create `config.yaml` with your MCP server settings:

yaml

bridge:
     port: 8080
     allowed_origins:
       - http://localhost:3000

   servers:
     git:
       name: "git"
       binary: "npx"
       args:
         - "-y"
         - "@modelcontextprotocol/server-git"

3. Run

bash

./bin/bridge --config config.yaml

4. Test

bash

# Health check
    curl http://localhost:8080/health

    # Send initialize request
    curl -X POST http://localhost:8080/mcp/git \
      -H "Content-Type: application/json" \
      -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{...}}'

    # Check metrics
    curl http://localhost:8080/metrics

    # View debug stream
    curl http://localhost:8080/debug/stream

📡 API Endpoints

Primary MCP Endpoint

code

GET  /mcp/{namespace}          → Start SSE stream
POST /mcp/{namespace}/message  → Send JSON-RPC request

Example Request:

bash

curl -X POST http://localhost:8080/mcp/test/message \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{...}}'

Health Check

code

GET /health              → Bridge health
GET /health/{namespace}  → Namespace health

Debug Endpoint

code

GET /debug               → Debug dashboard (HTML)
GET /debug/stream        → Debug message stream (SSE)

Project Structure

code

go-mcp-bridge/
├── cmd/
│   ├── bridge/main.go       # Main entry point
│   ├── test-server/         # Go test MCP server
│   └── test-mcp-server/     # TypeScript test MCP server
├── internal/
│   ├── config/
│   │   └── loader.go        # YAML config parser
│   ├── mcp/
│   │   ├── handler.go       # Protocol handler
│   │   ├── jsonrpc.go       # JSON-RPC 2.0
│   │   └── types.go         # MCP types
│   ├── process/
│   │   └── manager.go       # Subprocess manager
│   ├── router/
│   │   └── namespace.go     # Namespace routing
│   └── server/
│       ├── http.go          # HTTP server
│       ├── sse.go           # SSE writer
│       └── metrics.go       # Prometheus metrics
├── docs/                    # Documentation
│   ├── CONFIG.md            # Configuration reference
│   ├── API.md               # API specification
│   ├── EXAMPLES.md          # Usage examples
│   ├── DEBUG.md             # Debug endpoint guide
│   └── TESTING.md           # Testing guide
├── testdata/                # Test configurations
├── bin/                     # Built binaries
├── config.yaml              # Configuration
├── Makefile                 # Build automation
├── test-tool-metrics.sh     # Tool metrics test script
└── README.md                # This file

Testing

Unit Tests

bash

# Run all unit tests
go test ./... -v

# Specific package
go test ./internal/mcp/... -v

End-to-End Test

bash

# Start bridge in background
./bin/bridge --config config.yaml &
BRIDGE_PID=$!

# Run tests
./test.sh

# Stop bridge
kill $BRIDGE_PID

Integration Tests (Complete)

bash

# Test with real subprocess
./test-tool-metrics.sh

# Or run all tests
go test ./... -v

Git Branches

`master` - Current stable (All phases 1-6 complete)

Roadmap

✅ Phase 1-2: Core Architecture (COMPLETE)

✅ HTTP streaming server
✅ Subprocess management
✅ Basic JSON-RPC handling

✅ Phase 3: MCP Protocol Support (COMPLETE)

✅ JSON-RPC 2.0 handling
✅ Initialize method
✅ Tools/list and tools/call
✅ Request-response correlation

✅ Phase 4: Security & Error Handling (COMPLETE)

✅ Input validation (JSON-RPC, arguments)
✅ Command injection prevention
✅ Resource limits (size, connections)
✅ Exponential backoff restarts
✅ Graceful shutdown
✅ Structured JSON logging

✅ Phase 5: Testing & Documentation (COMPLETE)

✅ Unit tests (45 tests)
- JSON-RPC parsing (20 tests)
- Config loading (14 tests)
- Namespace routing (11 tests)
✅ Integration tests (45+ tests)
- HTTP server tests (20+ tests)
- Process manager tests (15+ tests)
- Namespace isolation tests (10 tests)
✅ Complete documentation (docs/CONFIG.md, docs/API.md, docs/EXAMPLES.md, docs/DEBUG.md, docs/TESTING.md)

✅ Phase 6: Build & Monitoring (COMPLETE)

✅ 6.1 Prometheus metrics (/metrics endpoint)
- ✅ HTTP request metrics (mcp_http_requests_total, mcp_http_request_duration_seconds)
- ✅ Active sessions gauge (mcp_active_sessions)
- ✅ Subprocess state metrics (mcp_subprocess_state)
- ✅ Tool call metrics (mcp_tool_calls_total, mcp_tool_calls_duration_seconds, mcp_tool_errors_total)
- ✅ Metrics endpoint at /metrics
✅ 6.2 Structured logging with slog
- ✅ Replace fmt.Printf with slog
- ✅ JSON structured logging
- ✅ Context-aware logs (namespace, session, request_id)
✅ 6.3 Enhanced debug streaming
- ✅ Stream DEBUG and INFO logs to /debug/stream
- ✅ JSON-RPC 2.0 compliant SSE format
- ✅ No verbose flag needed
✅ 6.4 Configuration cleanup
- ✅ Remove unused debug_port configuration
- ✅ Keep debug endpoints on main port 8080
✅ 6.5 Test script for tool metrics (test-tool-metrics.sh)
✅ 6.6 End-to-end verification of tool metrics recording

All phases complete as of Phase 6 merge to master.

Compatibility

✅ llama.cpp web frontend

Compatible with StreamableHTTP transport
Works with latest llama.cpp build

✅ MCP SDK

Uses standard JSON-RPC 2.0 format
Supports MCP protocol versions:
- 2025-06-18 (latest)
- 2025-03-26 (default)
- 2024-11-05 (backward compat)

Known MCP Servers

These servers can be used with the bridge:

1. Git MCP (NPM)

yaml

servers:
     git:
       name: "git"
       binary: "npx"
       args: ["-y", "@modelcontextprotocol/server-git"]

2. Filesystem MCP (uvx)

yaml

servers:
     filesystem:
       name: "filesystem"
       binary: "uvx"
       args: ["mcp-server-filesystem", "--allowed-directory", "/data"]

3. Memory MCP (Docker)

yaml

servers:
     memory:
       name: "memory"
       binary: "docker"
       args: ["run", "-i", "mcp/memory-server"]

4. Custom Binary

yaml

servers:
     custom:
       name: "custom"
       binary: "./my-mcp-server"
       args: ["--port", "8080"]

See EXAMPLES.md for more configuration examples.

Troubleshooting

Subprocess won't start

Check binary path is correct: `which npx`
Verify binary is executable: `chmod +x ./bin/test-server`
Check environment variables in config
Look at structured logs for errors

Connection fails

Verify namespace exists in config
Check `allowed_origins` includes client origin
Look at `/debug/stream` for real-time errors
Check `/health/{namespace}` for subprocess status

Messages not streaming

Ensure subprocess outputs JSON-RPC to stdout
Check for newline termination on messages (`\n`)
Verify SSE headers are set correctly
Use `/debug/stream` to see raw messages

High restart count

Check subprocess logs for errors
Increase timeout if subprocess is slow
Verify args are correct
Check resource limits

Security errors

Verify argument sanitization
Check allowed hosts/origins
Ensure binary path is safe (no shell injection)

Documentation

Document	Description
docs/CONFIG.md	Complete configuration reference
docs/API.md	HTTP API specification
docs/EXAMPLES.md	Usage examples and configurations
docs/DEBUG.md	Debug endpoint guide
docs/TESTING.md	Testing guide and test infrastructure

Contributing

Contributions welcome! Please:

1. Create a feature branch

2. Add tests for new functionality

3. Update documentation

4. Submit a pull request

License

MIT

Frequently asked questions

What is mpc-bridge?

mpc-bridge is stdin/stdout json-rpc to http stream sse for llama.cpp

How do I install mpc-bridge?

Open the GitHub repository and follow its README. Most MCP servers are added to your client's MCP config, then called by your agent.

Is mpc-bridge open source?

Yes — it is hosted on GitHub at https://github.com/AgentForgeEngine/mpc-bridge.

Related MCP tools

kubeshark

eBPF-powered network observability for Kubernetes. Indexes L4/L7 traffic with full K8s context, decrypts TLS without keys. Queryable by AI agents via MCP and humans via dashboard.

12,068 Go

kubernetesgolangrest+17

go-whatsapp-web-multidevice

GOWA - WhatsApp REST API with support for UI, Multi Account, Webhooks, and MCP, and Chatwoot. Built with Golang for efficient memory use.

4,717 Go

whatsappwhatsapp-apiwhatsapp-api-go+9

radar

The missing open-source Kubernetes UI with a built-in MCP server for AI agents. See what's broken, why, and what changed. Issues, Topology, event timeline, Helm, GitOps, live service traffic, and cluster audits - all in one Go binary.

3,246 Go

argocdcloud-nativegitops+17

mcp-language-server

mcp-language-server gives MCP enabled clients access semantic tools like get definition, references, rename, and diagnostics.

1,587 Go

ailanguage-server-protocolmcp+2

terraform-mcp-server

The Terraform MCP Server provides seamless integration with Terraform ecosystem, enabling advanced automation and interaction capabilities for Infrastructure as Code (IaC) development.

1,522 Go

matlab-mcp-server

Run MATLAB® using AI applications with the official MATLAB MCP Server from MathWorks®. This MCP server for MATLAB supports a wide range of coding agents like Claude Code® and Visual Studio® Code.

1,461 Go

engineering-toolsmatlabmcp-server+2

Run your own MCP server? See who uses it and what to fix.

Measure it with TrackMCP