MCP Servers

MCP Agent Bridge

An agent gateway that aggregates multiple local MCP servers into a single MCP endpoint with runtime control, hot-reloadable configuration, and meta tools like bridge__execute for calling any child server tool without restart.

README

MCP Agent Bridge

🚀 A lightweight agent gateway that combines multiple local MCP servers into a single MCP endpoint — with runtime control, hot-reloadable configuration, and a powerful bridge__execute tool that lets you call any child server tool without restarting.

✨ What's new in v0.3.0

mindmap
  root((MCP Agent Bridge v0.3.0))
    🚀 Primary Tool
      bridge__execute
        Execute any tool on any server
        1:1 response from child
        No client restart needed
    🔍 Discovery
      bridge__list_server_tools
        List tools per server
        Show input schemas
      bridge__list_servers
        Overview of all servers
        Show skipped reasons
    🎛️ Runtime Control
      bridge__enable_server
        Start server at runtime
        Persist to config
      bridge__disable_server
        Stop server at runtime
        Persist to config
    🔄 Hot Reload
      fs.watch debouncer
      Auto-apply in ~500ms
    🧠 Agent Architecture
      Bridge = Agent
      Client = Commander
      No restart needed

No restarts. No external edits. Just call bridge__execute.

🌍 Overview

MCP Agent Bridge is an agent gateway that turns multiple local MCP servers into one clean remote-facing MCP endpoint.

Instead of exposing or managing each MCP server separately, this bridge:

📖 reads a standard mcpServers JSON config
🎯 starts only the servers you want
🔗 aggregates their tools
🏷️ prefixes tool names by source server
🛰️ exposes its own meta tools for runtime inspection & control
🌐 exposes everything through a single /mcp endpoint
🚀 provides bridge__execute to call any child server tool without client restart

🧩 Why this project exists

graph TB
    subgraph Problems["❌ Problems"]
        direction TB
        P1["Many servers, few should run"]
        P2["Tools should stay disabled"]
        P3["Remote clients need one endpoint"]
        P4["Tool name collisions"]
        P5["Enable/disable requires restart"]
        P6["Clients don't re-fetch tools"]
    end

    subgraph Solutions["✅ MCP Agent Bridge Solutions"]
        direction TB
        S1["Selective server startup"]
        S2["disabled: true support"]
        S3["Single /mcp endpoint"]
        S4["Server-prefixed tool names"]
        S5["Runtime enable/disable"]
        S6["bridge__execute (no restart)"]
    end

    P1 --> S1
    P2 --> S2
    P3 --> S3
    P4 --> S4
    P5 --> S5
    P6 --> S6

    style Problems fill:#e94560,stroke:#fff,color:#fff
    style Solutions fill:#0f3460,stroke:#533483,color:#fff
    style P1 fill:#fff,stroke:#e94560,color:#000
    style P2 fill:#fff,stroke:#e94560,color:#000
    style P3 fill:#fff,stroke:#e94560,color:#000
    style P4 fill:#fff,stroke:#e94560,color:#000
    style P5 fill:#fff,stroke:#e94560,color:#000
    style P6 fill:#fff,stroke:#e94560,color:#000
    style S1 fill:#fff,stroke:#533483,color:#000
    style S2 fill:#fff,stroke:#533483,color:#000
    style S3 fill:#fff,stroke:#533483,color:#000
    style S4 fill:#fff,stroke:#533483,color:#000
    style S5 fill:#fff,stroke:#533483,color:#000
    style S6 fill:#fff,stroke:#533483,color:#000

MCP Agent Bridge solves those problems with a small, explicit, easy-to-debug layer — including runtime enable/disable without restarts.

🏗️ Architecture

The Agent-Commander Pattern

