mcp-0ne

One MCP server to rule them all.

A standalone MCP Gateway that multiplexes N backend MCP servers behind a single endpoint. Connect your MCP client once, manage backends dynamically at runtime.

MCP Client  ──(HTTP)──>  mcp-0ne (:8150)
                              │
              ┌───────────────┼───────────────┐
              │               │               │
         (HTTP client)   (stdio spawn)   (stdio spawn)
              │               │               │
         HTTP MCP         stdio MCP       stdio MCP
         server           server          server

Quickstart

# Install
pip install -e .

# Start with empty backends
python -m mcp_0ne.server

# Verify
curl http://127.0.0.1:8150/health

Connect Claude Code

Add to your .mcp.json:

{
  "mcpServers": {
    "0ne": {
      "type": "http",
      "url": "http://127.0.0.1:8150/mcp"
    }
  }
}

Add Backends

Via MCP tool (from Claude Code)

Call 0ne__add:

{
  "id": "myapp",
  "type": "http",
  "prefix": "myapp",
  "url": "http://127.0.0.1:8100/mcp",
  "description": "My App MCP Server"
}

Via REST API

curl -X POST http://127.0.0.1:8150/api/backends/myapp \
  -H "Content-Type: application/json" \
  -d '{"type":"http","prefix":"myapp","url":"http://127.0.0.1:8100/mcp"}'

Via config file

Edit backends.json:

{
  "backends": {
    "myapp": {
      "type": "http",
      "url": "http://127.0.0.1:8100/mcp",
      "prefix": "myapp",
      "enabled": true,
      "description": "My App MCP Server"
    }
  },
  "settings": {
    "separator": "__",
    "lazy_connect": true,
    "tool_cache_ttl": 60,
    "log_level": "info"
  }
}

Backend Types

HTTP

Connects to an existing MCP server over HTTP JSON-RPC 2.0.

Field	Required	Description
type	yes	"http"
prefix	yes	Tool namespace prefix
url	yes	MCP endpoint URL
health_url	no	Health check URL
timeout	no	Request timeout (default: 30s)
description	no	Human-readable description
enabled	no	Auto-connect (default: true)

Stdio

Spawns a subprocess and communicates via MCP SDK stdio transport.

Field	Required	Description
type	yes	"stdio"
prefix	yes	Tool namespace prefix
command	yes	Executable path
args	no	Command arguments
env	no	Environment variables
timeout	no	Operation timeout (default: 60s)
description	no	Human-readable description
enabled	no	Auto-connect (default: true)

Admin Tools

Available as MCP tools (prefix 0ne__):

Tool	Description
0ne__discover	List all backends with state and tool counts
0ne__health	Health check all backends with latency
0ne__add	Register a new backend at runtime
0ne__remove	Disconnect and unregister a backend
0ne__enable	Enable a disabled backend
0ne__disable	Disable a backend without removing it
0ne__refresh	Force reconnect and re-enumerate tools

REST API

Method	Path	Description
GET	/api/backends	List all backends
POST	/api/backends/{id}	Add a new backend
DELETE	/api/backends/{id}	Remove a backend
PATCH	/api/backends/{id}	Update backend config
POST	/api/backends/{id}/refresh	Reconnect and refresh

Environment Variables

Variable	Default	Description
MCP_0NE_HOST	127.0.0.1	Server bind address
MCP_0NE_PORT	8150	Server port
MCP_0NE_CONFIG	./backends.json	Config file path
MCP_0NE_LOG_LEVEL	info	Log level

Tool Namespacing

Tools from backends are exposed with a namespace prefix:

{prefix}__{original_tool_name}

For example, a backend with prefix myapp exposing a tool search becomes myapp__search. The separator __ is configurable in settings.