mcp-agent-bridge
Exposes the local MCP server publicly through a Cloudflare Tunnel (cloudflared), providing a temporary public MCP endpoint that web agents can connect to.
Provides an alternative tunnel provider for exposing the local MCP server on a stable ngrok dev domain, configurable with an ngrok authtoken and domain.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
MCP Agent Bridge
把本机变成一个可通过 Cloudflare Tunnel 公网访问的 MCP 服务器,让网页端 Agent(ChatGPT、Claude、Cursor、自建 Web Agent 等)直接:
📁 读写你本机的文件(
files.allowedRoots决定范围,默认["*"]= 整机任意路径;也可只放行指定目录)⚡ 控制你的 PowerShell(默认 blocklist:任意命令可执行,删除/破坏性命令全链路拦截;可选 allowlist 白名单),并可通过 SSH 读取/操作远端主机
🧩 使用你本机的 Skill:
list_skills/read_skill让网页端模型直接读到本机SKILL.md并按其中的步骤干活🔧 调用你本机 Agent 的工具(桥接任意本地 MCP server,stdio / HTTP / SSE)
🧠 让本机的另一个 Agent(workbuddy / Claude Code / Cursor…)也连进来当"指挥方":它只用
delegate_task下指令(几乎不耗自己的 token),网页端 Agent 领活、干活、回报 —— 两边共享同一块任务板🌐 联网搜索:
web_search/fetch_page用你本机的网络位置去搜(默认 Bing,免 API Key)🖥️ 同时在本机监控台里实时看到:谁连进来了、调用了什么工具、读写/执行了什么、参数和结果
💬 本机 Agent 控制台(GUI):不含内置模型——一键生成"连接提示词"(给网页端)与"接入配置"(给本机 Agent),实时镜像活动流与任务板,并可手动调工具、审批
灵感来自 expose-files-mcp,在其安全模型上扩展了 PowerShell 深度控制、Agent 工具桥接、本机 Skill 读取、多 Agent 协作任务板、联网搜索、实时监控与审批门。
网页端 Agent (ChatGPT / Claude / 自建) 你(浏览器)
│ https://<random>.trycloudflare.com/mcp │ http://127.0.0.1:7822
│ Authorization: Bearer <token> │ http://127.0.0.1:7821
▼ ▼
Cloudflare Tunnel (cloudflared) Agent 控制台 (GUI) / 监控台
│ │
└──────────────┬───────────────────────────────┘
▼
┌─────────────────────────────────────────────┐
│ mcp-agent-bridge (本机 Node 进程) │
│ │
│ MCP Server (Streamable HTTP, 127.0.0.1) │
│ ├─ 文件工具 任意路径 list/read/write/... │
│ ├─ PowerShell run_powershell (blocklist) │
│ ├─ 本机 Skill list_skills / read_skill │
│ ├─ Agent 桥接 agent_call_tool ... │
│ ├─ 协作任务板 delegate_task / take_task │
│ └─ 联网搜索 web_search / fetch_page │
│ │ │ │
│ ▼ ▼ │
│ 本机文件系统 / SSH 主机 本机其他 MCP server│
│ (stdio/HTTP/SSE) │
│ │
│ GUI http://127.0.0.1:7822 (仅本机) │
│ 接入本机Agent · 连接提示词 · 任务板 · 审批 │
│ 监控台 http://127.0.0.1:7821 (仅本机) │
│ 实时活动流 · 会话 · 审计日志 · 配置 │
└─────────────────────────────────────────────┘快速开始
要求:Node.js ≥ 18.17;公网暴露需要 cloudflared(winget install Cloudflare.cloudflared)。
cd mcp-agent-bridge
npm install --registry=https://registry.npmmirror.com
node bin/mcp-agent-bridge.js --public
# 配置好 bridge.config.json 之后,日常启动就一条命令(或双击 start.cmd):
npm start
# 想固定域名(重启不变)?见下方「稳定域名(ngrok)」一节
# ngrok 已是默认 Provider;未配置 dev 域名时会自动回退到 cloudflared quick tunnel 并提示
# 想收窄文件范围(只放行指定目录)时:
node bin/mcp-agent-bridge.js --allowed-roots "C:\Users\Administrator\.workbuddy,E:\projects"
# 想收回权限时(例如只读):
node bin/mcp-agent-bridge.js --files read-only
# 想收紧为白名单模式时:
node bin/mcp-agent-bridge.js `
--root . `
--powershell `
--ps-mode allowlist `
--allowed-commands "Get-ChildItem,Get-Content,Get-Date,node,git"启动后控制台会打印:
── Server ────────────────────────────────────
Root C:\Users\Administrator\.workbuddy
Files read-write (sensitive patterns allowed) — whole machine (any path on this host + SSH targets)
PowerShell enabled — any command; deletion/destructive always blocked (blocklist mode)
Skills enabled (5 dirs: ...\.trae-cn\skills, ...\.claude\skills, ...)
Search enabled (engine: bing; web_search + fetch_page, no API key needed)
Handoff enabled — local agent (commander) ⇄ web agents (workers); 0 open / 0 task(s) in ...\logs\board.json
Tools 24 (get_status, list_files, read_file, ...)
── Tunnel (cloudflared) ──────────────────────
Public https://xxxx-yyyy.trycloudflare.com/mcp
Header Authorization: Bearer <token>
Token 9f2b1c... (自动生成,也可用 --auth-token 指定)
── Agent Console (GUI) ───────────────────────
URL http://127.0.0.1:7822
Mode connect-prompt console — no built-in model; the web agent is the brain
Local agent console → 🔌 接入本机 Agent for a ready-to-paste MCP client config
── Dashboard (monitor) ───────────────────────
URL http://127.0.0.1:7821把 Public URL + Token 填到你的网页端 Agent 即可;也可以打开 http://127.0.0.1:7822 点 「🔗 连接网页 Agent」,直接拿一段写好的连接提示词粘给网页端模型;想让本机另一个 Agent也连进来当指挥方,点 「🔌 接入本机 Agent」。http://127.0.0.1:7821 看监控。
Related MCP server: localmcpcoder
稳定域名(ngrok)
Cloudflare quick tunnel 的域名每次启动都随机变,且官方定位为测试用途(200 并发上限、不支持 SSE)。要长期固定地址就用 ngrok Provider(内置默认):每个 ngrok 账号自带 1 个永久 dev 域名,免费版即可,自动分配、不能自定义,但重启不变。
默认 Provider 是
ngrok,但它需要 dev 域名才有意义。没配置域名时--public不会报错,而是自动回退到 cloudflared quick tunnel,并在启动横幅前打印一行警告——所以第一次用之前,请先完成下面 1~3 步。
# 1) 安装(只需一次)
winget install ngrok.ngrok
# 1b) 必须升级一次:winget 里的版本很旧(3.3.x),ngrok 服务端要求 ≥ 3.28
ngrok update
# 2) 登记 authtoken(只需一次)—— token 在 https://dashboard.ngrok.com/get-started/your-authtoken
ngrok config add-authtoken <你的 authtoken>
# 3) 复制你的 dev 域名(形如 your-name.ngrok-free.dev)
# https://dashboard.ngrok.com/domains
# 4) 写进 bridge.config.json 后,启动只需一条命令
npm startbridge.config.json 的最小写法(该文件已在 .gitignore 中):
{
"public": {
"enabled": true,
"provider": "ngrok",
"authToken": "换成你自己的 64 位随机串",
"ngrok": { "domain": "your-name.ngrok-free.dev" }
}
}也可以临时用命令行覆盖(注意会留在命令历史里):
node bin/mcp-agent-bridge.js --public --provider ngrok `
--ngrok-domain your-name.ngrok-free.dev `
--ngrok-authtoken <你的 authtoken>想把 authtoken 也写进配置文件(而不是用全局 ngrok config)时,加一行 "ngrok": { "domain": "...", "authtoken": "..." } 即可。
关于 Bearer token 的两种用法:不写 authToken(推荐)时,每次启动都会重新生成一个 64 位随机 token,并打印在启动横幅的 Token 行,重启即作废旧 token;写死一个值则重启后保持不变,省去每次重新粘贴。bridge.config.json 已在 .gitignore 中,写死也不会进仓库。
两个 Provider 的区别:
ngrok(默认) | cloudflared | |
公网域名 | 固定,随账号长期保留 | 每次启动随机变 |
是否需要账号 | 需要(免费注册) | 不需要 |
限制 | 免费版最多 3 个在线端点 | quick tunnel 限 200 并发、不支持 SSE |
适合场景 | 长期挂给网页端 Agent | 临时试一下 |
启动成功后横幅会多一行 Stable yes (your ngrok dev domain),确认用的是固定域名。
ngrok 免费版会给浏览器式 GET 请求(含直接打开
/healthz)插入一个警告页(ERR_NGROK_6024)。MCP 客户端走的是POST /mcp,不受影响,已实测可正常握手;若要用浏览器调试,请带上ngrok-skip-browser-warning: 1请求头。
网页端 Agent 如何接入
客户端 | 接入方式 |
通用 MCP 客户端 | Streamable HTTP 端点 |
ChatGPT | Settings → Apps & Connectors → Developer mode → 添加 MCP Server(填 URL);token 走自定义 Header 或使用 OAuth 网关 |
Claude / Cursor 等 | 在 MCP 配置中填 URL,认证头 |
自建 Web Agent |
|
SDK 示例(Node):
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
const client = new Client({ name: "web-agent", version: "1.0.0" });
await client.connect(
new StreamableHTTPClientTransport(new URL("https://xxxx.trycloudflare.com/mcp"), {
requestInit: { headers: { Authorization: `Bearer ${TOKEN}` } },
}),
);
const { tools } = await client.listTools();
const res = await client.callTool({ name: "run_powershell", arguments: { command: "Get-Date" } });本机 Agent 接入(多一个"指挥方"客户端)
原来的模式不变:网页端 Agent 通过隧道连进来干活。新增加的是——你本机的另一个 Agent(workbuddy、Claude Code、Cursor、TRAE…)也连到同一个桥上,于是它和网页端 Agent 就能通过这个 MCP 沟通:
本机 Agent(指挥方,省 token)──delegate_task──▶ 共享任务板 ◀──take_task── 网页端 Agent(干活的)
▲ │
└──────── 通知/留言(update_task 自动触发)────┘关键点:两个客户端连的是同一个 bridge 进程,所以任务板是共享的(board.file,默认 ./logs/board.json,重启不丢)。注意本机 Agent 要用 HTTP 回环地址 http://127.0.0.1:8080/mcp 接入,不要用 stdio 另起一个进程——那样就变成两块板子了。隧道开不开都不影响本机接入。
怎么接
控制台右上角点 🔌 接入本机 Agent,会给你三样东西:
MCP 客户端配置(直接粘进本机 Agent 的 MCP 配置):
{ "mcpServers": { "mcp-agent-bridge": { "type": "http", "url": "http://127.0.0.1:8080/mcp", "headers": { "Authorization": "Bearer <你的token>" } } } }个别客户端要求
"type": "streamable-http",按客户端写法改一下即可。命令行方式(Claude Code 等):
claude mcp add --transport http mcp-agent-bridge http://127.0.0.1:8080/mcp --header "Authorization: Bearer <token>"一段说明(把这句发给本机 Agent,它会按"指挥方"的规矩干活)
指挥方的省 token 规矩
内置在 🔌 接入本机 Agent 的说明里,核心就四条:
只下指令、不干重活:
delegate_task({ instruction: "一句话说清目标", context: "可选、尽量短" }),写完就停不轮询:干活的 Agent 完成/失败/被阻塞时会自动发通知给指挥方,
read_messages({to:"local"})收即可;要等就wait_for_work({role:"local", timeoutSec:60})看进度用
get_tasks({status:"open"})——每行一个摘要,只有要细节才verbose:true大文件、长日志、整页网页都让干活的 Agent 去读,指挥方只收结论
干活的 Agent 侧的约定是:take_task 领活 → 用文件/PowerShell/搜索工具干活 → update_task({status:"done", result:"一句话结论"}) 汇报;信息不够就 send_message({to:"local"}) 提问、update_task({status:"blocked"}) 说明阻塞。
从控制台直接派活
控制台 → 📋 任务板 → 写一句指令 → 派活:等价于指挥方调用 delegate_task。谁派的、谁在干、干到哪一步(含最新 note / result)都在这个面板里,监控台首页也有一张任务板卡片。任务板 API:GET /api/board、POST /api/board/task、POST /api/board/message。
暴露给网页端 Agent 的工具
文件(范围由 files.allowedRoots 决定)
list_files read_file write_file delete_file move_path search_files file_info
默认 files.allowedRoots = ["*"]:整机任意路径都可读可写,传绝对路径即可(C:\Users\...、D:\...);想收窄就把它改成具体目录列表,rootDir 始终在范围内。
本机 Skill
list_skills — 列出本机全部 skill(扫描 skills.dirs 下含 SKILL.md 的目录),可按关键词过滤
read_skill — 按名字读取某个 skill 的 SKILL.md(或用 file 读 references/xxx.md 等附属文件),让网页端模型照它执行
协作任务板(本机指挥方 ⇄ 干活的 Agent)
delegate_task — 指挥方下指令(一句话),返回任务号,输出极短
take_task — 干活的 Agent 领取下一个任务(可按优先级/指定 id),拿到完整指令
update_task — 汇报进展/阻塞/完成(done/failed/blocked 会自动给指挥方发通知)
get_tasks — 一行一个任务摘要(verbose:true 才展开细节),指挥方省 token 就靠它
send_message / read_messages — 两边互相留言提问/回答,默认只读未读并标记已读
wait_for_work — 长轮询(最多 600s),有活/有留言才返回,避免双方空转轮询
联网搜索
web_search — 搜索并返回标题/链接/摘要(默认 Bing,免 API Key;可切 duckduckgo / tavily / brave)
fetch_page — 抓取某个页面并转成可读正文(mode: text|html|links;静态抓取,不执行 JS)
PowerShell
run_powershell — 双模式安全校验 + 超时(taskkill 整树击杀)+ 输出上限:
blocklist(默认):任意命令可执行(管道
|、重定向>、&&/;链都放行),但删除/破坏性命令在任何形式下都会被拦截——本体的 cmdlet 与别名(Remove-Item/ri/rm/del/rmdir/rd/Clear-Content/Format-Volume…)、命令链后半段的删除(A; Remove-Item …、A && rm …、$(rm …))、嵌套 shell 内的删除(cmd /c del、powershell -Command rm、bash -c "rm"、wsl rm、python -c "os.remove"等)、powershell -EncodedCommand解码后的删除、以及 SSH 远端命令中的删除。主机关机/重启(Stop-Computer/shutdown)与Invoke-Expression(绕过向)也一律拦截allowlist:只放行
powershell.allowedCommands里的命令,元字符默认禁用——旧行为,适合最严格场景
删除文件请走 delete_file(有审批门;PowerShell 侧无论本机还是 SSH 远端都删不了东西)。
通过 PowerShell 使用 SSH
blocklist 模式下可以直接跑 ssh,远端命令同样只拦删除:
ssh -o BatchMode=yes -o ConnectTimeout=10 deploy@10.0.0.5 "df -h && free -m"远端命令里的删除(
rm、rmdir、unlink、find -delete、sudo rm、远端 pythonos.remove等)会在连接之前被本地拦截;其余远端命令(管道、链式)正常放行读取不受限:
ssh host "cat /etc/hosts"、ssh host "ls -la /var/log"等浏览远端内容的命令一律放行,本地任意路径也能直接读建议始终带
-o BatchMode=yes -o ConnectTimeout=10:交互式密码/指纹确认会让调用挂到超时仅支持已配置免密登录(公钥)的主机;
ssh后面必须跟一次性命令,裸ssh(读 stdin)会被拒绝
Agent 桥接
agent_list_servers agent_list_tools agent_call_tool agent_refresh — 把你本机其他 MCP server 的工具代理给网页端。
状态
get_status — 让 Agent 自查当前权限、文件范围(allowedRoots/是否整机)、PowerShell 模式(blocklist/allowlist)与白名单、skill 目录与数量、搜索引擎、协作任务板状态、agent 列表、敏感文件策略。
文件范围(allowedRoots)
"files": { "allowedRoots": ["*"] } // 默认:整机任意路径
"files": { "allowedRoots": ["C:\\Users\\Administrator\\.workbuddy", "E:\\projects"] } // 只放行这两个目录"*"(或"any"/"all")表示整机:list_files/read_file/write_file/move_path/file_info/search_files都接受任意绝对路径,不再有PathSecurityError配置里的路径支持
~(展开为用户目录),rootDir永远在允许范围内越界时报错会提示怎么放宽:
Path "..." is outside the allowed roots (...). Add it to files.allowedRoots, or set files.allowedRoots = ["*"] ...敏感文件(
.env、*.pem、*.key、id_rsa…)由sensitivePatterns+allowSensitive控制,默认allowSensitive = true(可读);要恢复防护就设成false唯一的写保护是"删除":
delete_file是唯一删除通道(审批门 + 拒绝删除允许根本身),PowerShell 的删除命令在本机与 SSH 远端一律拦截
使用你本机的 Skill
开启后(默认开启),网页端模型可以先 list_skills 看清单,再 read_skill 把某个 skill 的 SKILL.md 读进上下文,然后照其中的步骤用现有工具完成工作——相当于把本机 skill 库变成了它的一部分能力。
"skills": {
"enabled": true,
"dirs": ["~/.trae-cn/skills", "~/.claude/skills", "~/.codex/skills", "~/.workbuddy/skills", "~/.trae-cn/plugins"],
"maxDepth": 6,
"maxSkills": 500
}扫描规则:目录树下任何含
SKILL.md的文件夹算一个 skill(其子目录视为references/、scripts/之类的附属资源,不再递归当 skill)元信息取自
SKILL.md顶部的 frontmatter(name/display_name/description/description_zh)单文件读取上限 400 KB;
read_skill的file参数只接受 skill 目录内的相对路径目录清单有 30 秒缓存,新增 skill 最多半分钟后可见;
skills.enabled = false则不注册这两个工具
联网搜索(web_search / fetch_page)
让连进来的 Agent 用你本机的网络位置去搜索和抓页面:web_search({query}) 拿标题+链接+摘要,fetch_page({url}) 把某个页面转成可读正文(mode: text|html|links)。
默认引擎是 Bing,不需要 API Key——Bing 有稳定的 RSS 结果端点(https://www.bing.com/search?q=…&format=rss),比抓 JS 渲染的结果页可靠得多,抓不到时才回退解析 HTML 结果块。默认之所以不是 DuckDuckGo:国内多数网络根本连不上 DDG(实测 html.duckduckgo.com、lite.duckduckgo.com、api.duckduckgo.com 全部超时),而 Bing 可用且很快。
引擎 | 需要 Key | 适用 |
| 否 | 国内可用;走 RSS 结果端点,失败回退 HTML |
| 否 | 免 Key,但国内多数网络不可达(报错时会提示你换 bing) |
| 是( | 需要正式搜索 API 时用 |
| 是( | 同上 |
# 关掉搜索工具
node bin/mcp-agent-bridge.js --search false
# 换成 tavily(需要 Key)
node bin/mcp-agent-bridge.js --search-engine tavily --search-key tvly-xxxx
# 自定义端点(内网镜像 / 自建搜索服务;{q} 与 {count} 会被替换)
node bin/mcp-agent-bridge.js --search-endpoint "http://10.0.0.9/search?q={q}&count={count}"注意:
fetch_page是静态抓取(不执行 JS),SPA 页面可能只拿到很少内容——这种页面用run_powershell起无头浏览器,或直接换一个静态源单次响应有大小上限(
search.maxBytes,默认 2MB)与超时(search.timeoutMs,默认 20s)Bing RSS / DDG HTML 属于"给人看的搜索结果",请仅作个人非商业用途;要商用/正式集成就切到
tavily/brave这类 API控制台监控台都能改引擎与端点(热生效);
search.apiKey在监控台里只写不读(接口返回时已脱敏)
桥接"我的 Agent 的工具"
在配置文件 agents 数组里登记任意本地 MCP server,启动时会自动连接并代理其全部工具:
{
"agents": [
{ "name": "filesystem", "transport": "stdio",
"command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "."] },
{ "name": "my-http-server", "transport": "http",
"url": "http://127.0.0.1:9000/mcp", "headers": { "Authorization": "Bearer xxx" } },
{ "name": "my-sse-server", "transport": "sse",
"url": "http://127.0.0.1:9001/sse" }
]
}网页端 Agent 调用:agent_call_tool { server: "filesystem", tool: "write_file", args: {...} }。每个 agent 可加 "enabled": false 暂时停用,"timeoutMs": 120000 控制调用超时。改完配置重启进程,或在监控台点"重连 Agents"。
监控台功能(http://127.0.0.1:7821,仅回环,不经隧道)
实时活动流:每次工具调用(参数/结果/耗时/成败)、会话建立断开、认证失败、隧道状态、Agent 状态,SSE 秒推,可按类型过滤
会话表:来源 IP(取自 CF-Connecting-IP)、User-Agent、连接时长、调用数、流量
审批队列:manual 模式下危险操作挂起等你批准/拒绝(见下)
配置热更新:rootDir、文件允许根(allowedRoots)、文件权限、PowerShell 模式与白名单、skill 目录、敏感模式、审批模式,改完即生效,无需重启
急停:一键"暂停服务"(所有工具调用立即被拒绝)、"断开隧道"
审计日志:所有事件落盘
logs/audit-YYYY-MM-DD.jsonl
本机 Agent 控制台(GUI,http://127.0.0.1:7822,仅回环)
一个浏览器里的"操作台":GUI 自身作为 MCP 客户端连到 bridge,因此它调用工具与网页端 Agent 走的是同一条 MCP 通道——同样的文件范围、命令策略(blocklist/allowlist)、审批与监控打点(监控台里能看到 gui 会话)。
这个控制台不含内置模型,也不再需要任何 API Key —— 大脑就是网页端模型,控制台负责"给它钥匙 + 让你看它在干什么"。
连接网页 Agent(核心):顶栏点 「🔗 连接网页 Agent」,一键生成连接提示词——已自动嵌入 MCP URL、访问令牌、文件范围(整机/指定根)、文件权限、PowerShell 与 SSH 规则、skill 用法、删除规则、审批模式、全部工具清单。复制后发给支持 MCP 的网页端模型(ChatGPT Apps & Connectors、Claude、Kimi 等),它就能连上来待命
接入本机 Agent:顶栏点 「🔌 接入本机 Agent」,给出可直接粘贴的 MCP 客户端配置(回环 URL + Bearer)、Claude Code 命令行写法,以及一段"指挥方"说明(含省 token 规矩)——详见上面的本机 Agent 接入
任务板:顶栏点 「📋 任务板」 看本机指挥方与网页端 Agent 的协作全貌(任务状态、谁在干、最新进展与结论、双方留言),也可以在这里直接写一句指令派活;有未完成任务时顶栏按钮会高亮并显示数量
实时活动流:网页端 Agent 的每一次工具调用都以卡片形式秒级推送到界面(参数、结果、耗时、成败,可展开),与监控台同源
工具面板:左侧列出全部工具与 JSON Schema 表单,点开即填参调用,用于调试和单次操作
范围条:顶部一行常显当前 rootDir、文件范围(是否整机)、权限、PowerShell 模式、skill 目录、敏感文件策略、审批模式
审批:
approval.mode = manual时,挂起的操作直接在活动流里弹出审批卡片,批准/拒绝后继续;也可在监控台统一处理暂停/隧道状态:顶栏徽章显示 MCP 连接、隧道、待审批数量与暂停状态
配置只有三个键(启动期配置,运行时不可热改;transport = stdio 时 GUI 自动关闭):
# 配置文件 bridge.config.json
"gui": { "enabled": true, "host": "127.0.0.1", "port": 7822 }
# CLI
node bin/mcp-agent-bridge.js --gui on --gui-port 7822为什么没有 API Key?
网页端模型自带推理能力,本工具只提供工具与通道,因此不需要你配置任何 LLM Key(gui.llm、gui.systemPrompt 以及 BRIDGE_LLM_* / --llm-* 等配置项已全部移除)。
让网页端模型当大脑(推荐):控制台点 「🔗 连接网页 Agent」 拿到提示词 → 发给网页端模型。注意:网页模型要走公网隧道,启动时需加
--public(弹窗里也会提示)。纯手动工具模式:左侧「工具」面板按 JSON Schema 填参调用,适合调试和单次操作。
⚠️ 连接提示词里包含明文访问令牌,等于把本机工具的钥匙交给收到它的模型——只发给你信任的服务,并在控制台/监控台留意其行为。
审批模式(推荐给敏感场景)
"approval": {
"mode": "manual",
"timeoutMs": 60000,
"requireFor": { "fileWrite": true, "fileDelete": true, "command": true, "agentCall": true }
}manual 模式下,网页端 Agent 的写文件 / 删除 / 执行命令 / 调用 agent 工具会挂起,监控台"审批"页弹出卡片显示完整参数,你点"批准"才真正执行(超时默认按拒绝处理)。auto 模式则全自动执行,仅记录审计。
安全模型
默认"除删除外全部放开":文件
read-write、PowerShell 开启、本机 Skill 开启、文件范围整机;公网默认关,allowlist 白名单为空 = 全拒绝公网暴露强制 Bearer Token(未提供则自动生成 64 位十六进制)
文件路径按
files.allowedRoots判定:默认["*"]= 整机可读写(有意为之,读取不受限);改成具体目录列表即恢复边界,越界仍会拒绝..逃逸与 symlink 逃逸allowSensitive默认true,即.env/*.pem/*.key等也可读;要恢复防护就设false(此时命中sensitivePatterns的路径会被拒绝)唯一被限制的能力是"删除":
delete_file是唯一删除通道(manual 模式下必须审批,且拒绝删除允许根本身);PowerShell 侧的删除/破坏性命令在本机与 SSH 远端一律拦截PowerShell 双模式:
blocklist(默认):任意命令可执行,但删除/破坏性命令做全链路拦截——命令分段解析(管道/
;/&&/$()后的删除都算)、嵌套 shell 递归检查(cmd/powershell/pwsh/bash/sh/wsl/python等,含-EncodedCommandBase64 解码)、SSH 命令行分区检查(远端命令里的删除在连接前拦截)、常见破坏性 payload 模式(docker rm、kubectl delete、find -delete、os.remove等);主机关机/重启与Invoke-Expression一律拒绝;裸 shell(无参,stdin 执行通道)拒绝allowlist:仅白名单命令 + 元字符默认禁用
两种模式都有超时与输出上限
监控台与 Agent 控制台都只绑定 127.0.0.1,不经过隧道
Token 在配置接口中始终脱敏,认证失败也会记录来源 IP
GUI 发起的工具调用与外部 Agent 同权限——受文件范围、命令策略(blocklist/allowlist)、审批门约束,且全部计入监控与审计
⚠️ 公网暴露本质上是把本机能力交给持有 token 的一方。请使用长随机 token、保持 manual 审批、定期看审计日志,不用时用监控台断开隧道。
配置
优先级:内置默认 < bridge.config.json(或 --config)< 环境变量 < CLI 参数。完整示例见 config.example.json。
键 | 默认 | 说明 |
| cwd | 相对路径的解析基准,永远在允许范围内 |
|
| 文件工具范围; |
|
|
|
|
| 是否启用 run_powershell |
|
| 是否启用 agent 桥接工具(需在 |
|
| 是否注册 list_skills / read_skill |
| 5 个常见目录 | skill 搜索目录(含 |
| 6 / 500 | 扫描深度与数量上限 |
|
| 是否注册 |
|
|
|
|
| 仅 tavily / brave 需要(接口返回时脱敏) |
|
| 覆盖引擎地址( |
| 6 / 20000 / 2000000 | 结果条数(1–10)、超时、单次响应上限 |
| 8000 |
|
|
| 是否注册协作任务板工具( |
|
| 任务板持久化文件(运行时不可改,需重启) |
| 200 / 200 | 保留上限(先淘汰最旧的已完成任务) |
|
|
|
|
| MCP HTTP 监听地址 |
|
| 启动公网隧道 |
|
|
|
| 自动生成 | 留空则每次启动随机生成(横幅打印);填固定值则重启不变 |
|
| 关闭认证(危险) |
| — | ngrok 免费 dev 域名;留空则回退 cloudflared |
| — | ngrok authtoken(也可用全局 |
|
|
|
|
| 命令白名单(仅 allowlist 模式生效;cmdlet 名或 exe 名) |
|
| 允许 |
| 30000 / 200000 | 超时与输出上限 |
|
| 桥接的本机 MCP server 列表 |
|
| 审批模式与超时 |
| 内置 / | 敏感文件防护;默认 |
|
| 监控台 |
|
| 本机 Agent 控制台(stdio 传输时强制关闭) |
|
| GUI 监听地址(仅回环,不经隧道) |
|
| 审计日志目录与内存事件上限 |
常用 CLI:--root --files --allowed-roots --skills on|off --skills-dirs --powershell --ps-mode blocklist|allowlist --agents --allowed-commands --search on|off --search-engine --search-key --search-endpoint --board on|off --board-file --public --provider cloudflared|ngrok --ngrok-domain --ngrok-authtoken --auth-token --port --host --approval manual|auto --gui on|off --gui-port <n> --config <file>;环境变量对应 BRIDGE_ALLOWED_ROOTS、BRIDGE_SKILLS_DIRS、BRIDGE_SKILLS、BRIDGE_PS_MODE、BRIDGE_ALLOWED_COMMANDS、BRIDGE_SEARCH、BRIDGE_SEARCH_ENGINE、BRIDGE_SEARCH_KEY、BRIDGE_BOARD、BRIDGE_BOARD_FILE、BRIDGE_PUBLIC_PROVIDER、BRIDGE_NGROK_DOMAIN、BRIDGE_NGROK_AUTHTOKEN 等。(已移除:--llm-base-url --llm-api-key --llm-model / BRIDGE_LLM_*)
常见问题
开着加速器 TUN 时 QUIC 反复超时:本工具使用
--protocol http2(TCP 7844)启动 cloudflared,避免依赖 UDP 转发;无需关闭 TUN。更新后重启 bridge 生效。如果仍然超时,请确认加速器当前节点允许 TCP 7844,并检查region1.v2.argotunnel.com/region2.v2.argotunnel.com的分流规则。trycloudflare URL 每次重启都会变:quick tunnel 的特性。要固定域名直接用 ngrok Provider(
--provider ngrok --ngrok-domain your-name.ngrok-free.dev,见「稳定域名(ngrok)」);也可以自己跑cloudflared tunnel命名隧道指向http.port,此时不要再加--public。命令被拒:not in the allowlist:只在 allowlist 模式出现。把该命令加进
powershell.allowedCommands(监控台配置页可热改),或切回默认的 blocklist 模式(--ps-mode blocklist)。read_file/list_files报PathSecurityError(以前读不到 C 盘):旧版本把路径锁在 rootDir 内。现在files.allowedRoots默认["*"],直接传绝对路径即可;若你手动改成过目录列表,把目标目录加进去,或改回["*"]。报错信息里会直接告诉你该怎么改。敏感文件读不了:说明
allowSensitive = false。设成true(默认值)即可读.env/*.pem/*.key等。需要真正删除文件时:
delete_file是唯一通道(manual 模式下会挂起等你批准);rm/Remove-Item/del等命令在任何模式、任何位置(含 SSH 远端)都会被拦截。list_skills看不到某个 skill:确认它所在目录在skills.dirs里、目录内直接放着SKILL.md,且清单缓存 30 秒后过期;也可显式加--skills-dirs指向它。为什么没有 API Key / LLM 配置了? 控制台已内置模型能力移除,改为由网页端模型当大脑:点「🔗 连接网页 Agent」拿提示词即可。旧的
--llm-*与BRIDGE_LLM_*参数已删除,配置里的gui.llm/gui.systemPrompt会被自动忽略。Remove-Item / rm / del 一直被拒:设计如此,两种模式下都拦截。删除请用
delete_file(审批门保护)。为什么 ssh 远程执行
rm会被拒绝? SSH 命令行会被分成"本地参数"和"引号内的远端命令"两段分别检查,远端命令中的删除模式(rm、rmdir、unlink、find -delete、sudo rm等)在建立连接之前就被本地策略拦截——这是有意为之,本工具不希望网页端 Agent 通过 SSH 删掉你远端机器上的东西。远端的非删除命令不受影响。ssh 卡住直到超时:大概率是交互式密码或主机指纹确认在等输入。请给主机配置公钥免密登录,并带上
-o BatchMode=yes -o ConnectTimeout=10。Agent 连接失败:看监控台 Agent 表的错误信息;stdio 方式确认 command/args 可在终端手动跑通。
本机 Agent 连上了,但任务板是空的 / 两边看不到对方:确认本机 Agent 用的是 HTTP 回环 URL(
http://127.0.0.1:8080/mcp+ Bearer),而不是 stdio 另起的进程——只有连到同一个 bridge 进程才会共享同一块board.file。用get_status看handoff里的total/open是不是同一个板子。指挥方收不到完成通知:
update_task的status要写done/failed/blocked才会自动发通知(只写note不会);通知发给delegate_task时的from(默认local),所以读取要用read_messages({to:"local"})。web_search报错或没有结果:默认走 Bing,国内可用;engine=duckduckgo在国内多数网络会fetch failed(报错信息里会提示换 bing)。公司网络需要代理时可换tavily/brave(带 Key)或--search-endpoint指到内网搜索服务。fetch_page抓回来几乎是空的:目标页是 JS 渲染的,静态抓取拿不到内容。换静态源,或用run_powershell起无头浏览器抓。任务板文件在哪、会不会丢:默认
logs/board.json(board.file可改,但需重启),写入是"临时文件 + rename"的原子写,重启后自动恢复;board.maxTasks满了会先淘汰最旧的已完成任务,未完成的保留。
目录结构
mcp-agent-bridge/
├── bin/mcp-agent-bridge.js 入口
├── src/
│ ├── index.js 启动编排
│ ├── config.js 配置(默认值/文件/env/CLI 合并校验)
│ ├── server.js MCP server 组装 + 调用打点
│ ├── monitor.js 监控核心:事件/会话/审计/审批/统计
│ ├── security/ 路径范围(allowedRoots)/ PowerShell 命令校验
│ ├── tools/ files / powershell / skills / agent-bridge / handoff(任务板)/ search(搜索+抓页)
│ ├── transports/ Streamable HTTP (+stdio)
│ ├── tunnel/ cloudflared / ngrok 隧道封装
│ ├── gui/ Agent 控制台(MCP 客户端 + 活动流 + 连接提示词)
│ └── dashboard/ 监控台(API + SSE + 前端)
├── config.example.json
└── test/ e2e / gui / gui-approval / agents / ps-blocklist / tunnel / ngrokMIT License. 参考 expose-files-mcp(MIT)。
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Remote MCP server exposing your Node Command fleet (files, shell, processes, browser) to AI hosts.
Connect ChatGPT and Claude to your Mac, Windows or Linux with secure MCP remote access.
Remote streamable-HTTP MCP server running on a single Cloudflare Worker. Your assistant gets live Airbnb, Amazon, Booking.com, Google Flights, Maps and Reddit data, social search on X, Instagram and TikTok, the Meta Ad Library, and image/video generation without any keys. Connect your own accounts to let it send WhatsApp or Telegram messages, work an IMAP inbox, manage Meta Ads campaigns and publish to X and LinkedIn. OAuth 2.1 with PKCE; stored credentials are AES-256-GCM encrypted.
Hosted MCP server for live public-data APIs and Skills for AI agents.
Related MCP Servers
- FlicenseNot gradedqualityCmaintenanceTurns your local machine into an MCP server with a GUI, allowing agents to execute file operations, run commands (including admin), manage background processes, and query databases, with optional ngrok exposure.-
- AlicenseNot gradedqualityDmaintenanceEnables remote MCP clients like ChatGPT to run shell commands and manage files on your local machine via a Cloudflare tunnel, exposing tools for file operations, search, and task management.7MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to securely access and control a Windows machine remotely, running commands and managing files via an MCP server protected by Bearer-token authentication and exposed through a Cloudflare Tunnel.MIT
- AlicenseNot gradedqualityBmaintenanceEnables authenticated web agents to reach a local machine through a portable MCP endpoint, with optional Cloudflare Tunnel or Tailscale Funnel ingress for public access.MIT