graph TB
    subgraph Commander["🎯 Commander (ZCode)"]
        Z["ZCode / AI Agent"]
    end

    subgraph Agent["🤖 Agent (MCP Agent Bridge)"]
        B["Bridge Gateway"]
        R["Router"]
        M["Meta Tools"]
    end

    subgraph Children["👶 Child MCP Servers"]
        S1["🔧 ssh-mcp<br/><i>7 tools</i>"]
        S2["🌐 web-curl<br/><i>7 tools</i>"]
        S3["🎨 vision-generator<br/><i>7 tools</i>"]
        S4["🎭 playwright-extension<br/><i>61 tools</i>"]
        S5["🖥️ cpanel<br/><i>171 tools</i>"]
    end

    Z -->|"bridge__execute({server, tool, args})"| B
    Z -->|"bridge__list_servers()"| B
    Z -->|"bridge__enable_server({server})"| B
    Z -->|"bridge__disable_server({server})"| B
    Z -->|"bridge__list_server_tools({server})"| B

    B --> R
    R --> M
    R --> S1
    R --> S2
    R --> S3
    R --> S4
    R --> S5

    style Commander fill:#1a1a2e,stroke:#e94560,color:#fff
    style Agent fill:#16213e,stroke:#0f3460,color:#fff
    style Children fill:#0f3460,stroke:#533483,color:#fff
    style Z fill:#e94560,stroke:#fff,color:#fff
    style B fill:#533483,stroke:#fff,color:#fff
    style R fill:#0f3460,stroke:#fff,color:#fff
    style M fill:#e94560,stroke:#fff,color:#fff
    style S1 fill:#1a1a2e,stroke:#e94560,color:#fff
    style S2 fill:#1a1a2e,stroke:#e94560,color:#fff
    style S3 fill:#1a1a2e,stroke:#e94560,color:#fff
    style S4 fill:#1a1a2e,stroke:#e94560,color:#fff
    style S5 fill:#1a1a2e,stroke:#e94560,color:#fff

Key idea

The bridge is the agent that manages all child server sessions. The client (ZCode) is the commander that sends instructions through bridge__execute.

Benefits:

✅ Client only needs to know 5 meta tools (not hundreds of child tools)
✅ Enable/disable servers without client restart
✅ Response is 1:1 from child server (no data transformation)
✅ All session management happens inside the bridge

Request flow

sequenceDiagram
    participant C as 🎯 Commander
    participant B as 🤖 Bridge
    participant S as 👶 Child Server

    Note over C,S: bridge__execute Flow
    C->>B: bridge__execute({server: "web-curl", tool: "fetch_api", args: {...}})
    activate B
    B->>B: Parse server & tool name
    B->>B: Route to correct child server
    B->>S: tools/call({name: "fetch_api", args: {...}})
    activate S
    S-->>B: {content: [{type: "text", text: "..."}]}
    deactivate S
    B-->>C: {content: [{type: "text", text: "..."}]} (1:1 response)
    deactivate B

    Note over C,S: Server Management Flow
    C->>B: bridge__enable_server({server: "cpanel"})
    activate B
    B->>B: Update config file
    B->>B: Start child server process
    B->>S: Initialize MCP connection
    S-->>B: Server ready
    B-->>C: "Enabled cpanel. Config updated."
    deactivate B

Enable/Disable flow

flowchart LR
    subgraph Input["📥 Command"]
        I1["bridge__enable_server"]
        I2["bridge__disable_server"]
    end

    subgraph Bridge["🤖 Bridge Agent"]
        B1["Update Config File"]
        B2["File Watcher Trigger"]
        B3["Start/Stop Server"]
        B4["Update Tool Map"]
    end

    subgraph Output["📤 Result"]
        O1["Server Running"]
        O2["Server Stopped"]
        O3["Tools Exposed"]
        O4["Tools Removed"]
    end

    I1 --> B1
    I2 --> B1
    B1 --> B2
    B2 --> B3
    B3 --> B4
    B4 --> O1
    B4 --> O2
    B4 --> O3
    B4 --> O4

    style Input fill:#1a1a2e,stroke:#e94560,color:#fff
    style Bridge fill:#16213e,stroke:#0f3460,color:#fff
    style Output fill:#0f3460,stroke:#533483,color:#fff
    style I1 fill:#e94560,stroke:#fff,color:#fff
    style I2 fill:#e94560,stroke:#fff,color:#fff
    style B1 fill:#533483,stroke:#fff,color:#fff
    style B2 fill:#533483,stroke:#fff,color:#fff
    style B3 fill:#533483,stroke:#fff,color:#fff
    style B4 fill:#533483,stroke:#fff,color:#fff
    style O1 fill:#0f3460,stroke:#fff,color:#fff
    style O2 fill:#0f3460,stroke:#fff,color:#fff
    style O3 fill:#0f3460,stroke:#fff,color:#fff
    style O4 fill:#0f3460,stroke:#fff,color:#fff

