README.md Raw History Folder

mcp-bridge

Connect zot to MCP (Model Context Protocol) servers.

This extension reads MCP server configurations from standard locations (same format as Claude Desktop, Cursor, Cline, etc.) and bridges their tools into zot so the LLM can call them directly.

Features

Standard config format — same JSON as Claude Desktop, Cursor, Cline
On-demand tool discovery — only mcp__search_tools is advertised initially; matching MCP schemas load when needed instead of bloating every model request
Smart lazy loading — cached definitions register as deferred tools at startup, servers wake for refresh or tool calls, then auto-sleep after idle time
Auto-respawn — calling a loaded tool on a sleeping server wakes it up automatically
Multi-transport — stdio, streamable-http, and SSE transports
Multi-server — connect to any number of MCP servers simultaneously
Tool namespacing — tools appear as mcp__<server>__<tool> to avoid collisions
Tool annotations — read-only, destructive, idempotent hints surfaced to LLM
Configurable timeouts — per-server connect, request, and idle timeouts
Custom headers — auth tokens and other headers for HTTP servers
Slash commands — /mcp to check status, start/stop/restart servers
Better error messages — context-aware errors with actionable suggestions

Quick Start

Build the extension:

cd examples/extensions/mcp-bridge
go build -o mcp-bridge .

Create a project config file:

mkdir -p .zot
cat > .zot/mcp.json << 'EOF'
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "."]
    },
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp@latest"]
    }
  }
}
EOF

Install the extension:
```
zot ext install .
```
Restart zot. On first run the extension refreshes its tool cache in the background. When zot shows MCP tool cache changed, run /reload-ext once. Future launches register the cached MCP tools immediately as deferred definitions.

The model initially sees one small loader tool, mcp__search_tools. It searches cached MCP tool names and descriptions locally, activates up to eight relevant definitions by default, and then calls the selected MCP tool normally. This keeps large MCP installations compatible with providers that limit request or tool-schema size.

Phone pairing with Build Remote Agent

Build Remote Agent is an optional, third-party integration that lets a paired phone observe terminal sessions and veto actions. It is an independent Linespotting AB product and is not affiliated with xAI or SpaceX.

Install the agent

Pin release v0.6.0 and verify the binary against the checksum listed here. The release's own SHA256SUMS file does not currently match five of its six binary assets, so do not use that file as the trust source. These checksums were verified directly against the release assets on 2026-08-24:

62673a6856342a87d4a2a659bc1de92200aa19a5b60d88d252254940820f0b7f  gbr-agent-darwin-amd64
7baa1a8e214cd71b60e3f2b5063713e00ff740939749c3cab3d702784a1432f8  gbr-agent-darwin-arm64
fb54724367882497f2e8e05e40ecdeb4be29e008e6c865fc5c426cf464e6ad6e  gbr-agent-linux-amd64
9e9d7ca45bb0c4ded9d04226136013e9b64ae30f16bcf03069d35e9c38171cb9  gbr-agent-linux-arm64
40355b2be6cd68f3be68f2a06dfd30307ec1a60f16f87f1d6174012b35aa4a49  gbr-agent-windows-amd64.exe
8fb9efcbc7e2ac91c11964944bf0f45e31bb23f4356d9dcb4b305d7cb9b0fe8c  gbr-agent-windows-arm64.exe

This macOS Apple Silicon example downloads, verifies, and installs the binary. Change both ASSET and SHA for another platform.

VER=v0.6.0
ASSET=gbr-agent-darwin-arm64
SHA=7baa1a8e214cd71b60e3f2b5063713e00ff740939749c3cab3d702784a1432f8
BASE="https://github.com/LinespottingOrg/GrokBuildRemote-Agents/releases/download/$VER"
curl -fsSL -o "$ASSET" "$BASE/$ASSET"
if command -v sha256sum >/dev/null 2>&1; then
  printf '%s  %s\n' "$SHA" "$ASSET" | sha256sum -c -
else
  printf '%s  %s\n' "$SHA" "$ASSET" | shasum -a 256 -c -
