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"]
    }
  }
}

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}
217```
218
219## How It Works
220
221```
222┌──────────────────────────────────────────────────────────────┐
223│  zot agent                                                    │
224│                                                               │
225│  ┌──────────┐    tool_call    ┌──────────────┐               │
226│  │   LLM    │───────────────▶│  mcp-bridge  │               │
227│  │          │◀───────────────│  (extension) │               │
228│  └──────────┘    tool_result └──────┬───────┘               │
229│                                      │                        │
230│                           ┌──────────┼──────────┐            │
231│                           ▼          ▼          ▼            │
232│                    ┌──────────┐ ┌──────────┐ ┌──────────┐   │
233│                    │   MCP    │ │   MCP    │ │   MCP    │   │
234│                    │ server 1 │ │ server 2 │ │ server 3 │   │
235│                    │ (stdio)  │ │ (stdio)  │ │ (stdio)  │   │
236│                    └──────────┘ └──────────┘ └──────────┘   │
237└──────────────────────────────────────────────────────────────┘
238```
239
2401. **Startup**: mcp-bridge reads config and registers tools from `mcp-tools-cache.json`
2412. **Background refresh**: starts configured MCP servers, calls `tools/list`, and updates the cache when definitions change
2423. **Reload**: if the cache changed, run `/reload-ext` once so zot rebuilds the tool registry with the new definitions
2434. **Naming**: tools appear as `mcp__<server>__<tool>` (e.g., `mcp__filesystem__read_file`)
2445. **Idle timeout**: servers not used for 5 minutes are automatically stopped
2456. **Auto-respawn**: calling a tool on a stopped server wakes it up
2467. **Routing**: tool calls are forwarded to the appropriate MCP server
247
248## Slash Commands
249
250| Command | Description |
251|---|---|
252| `/mcp` | Show status of all configured servers |
253| `/mcp help` | Show available MCP commands |
254| `/mcp <name>` | Show detailed status for one server |
255| `/mcp start <name>` | Manually start a server |
256| `/mcp stop <name>` | Manually stop a server |
257| `/mcp restart` | Restart all servers |
258| `/mcp start all` | Manually start all servers |
259| `/mcp stop all` | Manually stop all servers |
260| `/mcp setup templates` | Show available setup templates |
261| `/mcp setup add <template> [--global|--project] [--name <server-name>]` | Add a server from a template |
262
263## Tool Naming
264
265Tools are namespaced to avoid collisions with zot's built-in tools:
266
267```
268mcp__<server>__<tool>
269```
270
271Examples:
272- `mcp__filesystem__read_file`
273- `mcp__filesystem__write_file`
274- `mcp__sqlite__query`
275- `mcp__context7__resolve-library-id`
276
277Server and tool names are sanitized (non-alphanumeric characters become `_`).
278
279## Smart Lazy Loading
280
281The bridge uses a "smart lazy" strategy:
282
2831. **On startup**: cached tool definitions are registered without blocking zot startup
2842. **In the background**: servers start long enough to refresh the tool cache
2853. **During use**: servers stay running for fast tool calls
2864. **After 5 min idle**: unused servers are automatically stopped (saves memory/CPU)
2875. **On next tool call**: the server is respawned automatically (~1-3s delay)
288
289This gives you:
290- Cached tools visible to the LLM immediately
291- Fast tool calls when actively working
292- Memory freed when not using MCP tools
293- One manual `/reload-ext` only when tool definitions change
294
295## Troubleshooting
296
297**Check server status:**
298```
299/mcp
300```
301
302**View extension logs:**
303```bash
304zot ext logs mcp -f
305```
306
307**Common issues:**
308
309- **Server fails to start**: check that `command` exists in your PATH, or use absolute path
310- **Tool not found**: run `/mcp` to see if the server started successfully
311- **Slow first call**: server is respawning after idle timeout (normal)
312
313## Limitations
314
315- **No OAuth flow** — authentication requires manual token configuration in headers
316- **No resources/prompts** — only tools are bridged (MCP resources and prompts coming later)
317- **No automatic config hot reload** — run `/reload-ext` after setup/config changes
318
319## Development
320
321```bash
322# Build
323cd examples/extensions/mcp-bridge
324go build -o mcp-bridge .
325
326# Test
327go test ./...
328go vet ./...
329
330# Run without installing (for one zot session)
331zot --ext .
332
333# View logs
334zot ext logs mcp -f
335```
336
337## License
338
339MIT
340
341## Testing
342
343```bash
344go test ./...
345go vet ./...
346go build -o /tmp/mcp-bridge .
347```
348
349Tested MCP servers:
350
351| Server | Transport | Result |
352|---|---|---|
353| `@modelcontextprotocol/server-filesystem` | stdio | 14 tools registered; file operations and MCP errors handled correctly |
354| grep.app `https://mcp.grep.app/` | streamable-http | `searchGitHub` registered and successfully searched public GitHub code |
355
356Note: grep.app uses the root endpoint `/`. Streamable HTTP protocol headers are handled automatically by the bridge and should not be written to `mcp.json`.
357
358## What the paired phone sees
359
360Build 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