🛰️ Bridge meta tools

The bridge exposes 5 tools at the gateway level (prefix bridge__) that are always available regardless of which child servers are loaded.

`bridge__execute` 🚀

The primary way to interact with child MCP servers.

Execute any tool on any loaded server. The response is returned exactly as-is from the child server (1:1 output).

Args:

Field	Type	Required	Description
`server`	string	✅	Name of the MCP server (e.g. `"ssh-mcp"`, `"web-curl"`, `"vision-generator"`)
`tool`	string	✅	Name of the tool to execute (e.g. `"terminal-start"`, `"fetch_api"`)
`args`	object	❌	Arguments to pass to the tool. Use `{}` for tools with no required parameters

Examples:

// List models from vision-generator
{ "server": "vision-generator", "tool": "list_models" }

// Fetch a URL
{ "server": "web-curl", "tool": "fetch_api", "args": { "url": "https://example.com", "method": "GET", "limit": 1000 } }

// Start SSH terminal
{ "server": "ssh-mcp", "tool": "terminal-start", "args": { "account": "rayhan-vps" } }

// Generate an image
{ "server": "vision-generator", "tool": "generate_image", "args": { "model": "gpt-image-2", "prompt": "A cat", "output": { "directory": "C:/output" } } }

// Take a screenshot
{ "server": "playwright-extension", "tool": "browser_take_screenshot", "args": { "type": "png" } }

`bridge__list_server_tools` 🔍

List all available tools for a specific MCP server, including their input schemas.

Args:

Field	Type	Required	Description
`server`	string	✅	Name of the MCP server to list tools for

Output: JSON object with server name, tool count, and array of tools with names, descriptions, and input schemas.

Use it when:

you want to know what tools a server supports
you need to check required parameters before calling bridge__execute
you're exploring a server's capabilities

`bridge__list_servers` 🛰️

Get a complete overview of what the bridge is currently exposing.

Args (optional):

Field	Type	Description
`server`	string	Filter to a specific server name (exact match)

Output: Plain text summary including:

Loaded servers with tool counts
Skipped servers with reasons
Total exposed tool count
Full list of exposed tool names

`bridge__disable_server` 🔒

Disable a server at runtime. The change is persisted to the config file — it survives restarts.

Args:

Field	Type	Required	Description
`server`	string	✅	Name of the server entry in `mcpServers`

`bridge__enable_server` 🔓

Re-enable a previously disabled server. The change is persisted to the config file.

Args:

Field	Type	Required	Description
`server`	string	✅	Name of the server entry in `mcpServers`

🏷️ Tool naming strategy

Every tool is prefixed with its source server. Bridge meta tools use the bridge__ prefix.

graph LR
    subgraph Child["👶 Child Server Tools"]
        direction TB
        C1["vision-generator__list_models"]
        C2["web-curl__fetch_api"]
        C3["ssh-mcp__terminal-start"]
        C4["playwright__browser_navigate"]
    end

    subgraph Bridge["🤖 Bridge Meta Tools"]
        direction TB
        B1["bridge__execute"]
        B2["bridge__list_servers"]
        B3["bridge__list_server_tools"]
        B4["bridge__enable_server"]
        B5["bridge__disable_server"]
    end

    C1 -.- |"server prefix"| P1["vision-generator"]
    C2 -.- |"server prefix"| P2["web-curl"]
    C3 -.- |"server prefix"| P3["ssh-mcp"]
    C4 -.- |"server prefix"| P4["playwright"]

    style Child fill:#1a1a2e,stroke:#e94560,color:#fff
    style Bridge fill:#16213e,stroke:#0f3460,color:#fff
    style C1 fill:#533483,stroke:#fff,color:#fff
    style C2 fill:#533483,stroke:#fff,color:#fff
    style C3 fill:#533483,stroke:#fff,color:#fff
    style C4 fill:#533483,stroke:#fff,color:#fff
    style B1 fill:#e94560,stroke:#fff,color:#fff
    style B2 fill:#e94560,stroke:#fff,color:#fff
    style B3 fill:#e94560,stroke:#fff,color:#fff
    style B4 fill:#e94560,stroke:#fff,color:#fff
    style B5 fill:#e94560,stroke:#fff,color:#fff
    style P1 fill:#0f3460,stroke:#fff,color:#fff
    style P2 fill:#0f3460,stroke:#fff,color:#fff
    style P3 fill:#0f3460,stroke:#fff,color:#fff
    style P4 fill:#0f3460,stroke:#fff,color:#fff

