连接与鉴权

Marginnote CLI在MacOS上会监听127.0.0.1端口，这意味着除非经过本机转发，否则无法跨设备访问。

MarginNote 设置 → Lab → 开启「MarginNote CLI」
令牌来源：~/.config/mn-bridge/token 文件、直接提供、环境变量 MN_BRIDGE_TOKEN
未安装时：设置 → Lab →「Copy Agent Setup Command」，粘进终端执行

跨设备确认

study-sets/{id}/delete、notes/delete、snapshots/{id}/restore 在跨设备下需要设备端按 Allow。带 confirm:true 的请求会挂起，最多 60 秒。

返回	含义
200	设备端已 Allow
403 `APPROVAL_DENIED`	设备端已 Deny
408 `APPROVAL_TIMEOUT`	60 秒内设备端无响应，确认设备状态后重试

MCP 接入

claude mcp add --transport http marginnote http://127.0.0.1:{port}/bridge/v1/mcp \
  --header "Authorization: Bearer $TOKEN"

接入后提供 mn_guide 与 mn_call 两个工具。mn_guide 返回运行时规程，mn_call 以 {method,path,body} 转发到同一批端点。

同机发现

跨设备跳过本节。

BRIDGE_JSON=""
for f in ~/Library/Containers/*[Mm]argin*/Data/Library/Application\ Support/MNAgentBridge/bridge.json \
         ~/Library/Application\ Support/MNAgentBridge/bridge.json; do
  [ -r "$f" ] && { BRIDGE_JSON="$f"; break; }
done

if [ -n "$BRIDGE_JSON" ]; then
  PORT=$(sed -n 's/.*"port"[^0-9]*\([0-9][0-9]*\).*/\1/p' "$BRIDGE_JSON" 2>/dev/null | head -1)
  NONCE=$(sed -n 's/.*"instanceNonce"[^"]*"\([^"]*\)".*/\1/p' "$BRIDGE_JSON" 2>/dev/null | head -1)
fi
if [ -z "$PORT" ]; then
  PORT=$(lsof -nP -iTCP -sTCP:LISTEN 2>/dev/null | grep -i margin \
         | grep -o '127\.0\.0\.1:[0-9]*' | head -1 | cut -d: -f2)
fi
PORT=${PORT:-42340}

BASE="http://127.0.0.1:$PORT/bridge/v1"
curl -s "$BASE/status"

bridge.json 读不到常见于缺少完全磁盘访问权限。lsof 扫不到不代表 Bridge 未运行，受限环境的进程表可能残缺。端口缺省 42340。status 返回 instanceNonce 时与本地值比对。

后续请求在 Authorization 头携带 Bearer token。

携带 Origin 头的请求会被拒绝，返回 403 FORBIDDEN_ORIGIN。见错误处理。

首次检查

读 `GET /status`

返回 bridgeApiVersion、routeCount、apiFingerprint、guideVersion、guideHash。guideHash 为完整 SHA-256。

规程不一致则刷新

运行时的 guide 版本或 hash 与已加载规程不一致时，用现有 Bearer token 读 GET /guide，以返回的 Markdown 为当前会话规程。只读刷新，不调 /install，不轮换 token，不覆写磁盘文件。缺少这些字段时用 /capabilities 核对。

读 `GET /capabilities`

返回实际注册的全部路由 {routes:[{method,path}]}，以及 presets、anchorModes 等。仅调用清单中的路由。

403 与 401

现象	含义	动作
`401 UNAUTHORIZED`	令牌缺失或无效	更换 token 后重试。TCP 可达而 401 说明令牌无效
`403 FORBIDDEN_ORIGIN`	请求带了 Origin 头	去掉 Origin 头重试
跨设备 403 `APPROVAL_DENIED`	设备端拒绝了请求	见跨设备确认
跨设备 408 `APPROVAL_TIMEOUT`	设备端 60 秒内无响应	确认设备状态后重试

连接与鉴权

On this page