{ "server": "web-curl", "tool": "fetch_api", "args": { "url": "https://api.example.com/data", "method": "GET", "limit": 1000 } } ``` **Args:** | Field | Type | Required | Description | |---|---|---|---| | `server` | string | ✅ | Name of the MCP server (e.g. `"ssh-mcp"`, `"web-curl"`, `"playwright-extension"`) | | `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 | #### Batch mode Chain multiple tool calls in **one** request. Each operation runs sequentially against its target server. Use this for workflows like `navigate → snapshot → evaluate` that would otherwise need N round trips. ```json { "operations": [ { "server": "playwright-extension", "tool": "browser_navigate", "args": { "url": "https://example.com" } }, { "server": "playwright-extension", "tool": "browser_snapshot" }, { "server": "playwright-extension", "tool": "browser_evaluate", "args": { "function": "() => document.body.innerText" } } ], "stopOnError": true } ``` **Batch args:** | Field | Type | Required | Description | |---|---|---|---| | `operations` | array | ✅ | Ordered list of `{ server, tool, args }` to execute sequentially | | `stopOnError` | boolean | ❌ | If `true` (default), stop at the first failure. If `false`, attempt every operation and report per-op status | **Batch response:** ```json { "mode": "batch", "total": 3, "completed": 3, "stoppedOnError": false, "results": [ { "index": 0, "server": "playwright-extension", "tool": "browser_navigate", "ok": true, "result": {...} }, { "index": 1, "server": "playwright-extension", "tool": "browser_snapshot", "ok": true, "result": {...} }, { "index": 2, "server": "playwright-extension", "tool": "browser_evaluate", "ok": true, "result": {...} } ] } ``` **More single-mode examples:** ```json // List models from vision-generator { "server": "vision-generator", "tool": "list_models" } // 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" } } // 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. Use this to discover what tools and parameters a server supports before calling `bridge__execute`. **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. ### `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. ```mermaid 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 ```mermaid 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
Real config (gitignored)"] C2["default.example.json
Sanitized template"] C3["README.md
Setup guide"] end subgraph Src["📁 src"] direction TB S1["index.js
Main server, auth, watcher"] S2["config.js
CLI args, config loading"] S3["childServers.js
Lifecycle, tool map, health"] S4["router.js
5 meta tools"] S5["cli/
Launcher"] end subgraph Tools["📁 tools"] direction TB T1["cloudflared.exe
Tunnel helper"] 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 ```mermaid 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 ```bash npm install ``` ### 2. Create your config ```bash cp config/default.example.json config/default.json ``` Edit `config/default.json` and replace placeholders with your real values. ### 3. Start the gateway ```bash npm start ``` ### 4. Check health ```text 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 ```mermaid graph TB subgraph Commands["💻 CLI Commands"] direction TB C1["npm start
Default shortcut"] C2["npm run ui
Interactive launcher"] C3["node src/index.js
Manual start"] end subgraph Options["⚙️ Options"] direction TB O1["--config
Path to JSON config"] O2["--only
Allowlist server names"] O3["--host
Bind host"] O4["--port
Bind port"] O5["--token
Bearer token"] O6["--stdio
stdio mode"] 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 ```bash npm start ``` ### Interactive launcher ```bash npm run ui ``` ### Manual examples ```bash 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 ```mermaid graph TB subgraph Config["📁 config/default.json"] direction TB C1["mcpServers"] end

MCP Agent Bridge

Installation