Why this matters

🚫 Avoids name collisions between servers
👀 Makes tool origin obvious at a glance
🧰 Keeps remote clients easier to debug
📈 Scales better as more servers are added
🛰️ Gives the bridge its own namespace for management tools

💡 Examples

Enable a server and use it immediately

You: "Enable vision-generator on the bridge."

AI: → bridge__enable_server { "server": "vision-generator" }

Bridge: "Enabled \"vision-generator\". Config updated at /path/to/default.json."

AI: "Let me generate an image now."

AI: → bridge__execute {
      "server": "vision-generator",
      "tool": "generate_image",
      "args": {
        "model": "gpt-image-2",
        "prompt": "A cyberpunk city at night",
        "output": { "directory": "C:/Users/rayss/ZCodeProject" }
      }
    }

Bridge: (returns 1:1 response from vision-generator with image data)

Explore a server's tools

You: "What tools does web-curl have?"

AI: → bridge__list_server_tools { "server": "web-curl" }

Bridge: {
  "server": "web-curl",
  "toolCount": 7,
  "tools": [
    { "name": "fetch_api", "description": "Performs a REST API request...", "inputSchema": {...} },
    { "name": "multi_search", "description": "Executes multiple Google search queries...", "inputSchema": {...} },
    ...
  ]
}

Toggle servers dynamically

You: "Disable cpanel, I don't need it right now."

AI: → bridge__disable_server { "server": "cpanel" }

Bridge: "Disabled \"cpanel\". Config updated."

AI: "Done. cpanel is stopped. Its 171 tools are no longer exposed."

---

You: "Okay, turn it back on."

AI: → bridge__enable_server { "server": "cpanel" }

Bridge: "Enabled \"cpanel\". Config updated."

AI: "cpanel is back. You can use it now."

📁 Project structure

graph TB
    subgraph Root["📁 MCP_Bridge"]
        direction TB
        R1["config/"]
        R2["src/"]
        R3["tools/"]
        R4["package.json"]
        R5["README.md"]
    end

    subgraph Config["📁 config"]
        direction TB
        C1["default.json<br/><i>Real config (gitignored)</i>"]
        C2["default.example.json<br/><i>Sanitized template</i>"]
        C3["README.md<br/><i>Setup guide</i>"]
    end

    subgraph Src["📁 src"]
        direction TB
        S1["index.js<br/><i>Main server, auth, watcher</i>"]
        S2["config.js<br/><i>CLI args, config loading</i>"]
        S3["childServers.js<br/><i>Lifecycle, tool map, health</i>"]
        S4["router.js<br/><i>5 meta tools</i>"]
        S5["cli/<br/><i>Launcher</i>"]
    end

    subgraph Tools["📁 tools"]
        direction TB
        T1["cloudflared.exe<br/><i>Tunnel helper</i>"]
    end

    R1 --> Config
    R2 --> Src
    R3 --> Tools

    style Root fill:#0f3460,stroke:#533483,color:#fff
    style Config fill:#1a1a2e,stroke:#e94560,color:#fff
    style Src fill:#16213e,stroke:#0f3460,color:#fff
    style Tools fill:#1a1a2e,stroke:#e94560,color:#fff
    style R1 fill:#533483,stroke:#fff,color:#fff
    style R2 fill:#533483,stroke:#fff,color:#fff
    style R3 fill:#533483,stroke:#fff,color:#fff
    style R4 fill:#533483,stroke:#fff,color:#fff
    style R5 fill:#533483,stroke:#fff,color:#fff
    style C1 fill:#e94560,stroke:#fff,color:#fff
    style C2 fill:#533483,stroke:#fff,color:#fff
    style C3 fill:#533483,stroke:#fff,color:#fff
    style S1 fill:#e94560,stroke:#fff,color:#fff
    style S2 fill:#533483,stroke:#fff,color:#fff
    style S3 fill:#533483,stroke:#fff,color:#fff
    style S4 fill:#e94560,stroke:#fff,color:#fff
    style S5 fill:#533483,stroke:#fff,color:#fff
    style T1 fill:#533483,stroke:#fff,color:#fff