fi
mkdir -p "$HOME/.local/bin"
install -m 0755 "$ASSET" "$HOME/.local/bin/gbr-agent"
export PATH="$HOME/.local/bin:$PATH"
gbr-agent version  # must report v0.6.0
gbr-agent pair
gbr-agent run

Keep gbr-agent run running. Its Bot API should only be available over loopback:

curl -sS http://127.0.0.1:8788/health
curl -sS http://127.0.0.1:8788/v1/sessions

Install the MCP server

The MCP server requires Node.js 20 or newer. Pin its source instead of cloning the mutable default branch:

git clone --branch v0.6.0 --depth 1 https://github.com/LinespottingOrg/GrokBuildRemote-Agents.git
cd GrokBuildRemote-Agents/mcp/gbr-mcp
npm install --ignore-scripts
MCP_PATH="$(pwd)/bin/gbr-mcp.js"
node "$MCP_PATH" --diagnose

The v0.6.0 source does not include a package lock, so its npm dependency resolution is not fully reproducible. Review the package manifest and resolved dependency tree before use. Put the absolute value of MCP_PATH in the configuration below. Never put mailbox keys in mcp.json.

Configuration

Config files are loaded from two locations (project overrides global per-server):

Location	Scope
`$ZOT_HOME/mcp.json`	Global (`$XDG_STATE_HOME/zot/mcp.json` when `XDG_STATE_HOME` is set)
`.zot/mcp.json`	Project-level (in your project root)

Config Format

Standard MCP config — same as Claude Desktop, with zot-specific extensions:

{
  "mcpServers": {
    // ── Stdio transport (local subprocess) ───────────────────────────────────
    "filesystem": {
      "command": "npx",                    // executable to spawn
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
      "env": {                             // extra environment variables
        "NODE_ENV": "production"
      },
      "connectTimeout": 30,                // connection timeout (seconds)
      "requestTimeout": 60,                // per-request timeout (seconds)
      "idleTimeout": 300                   // idle timeout before stopping (seconds)
    },

    // Build Remote Agent (gbr/1). Pair with `gbr-agent pair`, then keep
    // `gbr-agent run` running. Use an absolute path to the pinned MCP checkout.
    "gbr": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/GrokBuildRemote-Agents/mcp/gbr-mcp/bin/gbr-mcp.js"]
    },

    // ── Streamable HTTP transport (modern HTTP) ─────────────────────────────
    "supabase": {
      "transport": "streamable-http",
      "url": "https://mcp.supabase.com/mcp",
      "headers": {                         // custom HTTP headers
        "Authorization": "Bearer YOUR_TOKEN"
      }
    },

    // ── SSE transport (legacy HTTP) ─────────────────────────────────────────
    "legacy-server": {
      "transport": "sse",
      "url": "https://example.com/sse"
    }
  }
}

Configuration Options

Field	Type	Default	Description
`command`	string	—	Executable to spawn (stdio only)
`args`	string[]	[]	Arguments for the command
`env`	object	—	Extra environment variables
`transport`	string	"stdio"	Transport: "stdio", "streamable-http", or "sse"
`url`	string	—	Server URL (HTTP transports only)
`headers`	object	—	Custom HTTP headers (HTTP transports only)
`connectTimeout`	number	30	Connection timeout in seconds
`requestTimeout`	number	60	Per-request timeout in seconds
`idleTimeout`	number	300	Idle timeout before stopping in seconds

Example: Multiple Servers

{
  "mcpServers": {
    // Filesystem access (stdio)
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/projects"]
    },

    // Grep.app - Search GitHub (streamable-http)
    "grep": {
      "transport": "streamable-http",
      "url": "https://mcp.grep.app/"
    },

    // Database queries (stdio)
    "sqlite": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-sqlite", "test.db"]
    },

    // Documentation lookup (stdio)
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp@latest"]
    },

    // You.com web search (streamable-http, keyless)
    "you": {
      "transport": "streamable-http",
      "url": "https://api.you.com/mcp?profile=free"
    }
  }
}

You.com template

/mcp setup add you registers the keyless You.com MCP profile (you-search). It needs no account or API key. To use the authenticated server and its additional tools, edit $ZOT_HOME/mcp.json after adding the template:

{
  "mcpServers": {
    "you": {
      "transport": "streamable-http",
      "url": "https://api.you.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_YDC_API_KEY"
      }
    }
  }
}

The authenticated endpoint does not expose you-finance by default. Request it explicitly with the ?tools= URL parameter or the X-Allowed-Tools header.

How It Works

┌──────────────────────────────────────────────────────────────┐
│  zot agent                                                    │
│                                                               │
│  ┌──────────┐    tool_call    ┌──────────────┐               │
│  │   LLM    │───────────────▶│  mcp-bridge  │               │
│  │          │◀───────────────│  (extension) │               │
│  └──────────┘    tool_result └──────┬───────┘               │
│                                      │                        │
│                           ┌──────────┼──────────┐            │
│                           ▼          ▼          ▼            │
│                    ┌──────────┐ ┌──────────┐ ┌──────────┐   │
│                    │   MCP    │ │   MCP    │ │   MCP    │   │
│                    │ server 1 │ │ server 2 │ │ server 3 │   │
│                    │ (stdio)  │ │ (stdio)  │ │ (stdio)  │   │
│                    └──────────┘ └──────────┘ └──────────┘   │
└──────────────────────────────────────────────────────────────┘

Startup: mcp-bridge reads config and registers tools from mcp-tools-cache.json
Background refresh: starts configured MCP servers, calls tools/list, and updates the cache when definitions change
Reload: if the cache changed, run /reload-ext once so zot rebuilds the tool registry with the new definitions
Naming: tools appear as mcp__<server>__<tool> (e.g., mcp__filesystem__read_file)
Idle timeout: servers not used for 5 minutes are automatically stopped
Auto-respawn: calling a tool on a stopped server wakes it up
Routing: tool calls are forwarded to the appropriate MCP server

Slash Commands

Command	Description
`/mcp`	Show status of all configured servers
`/mcp help`	Show available MCP commands
`/mcp <name>`	Show detailed status for one server
`/mcp start <name>`	Manually start a server
`/mcp stop <name>`	Manually stop a server
`/mcp restart`	Restart all servers
`/mcp start all`	Manually start all servers
`/mcp stop all`	Manually stop all servers
`/mcp setup templates`	Show available setup templates
`/mcp setup add [--global	--project] [--name ]`

Tool Naming

Tools are namespaced to avoid collisions with zot's built-in tools:

mcp__<server>__<tool>

Examples:

mcp__filesystem__read_file
mcp__filesystem__write_file
mcp__sqlite__query
mcp__context7__resolve-library-id

Server and tool names are sanitized (non-alphanumeric characters become _).

Smart Lazy Loading

The bridge uses a "smart lazy" strategy:

On startup: cached tool definitions are registered without blocking zot startup
In the background: servers start long enough to refresh the tool cache
During use: servers stay running for fast tool calls
After 5 min idle: unused servers are automatically stopped (saves memory/CPU)
On next tool call: the server is respawned automatically (~1-3s delay)

This gives you:

Cached tools visible to the LLM immediately
Fast tool calls when actively working
Memory freed when not using MCP tools
One manual /reload-ext only when tool definitions change

Troubleshooting

Check server status:

/mcp

View extension logs:

zot ext logs mcp -f

Common issues:

Server fails to start: check that command exists in your PATH, or use absolute path
Tool not found: run /mcp to see if the server started successfully
Slow first call: server is respawning after idle timeout (normal)

Limitations

No OAuth flow — authentication requires manual token configuration in headers
No resources/prompts — only tools are bridged (MCP resources and prompts coming later)
No automatic config hot reload — run /reload-ext after setup/config changes

Development

# Build
cd examples/extensions/mcp-bridge
go build -o mcp-bridge .

# Test
go test ./...
go vet ./...

# Run without installing (for one zot session)
zot --ext .

# View logs
zot ext logs mcp -f

License

MIT

Testing

go test ./...
go vet ./...
go build -o /tmp/mcp-bridge .

Tested MCP servers:

Server	Transport	Result
`@modelcontextprotocol/server-filesystem`	stdio	14 tools registered; file operations and MCP errors handled correctly
grep.app `https://mcp.grep.app/`	streamable-http	`searchGitHub` registered and successfully searched public GitHub code

Note: grep.app uses the root endpoint /. Streamable HTTP protocol headers are handled automatically by the bridge and should not be written to mcp.json.

What the paired phone sees

Build Remote Agent exposes terminal windows on the machine. Its loopback :8788 endpoint is a Bot API that returns JSON, not an MCP endpoint or terminal transcript. See the third-party's current phone visibility documentation for details.

source

1# mcp-bridge
2
3Connect zot to [MCP (Model Context Protocol)](https://modelcontextprotocol.io) servers.
4
5This extension reads MCP server configurations from standard locations (same format as Claude Desktop, Cursor, Cline, etc.) and bridges their tools into zot so the LLM can call them directly.
6
7## Features
8
9- **Standard config format** — same JSON as Claude Desktop, Cursor, Cline
10- **On-demand tool discovery** — only `mcp__search_tools` is advertised initially; matching MCP schemas load when needed instead of bloating every model request
11- **Smart lazy loading** — cached definitions register as deferred tools at startup, servers wake for refresh or tool calls, then auto-sleep after idle time
12- **Auto-respawn** — calling a loaded tool on a sleeping server wakes it up automatically
13- **Multi-transport** — stdio, streamable-http, and SSE transports
14- **Multi-server** — connect to any number of MCP servers simultaneously
15- **Tool namespacing** — tools appear as `mcp__<server>__<tool>` to avoid collisions
16- **Tool annotations** — read-only, destructive, idempotent hints surfaced to LLM
17- **Configurable timeouts** — per-server connect, request, and idle timeouts
18- **Custom headers** — auth tokens and other headers for HTTP servers
19- **Slash commands** — `/mcp` to check status, start/stop/restart servers
20- **Better error messages** — context-aware errors with actionable suggestions
21
22## Quick Start
23
241. **Build the extension:**
25
26   ```bash
27   cd examples/extensions/mcp-bridge
28   go build -o mcp-bridge .
29   ```
30
312. **Create a project config file:**
32
33   ```bash
34   mkdir -p .zot
35   cat > .zot/mcp.json << 'EOF'
36   {
37     "mcpServers": {
38       "filesystem": {
39         "command": "npx",
40         "args": ["-y", "@modelcontextprotocol/server-filesystem", "."]
41       },
42       "context7": {
43         "command": "npx",
44         "args": ["-y", "@upstash/context7-mcp@latest"]
45       }
46     }
47   }
48   EOF
49   ```
50
513. **Install the extension:**
52
53   ```bash
54   zot ext install .
55   ```
56
574. **Restart zot.** On first run the extension refreshes its tool cache in the background. When zot shows `MCP tool cache changed`, run `/reload-ext` once. Future launches register the cached MCP tools immediately as deferred definitions.
58
59The model initially sees one small loader tool, `mcp__search_tools`. It searches cached MCP tool names and descriptions locally, activates up to eight relevant definitions by default, and then calls the selected MCP tool normally. This keeps large MCP installations compatible with providers that limit request or tool-schema size.
60
61### Phone pairing with Build Remote Agent
62
63[Build Remote Agent](https://grokbuildremote.com/) is an optional, third-party integration that lets a paired phone observe terminal sessions and veto actions. It is an independent Linespotting AB product and is not affiliated with xAI or SpaceX.
64
65#### Install the agent
66
67Pin release `v0.6.0` and verify the binary against the checksum listed here. The release's own `SHA256SUMS` file does not currently match five of its six binary assets, so do not use that file as the trust source. These checksums were verified directly against the release assets on 2026-08-24:
68
69```text
7062673a6856342a87d4a2a659bc1de92200aa19a5b60d88d252254940820f0b7f  gbr-agent-darwin-amd64
717baa1a8e214cd71b60e3f2b5063713e00ff740939749c3cab3d702784a1432f8  gbr-agent-darwin-arm64
72fb54724367882497f2e8e05e40ecdeb4be29e008e6c865fc5c426cf464e6ad6e  gbr-agent-linux-amd64
739e9d7ca45bb0c4ded9d04226136013e9b64ae30f16bcf03069d35e9c38171cb9  gbr-agent-linux-arm64
7440355b2be6cd68f3be68f2a06dfd30307ec1a60f16f87f1d6174012b35aa4a49  gbr-agent-windows-amd64.exe
758fb9efcbc7e2ac91c11964944bf0f45e31bb23f4356d9dcb4b305d7cb9b0fe8c  gbr-agent-windows-arm64.exe
76```
77
78This macOS Apple Silicon example downloads, verifies, and installs the binary. Change both `ASSET` and `SHA` for another platform.
79
80```bash
81VER=v0.6.0
82ASSET=gbr-agent-darwin-arm64
83SHA=7baa1a8e214cd71b60e3f2b5063713e00ff740939749c3cab3d702784a1432f8
84BASE="https://github.com/LinespottingOrg/GrokBuildRemote-Agents/releases/download/$VER"
85curl -fsSL -o "$ASSET" "$BASE/$ASSET"
86if command -v sha256sum >/dev/null 2>&1; then
87  printf '%s  %s\n' "$SHA" "$ASSET" | sha256sum -c -
88else
89  printf '%s  %s\n' "$SHA" "$ASSET" | shasum -a 256 -c -
90fi
91mkdir -p "$HOME/.local/bin"
92install -m 0755 "$ASSET" "$HOME/.local/bin/gbr-agent"
93export PATH="$HOME/.local/bin:$PATH"
94gbr-agent version  # must report v0.6.0
95gbr-agent pair
96gbr-agent run
97```
98
99Keep `gbr-agent run` running. Its Bot API should only be available over loopback:
100
101```bash
102curl -sS http://127.0.0.1:8788/health
103curl -sS http://127.0.0.1:8788/v1/sessions
104```
105
106#### Install the MCP server
107
108The MCP server requires Node.js 20 or newer. Pin its source instead of cloning the mutable default branch:
109
110```bash
111git clone --branch v0.6.0 --depth 1 https://github.com/LinespottingOrg/GrokBuildRemote-Agents.git
112cd GrokBuildRemote-Agents/mcp/gbr-mcp
113npm install --ignore-scripts
114MCP_PATH="$(pwd)/bin/gbr-mcp.js"
115node "$MCP_PATH" --diagnose
116```
117
118The `v0.6.0` source does not include a package lock, so its npm dependency resolution is not fully reproducible. Review the package manifest and resolved dependency tree before use. Put the absolute value of `MCP_PATH` in the configuration below. Never put mailbox keys in `mcp.json`.
119
120## Configuration
121
122Config files are loaded from two locations (project overrides global per-server):
123
124| Location | Scope |
125|---|---|
126| `$ZOT_HOME/mcp.json` | Global (`$XDG_STATE_HOME/zot/mcp.json` when `XDG_STATE_HOME` is set) |
127| `.zot/mcp.json` | Project-level (in your project root) |
128
129### Config Format
130
131Standard MCP config — same as Claude Desktop, with zot-specific extensions:
132
133```jsonc
134{
135  "mcpServers": {
136    // ── Stdio transport (local subprocess) ───────────────────────────────────
137    "filesystem": {
138      "command": "npx",                    // executable to spawn
139      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
140      "env": {                             // extra environment variables
141        "NODE_ENV": "production"
142      },
143      "connectTimeout": 30,                // connection timeout (seconds)
144      "requestTimeout": 60,                // per-request timeout (seconds)
145      "idleTimeout": 300                   // idle timeout before stopping (seconds)
146    },
147
148    // Build Remote Agent (gbr/1). Pair with `gbr-agent pair`, then keep
149    // `gbr-agent run` running. Use an absolute path to the pinned MCP checkout.
150    "gbr": {
151      "command": "node",
152      "args": ["/ABSOLUTE/PATH/GrokBuildRemote-Agents/mcp/gbr-mcp/bin/gbr-mcp.js"]
153    },
154
155    // ── Streamable HTTP transport (modern HTTP) ─────────────────────────────
156    "supabase": {
157      "transport": "streamable-http",
158      "url": "https://mcp.supabase.com/mcp",
159      "headers": {                         // custom HTTP headers
160        "Authorization": "Bearer YOUR_TOKEN"
161      }
162    },
163
164    // ── SSE transport (legacy HTTP) ─────────────────────────────────────────
165    "legacy-server": {
166      "transport": "sse",
167      "url": "https://example.com/sse"
168    }
169  }
170}
171```
172
173### Configuration Options
174
175| Field | Type | Default | Description |
176|---|---|---|---|
177| `command` | string | — | Executable to spawn (stdio only) |
178| `args` | string[] | [] | Arguments for the command |
179| `env` | object | — | Extra environment variables |
180| `transport` | string | "stdio" | Transport: "stdio", "streamable-http", or "sse" |
181| `url` | string | — | Server URL (HTTP transports only) |
182| `headers` | object | — | Custom HTTP headers (HTTP transports only) |
183| `connectTimeout` | number | 30 | Connection timeout in seconds |
184| `requestTimeout` | number | 60 | Per-request timeout in seconds |
185| `idleTimeout` | number | 300 | Idle timeout before stopping in seconds |
186
187### Example: Multiple Servers
188
189```jsonc
190{
191  "mcpServers": {
192    // Filesystem access (stdio)
193    "filesystem": {
194      "command": "npx",
195      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/projects"]
196    },
197
198    // Grep.app - Search GitHub (streamable-http)
199    "grep": {
200      "transport": "streamable-http",
201      "url": "https://mcp.grep.app/"
202    },
203
204    // Database queries (stdio)
205    "sqlite": {
206      "command": "npx",
207      "args": ["-y", "@modelcontextprotocol/server-sqlite", "test.db"]
208    },
209
210    // Documentation lookup (stdio)
211    "context7": {
212      "command": "npx",
213      "args": ["-y", "@upstash/context7-mcp@latest"]
214    },
215
216    // You.com web search (streamable-http, keyless)
217    "you": {
218      "transport": "streamable-http",
219      "url": "https://api.you.com/mcp?profile=free"
220    }
221  }
222}
223```
224
225### You.com template
226
227`/mcp setup add you` registers the keyless You.com MCP profile
228(`you-search`). It needs no account or API key. To use the authenticated
229server and its additional tools, edit `$ZOT_HOME/mcp.json` after adding
230the template:
231
232```jsonc
233{
234  "mcpServers": {
235    "you": {
236      "transport": "streamable-http",
237      "url": "https://api.you.com/mcp",
238      "headers": {
239        "Authorization": "Bearer YOUR_YDC_API_KEY"
240      }
241    }
242  }
243}
244```
245
246The authenticated endpoint does not expose `you-finance` by default. Request
247it explicitly with the `?tools=` URL parameter or the `X-Allowed-Tools` header.
248
249## How It Works
250
251```
252┌──────────────────────────────────────────────────────────────┐
253│  zot agent                                                    │
254│                                                               │
255│  ┌──────────┐    tool_call    ┌──────────────┐               │
256│  │   LLM    │───────────────▶│  mcp-bridge  │               │
257│  │          │◀───────────────│  (extension) │               │
258│  └──────────┘    tool_result └──────┬───────┘               │
259│                                      │                        │
260│                           ┌──────────┼──────────┐            │
261│                           ▼          ▼          ▼            │
262│                    ┌──────────┐ ┌──────────┐ ┌──────────┐   │
263│                    │   MCP    │ │   MCP    │ │   MCP    │   │
264│                    │ server 1 │ │ server 2 │ │ server 3 │   │
265│                    │ (stdio)  │ │ (stdio)  │ │ (stdio)  │   │
266│                    └──────────┘ └──────────┘ └──────────┘   │
267└──────────────────────────────────────────────────────────────┘
268```
269
2701. **Startup**: mcp-bridge reads config and registers tools from `mcp-tools-cache.json`
2712. **Background refresh**: starts configured MCP servers, calls `tools/list`, and updates the cache when definitions change
2723. **Reload**: if the cache changed, run `/reload-ext` once so zot rebuilds the tool registry with the new definitions
2734. **Naming**: tools appear as `mcp__<server>__<tool>` (e.g., `mcp__filesystem__read_file`)
2745. **Idle timeout**: servers not used for 5 minutes are automatically stopped
2756. **Auto-respawn**: calling a tool on a stopped server wakes it up
2767. **Routing**: tool calls are forwarded to the appropriate MCP server
277
278## Slash Commands
279
280| Command | Description |
281|---|---|
282| `/mcp` | Show status of all configured servers |
283| `/mcp help` | Show available MCP commands |
284| `/mcp <name>` | Show detailed status for one server |
285| `/mcp start <name>` | Manually start a server |
286| `/mcp stop <name>` | Manually stop a server |
287| `/mcp restart` | Restart all servers |
288| `/mcp start all` | Manually start all servers |
289| `/mcp stop all` | Manually stop all servers |
290| `/mcp setup templates` | Show available setup templates |
291| `/mcp setup add <template> [--global|--project] [--name <server-name>]` | Add a server from a template |
292
293## Tool Naming
294
295Tools are namespaced to avoid collisions with zot's built-in tools:
296
297```
298mcp__<server>__<tool>
299```
300
301Examples:
302- `mcp__filesystem__read_file`
303- `mcp__filesystem__write_file`
304- `mcp__sqlite__query`
305- `mcp__context7__resolve-library-id`
306
307Server and tool names are sanitized (non-alphanumeric characters become `_`).
308
309## Smart Lazy Loading
310
311The bridge uses a "smart lazy" strategy:
312
3131. **On startup**: cached tool definitions are registered without blocking zot startup
3142. **In the background**: servers start long enough to refresh the tool cache
3153. **During use**: servers stay running for fast tool calls
3164. **After 5 min idle**: unused servers are automatically stopped (saves memory/CPU)
3175. **On next tool call**: the server is respawned automatically (~1-3s delay)
318
319This gives you:
320- Cached tools visible to the LLM immediately
321- Fast tool calls when actively working
322- Memory freed when not using MCP tools
323- One manual `/reload-ext` only when tool definitions change
324
325## Troubleshooting
326
327**Check server status:**
328```
329/mcp
330```
331
332**View extension logs:**
333```bash
334zot ext logs mcp -f
335```
336
337**Common issues:**
338
339- **Server fails to start**: check that `command` exists in your PATH, or use absolute path
340- **Tool not found**: run `/mcp` to see if the server started successfully
341- **Slow first call**: server is respawning after idle timeout (normal)
342
343## Limitations
344
345- **No OAuth flow** — authentication requires manual token configuration in headers
346- **No resources/prompts** — only tools are bridged (MCP resources and prompts coming later)
347- **No automatic config hot reload** — run `/reload-ext` after setup/config changes
348
349## Development
350
351```bash
352# Build
353cd examples/extensions/mcp-bridge
354go build -o mcp-bridge .
355
356# Test
357go test ./...
358go vet ./...
359
360# Run without installing (for one zot session)
361zot --ext .
362
363# View logs
364zot ext logs mcp -f
365```
366
367## License
368
369MIT
370
371## Testing
372
373```bash
374go test ./...
375go vet ./...
376go build -o /tmp/mcp-bridge .
377```
378
379Tested MCP servers:
380
381| Server | Transport | Result |
382|---|---|---|
383| `@modelcontextprotocol/server-filesystem` | stdio | 14 tools registered; file operations and MCP errors handled correctly |
384| grep.app `https://mcp.grep.app/` | streamable-http | `searchGitHub` registered and successfully searched public GitHub code |
385
386Note: grep.app uses the root endpoint `/`. Streamable HTTP protocol headers are handled automatically by the bridge and should not be written to `mcp.json`.
387
388## What the paired phone sees
389
390Build Remote Agent exposes terminal windows on the machine. Its loopback `:8788` endpoint is a Bot API that returns JSON, not an MCP endpoint or terminal transcript. See the third-party's [current phone visibility documentation](https://github.com/LinespottingOrg/GrokBuildRemote-Agents/blob/main/docs/WHAT-THE-PHONE-SEES.md) for details.

README.md RawHistoryFolder