Important files

File	Purpose
`src/index.js`	Main HTTP server, session handling, auth, routes, config watcher
`src/config.js`	CLI argument parsing and config loading
`src/childServers.js`	Child server lifecycle, tool map, health check, enable/disable persistence, `getToolsForServer()`
`src/router.js`	Gateway MCP server with 5 meta tools (`list_servers`, `disable_server`, `enable_server`, `execute`, `list_server_tools`)
`src/cli/ui.js`	Interactive launcher with prompts
`src/cli/launch.js`	Process spawner for gateway & tunnel
`config/default.json`	Main config (gitignored — contains your secrets)
`config/default.example.json`	Sanitized template — safe to commit

⚡ Quick start

flowchart LR
    subgraph Setup["📦 Setup"]
        S1["1. npm install"]
        S2["2. cp config/default.example.json config/default.json"]
        S3["3. Edit config/default.json"]
    end

    subgraph Run["🚀 Run"]
        R1["4. npm start"]
        R2["5. Check /health"]
    end

    subgraph Use["🎯 Use"]
        U1["6. Call bridge__execute"]
        U2["7. Enable/disable servers"]
    end

    S1 --> S2
    S2 --> S3
    S3 --> R1
    R1 --> R2
    R2 --> U1
    U1 --> U2

    style Setup fill:#1a1a2e,stroke:#e94560,color:#fff
    style Run fill:#16213e,stroke:#0f3460,color:#fff
    style Use fill:#0f3460,stroke:#533483,color:#fff
    style S1 fill:#533483,stroke:#fff,color:#fff
    style S2 fill:#533483,stroke:#fff,color:#fff
    style S3 fill:#533483,stroke:#fff,color:#fff
    style R1 fill:#533483,stroke:#fff,color:#fff
    style R2 fill:#533483,stroke:#fff,color:#fff
    style U1 fill:#e94560,stroke:#fff,color:#fff
    style U2 fill:#e94560,stroke:#fff,color:#fff

1. Install dependencies

npm install

2. Create your config

cp config/default.example.json config/default.json

Edit config/default.json and replace placeholders with your real values.

3. Start the gateway

npm start

4. Check health

http://127.0.0.1:8787/health

5. Use bridge__execute

Call bridge__execute via your MCP client to interact with any child server.

💻 CLI usage

graph TB
    subgraph Commands["💻 CLI Commands"]
        direction TB
        C1["npm start<br/><i>Default shortcut</i>"]
        C2["npm run ui<br/><i>Interactive launcher</i>"]
        C3["node src/index.js<br/><i>Manual start</i>"]
    end

    subgraph Options["⚙️ Options"]
        direction TB
        O1["--config<br/><i>Path to JSON config</i>"]
        O2["--only<br/><i>Allowlist server names</i>"]
        O3["--host<br/><i>Bind host</i>"]
        O4["--port<br/><i>Bind port</i>"]
        O5["--token<br/><i>Bearer token</i>"]
        O6["--stdio<br/><i>stdio mode</i>"]
    end

    Commands --> Options

    style Commands fill:#1a1a2e,stroke:#e94560,color:#fff
    style Options fill:#16213e,stroke:#0f3460,color:#fff
    style C1 fill:#533483,stroke:#fff,color:#fff
    style C2 fill:#533483,stroke:#fff,color:#fff
    style C3 fill:#533483,stroke:#fff,color:#fff
    style O1 fill:#e94560,stroke:#fff,color:#fff
    style O2 fill:#e94560,stroke:#fff,color:#fff
    style O3 fill:#e94560,stroke:#fff,color:#fff
    style O4 fill:#e94560,stroke:#fff,color:#fff
    style O5 fill:#e94560,stroke:#fff,color:#fff
    style O6 fill:#e94560,stroke:#fff,color:#fff

Default shortcut

npm start

Interactive launcher

npm run ui

Manual examples

node src/index.js --config config/default.json
node src/index.js --config config/default.json --only vision-generator,web-curl
node src/index.js --config config/default.json --host 127.0.0.1 --port 8787
node src/index.js --config config/default.json --token SECRET123

Supported options

Option	Description
`--config`	Path to the JSON config
`--only`	Comma-separated allowlist of server names
`--host`	Host to bind the HTTP server
`--port`	Port to bind the HTTP server
`--token`	Optional bearer token for `/mcp`
`--stdio`	Run as stdio MCP server (no HTTP)

🧾 Configuration format

graph TB
    subgraph Config["📁 config/default.json"]
        direction TB
        C1["mcpServers"]
    end

    subgraph Server["👶 Child Server"]
        direction TB
        S1["command: node"]
        S2["args: path/to/server.js"]
        S3["env: API_KEY=value"]
        S4["cwd: /optional/path"]
        S5["disabled: true/false"]
        S6["timeout: 60 seconds"]
        S7["disabledTools: [...]"]
    end

    C1 --> Server

    style Config fill:#1a1a2e,stroke:#e94560,color:#fff
    style Server fill:#16213e,stroke:#0f3460,color:#fff
    style C1 fill:#e94560,stroke:#fff,color:#fff
    style S1 fill:#533483,stroke:#fff,color:#fff
    style S2 fill:#533483,stroke:#fff,color:#fff
    style S3 fill:#533483,stroke:#fff,color:#fff
    style S4 fill:#533483,stroke:#fff,color:#fff
    style S5 fill:#533483,stroke:#fff,color:#fff
    style S6 fill:#533483,stroke:#fff,color:#fff
    style S7 fill:#533483,stroke:#fff,color:#fff

Supported fields

Field	Meaning
`command`	Executable to run
`args`	Command arguments
`env`	Environment variables for that child process
`cwd`	Optional working directory
`disabled`	If `true`, the bridge skips that server
`timeout`	Per-server startup timeout in seconds (default 60)
`disabledTools`	Array of tool names to hide from the exposed list

🌐 Endpoints

graph TB
    subgraph Endpoints["🌐 HTTP Endpoints"]
        direction TB
        E1["GET /health<br/><i>Status & tool list</i>"]
        E2["POST /mcp<br/><i>Primary MCP endpoint</i>"]
        E3["GET /mcp<br/><i>Session-based flows</i>"]
        E4["DELETE /mcp<br/><i>Close session</i>"]
    end

    subgraph Auth["🔐 Authentication"]
        A1["Bearer Token<br/><i>Optional</i>"]
    end

    E2 --> A1
    E3 --> A1
    E4 --> A1

    style Endpoints fill:#1a1a2e,stroke:#e94560,color:#fff
    style Auth fill:#16213e,stroke:#0f3460,color:#fff
    style E1 fill:#533483,stroke:#fff,color:#fff
    style E2 fill:#e94560,stroke:#fff,color:#fff
    style E3 fill:#533483,stroke:#fff,color:#fff
    style E4 fill:#533483,stroke:#fff,color:#fff
    style A1 fill:#0f3460,stroke:#fff,color:#fff

`GET /health`

Returns a status summary with loaded servers, skipped servers, and tool list.

`POST /mcp`

Primary MCP Streamable HTTP endpoint. Exposes the merged tool list (child servers + bridge meta tools).

`GET /mcp`

Used for session-based MCP flows.

`DELETE /mcp`

Closes an active MCP session.

🔐 Security notes

graph TB
    subgraph Security["🔐 Security Considerations"]
        direction TB
        S1["Token Protection"]
        S2["Runtime Write Warning"]
        S3["Best Practices"]
    end

    subgraph Token["🔑 Token"]
        T1["--token SECRET123"]
        T2["Authorization: Bearer SECRET123"]
    end

    subgraph Warning["⚠️ Config Mutation"]
        W1["bridge__enable/disable_server<br/>mutate config on disk"]
    end

    subgraph Practices["✅ Best Practices"]
        P1["Keep config in user-only dir"]
        P2["Don't symlink to public location"]
        P3["Treat as privileged in multi-tenant"]
    end

    S1 --> Token
    S2 --> Warning
    S3 --> Practices

    style Security fill:#1a1a2e,stroke:#e94560,color:#fff
    style Token fill:#16213e,stroke:#0f3460,color:#fff
    style Warning fill:#e94560,stroke:#fff,color:#fff
    style Practices fill:#0f3460,stroke:#533483,color:#fff
    style T1 fill:#533483,stroke:#fff,color:#fff
    style T2 fill:#533483,stroke:#fff,color:#fff
    style W1 fill:#fff,stroke:#e94560,color:#000
    style P1 fill:#fff,stroke:#533483,color:#000
    style P2 fill:#fff,stroke:#533483,color:#000
    style P3 fill:#fff,stroke:#533483,color:#000

Token protection

node src/index.js --config config/default.json --token SECRET123

Clients need: Authorization: Bearer SECRET123

⚠️ Runtime write warning

bridge__disable_server and bridge__enable_server mutate your config file on disk. Consider:

🔒 Keep config in user-only directory
🚫 Don't symlink to public location
🛡️ Treat as privileged in multi-tenant setups

🛠️ Troubleshooting

graph TB
    subgraph Issues["❌ Common Issues"]
        direction TB
        I1["bridge__execute returns 'Unknown tool'"]
        I2["bridge__disable_server reports 'not found'"]
        I3["Child server fails to start"]
        I4["Config changes not taking effect"]
    end

    subgraph Solutions["✅ Solutions"]
        direction TB
        S1["Check bridge__list_servers<br/>Wait 1-2 seconds after enable"]
        S2["Server name must match exactly<br/>Use bridge__list_servers"]
        S3["Check command path<br/>Check env vars<br/>Check /health endpoint"]
        S4["Wait 500ms debounce<br/>Call bridge__list_servers"]
    end

    I1 --> S1
    I2 --> S2
    I3 --> S3
    I4 --> S4

    style Issues fill:#e94560,stroke:#fff,color:#fff
    style Solutions fill:#0f3460,stroke:#533483,color:#fff
    style I1 fill:#fff,stroke:#e94560,color:#000
    style I2 fill:#fff,stroke:#e94560,color:#000
    style I3 fill:#fff,stroke:#e94560,color:#000
    style I4 fill:#fff,stroke:#e94560,color:#000
    style S1 fill:#fff,stroke:#533483,color:#000
    style S2 fill:#fff,stroke:#533483,color:#000
    style S3 fill:#fff,stroke:#533483,color:#000
    style S4 fill:#fff,stroke:#533483,color:#000

🧠 Design principles

graph TB
    subgraph Principles["🧠 Design Principles"]
        direction LR
        P1["1️⃣ Agent-Commander<br/>Bridge = Agent<br/>Client = Commander"]
        P2["2️⃣ 1:1 Response<br/>No transformation<br/>Raw output"]
        P3["3️⃣ Standard Config<br/>Reuse mcpServers<br/>No custom schema"]
        P4["4️⃣ Persist Changes<br/>Config = Source of Truth<br/>Atomic writes"]
        P5["5️⃣ Stay Thin<br/>Route & Aggregate<br/>Not a platform"]
    end

    P1 --- P2
    P2 --- P3
    P3 --- P4
    P4 --- P5

    style Principles fill:#0f3460,stroke:#533483,color:#fff
    style P1 fill:#1a1a2e,stroke:#e94560,color:#fff
    style P2 fill:#1a1a2e,stroke:#e94560,color:#fff
    style P3 fill:#1a1a2e,stroke:#e94560,color:#fff
    style P4 fill:#1a1a2e,stroke:#e94560,color:#fff
    style P5 fill:#1a1a2e,stroke:#e94560,color:#fff

1. Agent-Commander pattern

The bridge is the agent that manages all child server sessions. The client is the commander that sends instructions through bridge__execute. This decouples the client from individual server tool lists.

2. 1:1 Response

bridge__execute returns the response exactly as-is from the child server. No data transformation, no format changes.

3. Standard Config

Reuse mcpServers instead of forcing a custom config system.

4. Persist Changes

When you toggle a server, the change is written to the config file. The file is the source of truth.

5. Stay Thin

The bridge should route, aggregate, expose, and let you toggle. It should not become a full platform.

🗺️ Roadmap ideas

📜 Richer structured logging
🔑 Better auth defaults
🗂️ Config profiles for different tool sets
🌐 Named tunnel support for stable URLs
📊 Optional metrics or request tracing
⏱️ Per-tool rate limiting
🪪 Audit log for meta-tool invocations

✅ Summary

mindmap
  root((MCP Agent Bridge))
    🚀 Core Features
      bridge__execute
        1:1 response
        No restart needed
      Runtime Control
        Enable/disable servers
        Persist to config
      Hot Reload
        fs.watch
        ~500ms debounce
    🎯 Best For
      Local Development
      Personal Automation
      Remote MCP Experiments
      On-demand Server Control
    🧠 Architecture
      Agent-Commander Pattern
      Single Endpoint
      Child Server Management

MCP Agent Bridge is a practical agent gateway that turns multiple local MCP servers into one clean remote MCP endpoint — with runtime control, persistent toggling, and the powerful bridge__execute tool.

Best suited for:

🛠️ Local development
🤖 Personal automation stacks
🧪 Remote MCP experiments
🪶 Lightweight gateway scenarios
🎛️ On-demand server control without restarts

📄 License

Not specified yet.

Recommended Servers

playwright-mcp

A Model Context Protocol server that enables LLMs to interact with web pages through structured accessibility snapshots without requiring vision models or screenshots.

Official

Featured

TypeScript

Magic Component Platform (MCP)

An AI-powered tool that generates modern UI components from natural language descriptions, integrating with popular IDEs to streamline UI development workflow.

Audiense Insights MCP Server

Enables interaction with Audiense Insights accounts via the Model Context Protocol, facilitating the extraction and analysis of marketing insights and audience data including demographics, behavior, and influencer engagement.

VeyraX MCP

Single MCP tool to connect all your favorite tools: Gmail, Calendar and 40 more.

Official

Featured

Local

graphlit-mcp-server

The Model Context Protocol (MCP) Server enables integration between MCP clients and the Graphlit service. Ingest anything from Slack to Gmail to podcast feeds, in addition to web crawling, into a Graphlit project - and then retrieve relevant contents from the MCP client.

Official

Featured

TypeScript

Kagi MCP Server

An MCP server that integrates Kagi search capabilities with Claude AI, enabling Claude to perform real-time web searches when answering questions that require up-to-date information.

Official

Featured

Python

E2B

Using MCP to run code via e2b.

Official

Featured

Neon Database

MCP server for interacting with Neon Management API and databases

Official

Featured

Qdrant Server

This repository is an example of how to create a MCP server for Qdrant, a vector search engine.

Official

Featured

Exa Search

A Model Context Protocol (MCP) server lets AI assistants like Claude use the Exa AI Search API for web searches. This setup allows AI models to get real-time web information in a safe and controlled way.

Official

Featured

MCP Agent Bridge

README

MCP Agent Bridge

✨ What's new in v0.3.0

📖 Table of contents

🌍 Overview

🧩 Why this project exists

🏗️ Architecture

The Agent-Commander Pattern

Key idea

Request flow

Enable/Disable flow

🛰️ Bridge meta tools

bridge__execute 🚀

bridge__list_server_tools 🔍

bridge__list_servers 🛰️

bridge__disable_server 🔒

bridge__enable_server 🔓

🏷️ Tool naming strategy

Why this matters

💡 Examples

Enable a server and use it immediately

Explore a server's tools

Toggle servers dynamically

📁 Project structure

Important files

⚡ Quick start

1. Install dependencies

2. Create your config

3. Start the gateway

4. Check health

5. Use bridge__execute

💻 CLI usage

Default shortcut

Interactive launcher

Manual examples

Supported options

🧾 Configuration format

Supported fields

🌐 Endpoints

GET /health

POST /mcp

GET /mcp

DELETE /mcp

🔐 Security notes

Token protection

⚠️ Runtime write warning

🛠️ Troubleshooting

🧠 Design principles

1. Agent-Commander pattern

2. 1:1 Response

3. Standard Config

4. Persist Changes

5. Stay Thin

🗺️ Roadmap ideas

✅ Summary

📄 License

Recommended Servers

`bridge__execute` 🚀

`bridge__list_server_tools` 🔍

`bridge__list_servers` 🛰️

`bridge__disable_server` 🔒

`bridge__enable_server` 🔓

`GET /health`

`POST /mcp`

`GET /mcp`

`DELETE /mcp`