Skip to content
Back to search

muse-relay-mcp

An MCP server that exposes your personal Muse at muse.ai as tools for other coding agents — terminal coding agents, IDEs, and other MCP hosts

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 20 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/99apps-id/muse-relay-mcp with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/99apps-id/muse-relay-mcp'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/99apps-id--muse-relay-mcp/badge.svg)](/listings/99apps-id--muse-relay-mcp)

HTML

<a href="/listings/99apps-id--muse-relay-mcp"><img src="/api/listings/99apps-id--muse-relay-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Every step is labelled with its difficulty. If the relay already runs on your machine — for example because you installed the Muse Companion extension first — this is a five-minute job; the only hard part is the one-time relay setup, and most of that is done by Muse itself.

| Step | What you get | Difficulty | Time | | --- | --- | --- | --- | | Relay check ([Part B](#part-b--set-up-the-relay-first-time-and-make-sure-it-is-running), step 5) | Confirmation the relay is live and not paused | 🟢 **Easy** | ~2 min | | [Part A — Get the server](#part-a--get-the-server) | `server.js` on your machine — no build, no `npm install` | 🟢 **Easy** — clone + one check command | ~5 min | | [Part B — Set up the relay](#part-b--set-up-the-relay-first-time-and-make-sure-it-is-running) *(only if no relay exists yet)* | The one-time relay behind the server | 🔴 **Advanced, one-time** — any SSH route from Muse to this machine (e.g. reverse SSH tunnel `ssh -R`, jump host, Tailscale/WireGuard, or direct IP) + SSH key; the polling hook is created by Muse on request | ~20–30 min | | [Part C — Register it in your MCP host](#part-c--register-it-in-your-mcp-host) | The `ask_muse` tools in your agent | 🟡 **Moderate** — paste a JSON snippet, restart the host | ~5 min |

The shortest path: relay live → **Part A** → **Part C** → restart the host → ask its agent to call `ask_muse_start` with a test question, then `ask_muse_check` until the answer arrives.

*Not a terminal person?* The relay setup is the only steep part — open [muse.ai](https://muse.ai) and ask Muse to set up the `muse-relay-inbox` hook with you. Muse writes the hook and the worker instructions; your part is enabling an SSH route to your machine (Tailscale is optional — any SSH tunnel, reverse SSH `ssh -R`, VPN, or jump host works).

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 456 lines
  1. <p align="center">
  2. <img src="images/muse-mascot-coding.gif" alt="Muse mascot coding - muse-relay-mcp" width="420">
  3. </p>
  4. <h1 align="center">muse-relay-mcp</h1>
  5. <p align="center">
  6. <a href="https://github.com/99apps-id/muse-relay-mcp"><img src="https://img.shields.io/badge/release-v0.1.2-blue" alt="Release"></a>
  7. <a href="https://nodejs.org/"><img src="https://img.shields.io/badge/node-%3E%3D18-339933" alt="Node"></a>
  8. <a href="#license"><img src="https://img.shields.io/badge/license-Apache%202.0-blue" alt="License: Apache 2.0"></a>
  9. <img src="https://img.shields.io/badge/dependencies-none-brightgreen" alt="Dependencies">
  10. </p>
  11. An MCP server that exposes **your personal Muse at [muse.ai](https://muse.ai)** as tools for other coding agents — terminal coding agents, IDEs, and other MCP hosts. Questions travel through the **muse-relay** file relay: the server writes a request file, a polling hook on the Muse side wakes a Muse worker, and the answer comes back as a file that the server returns as the tool result.
  12. > **Not an official Meta product.** Muse personal has no public API and cannot act as an MCP server natively — this bridge is the workaround. Answers come from your personal Muse, with its long-term memory of your projects, not from a raw model API.
  13. > **Separate project.** This server is a standalone project, independent from the **Muse Companion** VS Code extension. The two share nothing but the relay folder: the extension does not contain this server, and this server does not need the extension — only the relay folders and the Muse-side polling hook (see [Requirements](#requirements)).
  14. <a id="screenshot"></a>
  15. A real JSON-RPC session against `server.js` — handshake, tool list, an async question, and its answer arriving through the relay:
  16. <p align="center">
  17. <img src="images/terminal-session.png" alt="Terminal session with the muse-relay MCP server" width="880">
  18. </p>
  19. ## Table of Contents
  20. - [Quick Start](#quick-start)
  21. - [For AI Agents (Automated Setup)](#for-ai-agents-automated-setup)
  22. - [Tools](#tools)
  23. - [Screenshot](#screenshot)
  24. - [Blocking vs Async](#blocking-vs-async)
  25. - [How It Works](#how-it-works)
  26. - [Requirements](#requirements)
  27. - [Installation](#installation)
  28. - [Part A — Get the server](#part-a--get-the-server)
  29. - [Part B — Make sure the relay is running](#part-b--make-sure-the-relay-is-running)
  30. - [Part C — Register it in your MCP host](#part-c--register-it-in-your-mcp-host)
  31. - [Usage](#usage)
  32. - [Use Cases](#use-cases)
  33. - [Configuration](#configuration)
  34. - [Relay Protocol](#relay-protocol)
  35. - [Security and Privacy](#security-and-privacy)
  36. - [Limitations](#limitations)
  37. - [Troubleshooting](#troubleshooting)
  38. - [Changelog](#changelog)
  39. - [License](#license)
  40. ## Quick Start
  41. Every step is labelled with its difficulty. If the relay already runs on your machine — for example because you installed the Muse Companion extension first — this is a five-minute job; the only hard part is the one-time relay setup, and most of that is done by Muse itself.
  42. | Step | What you get | Difficulty | Time |
  43. | --- | --- | --- | --- |
  44. | Relay check ([Part B](#part-b--set-up-the-relay-first-time-and-make-sure-it-is-running), step 5) | Confirmation the relay is live and not paused | 🟢 **Easy** | ~2 min |
  45. | [Part A — Get the server](#part-a--get-the-server) | `server.js` on your machine — no build, no `npm install` | 🟢 **Easy** — clone + one check command | ~5 min |
  46. | [Part B — Set up the relay](#part-b--set-up-the-relay-first-time-and-make-sure-it-is-running) *(only if no relay exists yet)* | The one-time relay behind the server | 🔴 **Advanced, one-time** — any SSH route from Muse to this machine (e.g. reverse SSH tunnel `ssh -R`, jump host, Tailscale/WireGuard, or direct IP) + SSH key; the polling hook is created by Muse on request | ~20–30 min |
  47. | [Part C — Register it in your MCP host](#part-c--register-it-in-your-mcp-host) | The `ask_muse` tools in your agent | 🟡 **Moderate** — paste a JSON snippet, restart the host | ~5 min |
  48. The shortest path: relay live → **Part A** → **Part C** → restart the host → ask its agent to call `ask_muse_start` with a test question, then `ask_muse_check` until the answer arrives.
  49. *Not a terminal person?* The relay setup is the only steep part — open [muse.ai](https://muse.ai) and ask Muse to set up the `muse-relay-inbox` hook with you. Muse writes the hook and the worker instructions; your part is enabling an SSH route to your machine (Tailscale is optional — any SSH tunnel, reverse SSH `ssh -R`, VPN, or jump host works).
  50. ## For AI Agents (Automated Setup)
  51. If an operator gives you (an AI coding agent such as **Claude Code, OpenAI Codex CLI, Google Antigravity, VS Code Copilot, Cursor, Windsurf, or Gemini CLI**) this repository URL and asks you to install or set it up for them, follow this exact checklist:
  52. 1. **Dependencies & Prerequisites (Zero npm packages required):**
  53. - Runtime required: **Node.js `>= 18`** (`node --version`) and **`git`** (or download `server.js` directly).
  54. - **Do NOT run `npm install` or any build step** — `server.js` uses only built-in Node.js modules (`fs`, `os`, `path`, `readline`).
  55. - **Tailscale is NOT required:** the relay only needs *any* working SSH path from Muse's environment to the relay folder on this machine (e.g. reverse SSH tunnel `ssh -R` via a VPS/jump host, Cloudflare Tunnel, WireGuard, ZeroTier, Tailscale, or direct IP). Do not install Tailscale unless the operator specifically asks for it.
  56. 2. **Clone the repository & create the local relay directories:**
  57. - Clone `https://github.com/99apps-id/muse-relay-mcp.git` into a persistent folder (e.g. `~/muse-relay-mcp` or the operator's preferred directory) and note the absolute path to `server.js`.
  58. - Ensure the three relay directories exist (`~/muse-relay/inbox`, `~/muse-relay/outbox`, `~/muse-relay/archive`):
  59. - **Windows (PowerShell):**
  60. ```powershell
  61. New-Item -ItemType Directory -Force "$env:USERPROFILE\muse-relay\inbox", "$env:USERPROFILE\muse-relay\outbox", "$env:USERPROFILE\muse-relay\archive"
  62. ```
  63. - **macOS / Linux (Bash):**
  64. ```bash
  65. mkdir -p "$HOME/muse-relay/inbox" "$HOME/muse-relay/outbox" "$HOME/muse-relay/archive"
  66. ```
  67. 3. **Smoke-test `server.js` locally:**
  68. - Run `node --check server.js` and pipe the JSON-RPC `initialize` + `tools/list` smoke test from [Part A, step 3](#part-a--get-the-server) into `node server.js` to confirm `ask_muse`, `ask_muse_start`, and `ask_muse_check` are listed.
  69. 4. **Register `muse-relay` in the operator's MCP host config (merge safely — never overwrite existing MCP servers):**
  70. - **VS Code (`%APPDATA%\Code\User\mcp.json` or `.vscode/mcp.json`):** add under top-level `"servers"` with `"type": "stdio"`, `"command": "node"`, `"args": ["<ABSOLUTE_PATH_TO_SERVER_JS>"]`.
  71. - **Claude Code:** run `claude mcp add muse-relay -- node "<ABSOLUTE_PATH_TO_SERVER_JS>"` (or merge into `~/.claude.json` under `"mcpServers"`).
  72. - **OpenAI Codex CLI (`~/.codex/config.toml`):** append the TOML table `[mcp_servers.muse-relay]` with `command = "node"` and `args = ["<ABSOLUTE_PATH_TO_SERVER_JS>"]`.
  73. - **Google Antigravity (`~/.gemini/antigravity/mcp_config.json`), Claude Desktop, Cursor (`~/.cursor/mcp.json`), Windsurf (`~/.codeium/windsurf/mcp_config.json`), Gemini CLI (`~/.gemini/settings.json`):** merge `"muse-relay": { "command": "node", "args": ["<ABSOLUTE_PATH_TO_SERVER_JS>"] }` under `"mcpServers"`.
  74. 5. **Report clearly to the operator:**
  75. - Tell the operator to **restart their IDE / agent session** so the new `muse-relay` MCP tools load.
  76. - Check whether `~/muse-relay/control.json` or `~/muse-relay/applied.json` already exists:
  77. - If they exist, the Muse-side SSH relay is already configured — remind the operator to ensure the relay is not paused (`"paused": false` in `control.json`) and that the `muse-relay-inbox` hook is enabled on muse.ai.
  78. - If they do not exist yet, inform the operator that the local MCP server and relay folders are ready, and point them to the one-time SSH reachability + `muse-relay-inbox` hook setup in [Part B](#part-b--set-up-the-relay-first-time-and-make-sure-it-is-running).
  79. ## Tools
  80. | Tool | Mode | Behaviour |
  81. | --- | --- | --- |
  82. | `ask_muse` | Blocking | Ask a question and wait for the answer in one call (default timeout 600 s, adjustable 5–3600 s via `timeoutSecs`). Uses filesystem event watchers (`fs.watch`) so the answer returns **immediately** the instant Muse finishes. On timeout the question is **not** cancelled — you receive a `PENDING` result with the ticket id to continue waiting via `ask_muse_check`. |
  83. | `ask_muse_start` | Async | Submit a question and return immediately with a ticket id. |
  84. | `ask_muse_check` | Async / Long-Poll | Fetch or wait for a ticket id. If the answer is already in the outbox, returns immediately (0 ms). Otherwise watches the outbox in real time up to `waitSecs` (default 25 s, configurable 0–600 s), returning the instant Muse finishes or `PENDING` if still working. Safe to call repeatedly. |
  85. Shared arguments: `prompt` (required), `workspaceRoot` (optional), `answerLanguage` (`en` / `id`).
  86. ## Blocking vs Async
  87. - **Instant delivery when Muse is fast:** Both `ask_muse` and `ask_muse_check` attach an OS filesystem watcher (`fs.watch`) to the relay `outbox` and `archive` folders. Whether Muse takes 8 seconds or 8 minutes, the tool returns within milliseconds of the answer file landing.
  88. - **Blocking** (`ask_muse`) is simple: the agent asks and waits in a single tool call (up to `timeoutSecs`, max 3600 s / 1 hour), while sending MCP `notifications/progress` heartbeats when requested by the host. If the call reaches `timeoutSecs` first, it returns a non-error `PENDING` response containing the ticket id so the agent can seamlessly continue waiting with `ask_muse_check`.
  89. - **Async + Long-Polling** (`ask_muse_start` + `ask_muse_check`) is immune to strict MCP host tool-call timeouts (such as 60–120 s limits in Cursor, Codex, or Claude Code). Each `ask_muse_check` call can hold for `waitSecs` (default 25 s, or pass e.g. `waitSecs: 45` / `60`) so the agent can patiently wait for long tasks without burning dozens of rapid polling turns.
  90. ## How It Works
  91. ```text
  92. MCP host (agent) your machine Muse side
  93. ---------------- ------------ -----------
  94. tool call ----> server.js (stdio, this repo)
  95. write req-mcp-<id>.json ----> ~/muse-relay/inbox/
  96. polling hook (SSH tunnel)
  97. wakes a Muse worker
  98. tool result <---- read res-mcp-<id>.json <---- worker answers, archives req
  99. (outbox, then archived)
  100. ```
  101. The server is a single dependency-free Node script speaking line-delimited JSON-RPC over stdio, exactly like a regular MCP server. All the latency and queueing live in the relay behind it.
  102. ## Requirements
  103. - Node.js 18 or newer, available as `node`.
  104. - A working **muse-relay** on the same machine:
  105. - Relay folders `~/muse-relay/{inbox,outbox,archive}` (Windows: `C:\Users\<WINDOWS_USER>\muse-relay\...`), overridable with the `MUSE_RELAY_DIR` environment variable.
  106. - A network path from Claude's environment to this machine. The hook polls the relay folders **over SSH**, so this machine must be reachable from Claude's side. The reference setup uses [Tailscale](https://tailscale.com/download) (install it on both ends, log in with the same account) plus an SSH server on this machine; any equivalent route — LAN, another VPN, a jump host — works just as well. Tailscale itself is not mandatory; SSH reachability is.
  107. - A polling hook named `muse-relay-inbox` enabled on the Muse side, which wakes a worker for new request files. A reference setup (folders, SSH/Tailscale reachability, the hook, and the worker instructions) is documented in the companion extension's README, Part B.
  108. - The relay must not be paused (`control.json` in the relay folder). While paused, every tool refuses fast with a `PAUSED` error.
  109. Throughout this document, replace the placeholders with your own values:
  110. | Placeholder | Meaning | Example |
  111. | --- | --- | --- |
  112. | `<INSTALL_DIR>` | Folder where you put this project | `C:\Project\muse-relay-mcp` |
  113. | `<WINDOWS_USER>` | Your Windows account name | `alice` |
  114. ## Installation
  115. ### Part A — Get the server
  116. 1. Clone this repository (or copy the project folder) to your install directory:
  117. ```bash
  118. git clone https://github.com/99apps-id/muse-relay-mcp.git muse-relay-mcp
  119. cd muse-relay-mcp
  120. ```
  121. 2. Verify the script parses and Node is new enough:
  122. ```bash
  123. node --version # v18 or newer
  124. node --check server.js # no output = OK
  125. ```
  126. There is nothing to install — no `npm install`, no build step.
  127. 3. (Optional smoke test) Pipe a handshake and a tool list into the server:
  128. ```bash
  129. printf '%s\n%s\n%s\n' \
  130. '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"smoke","version":"1.0.0"}}}' \
  131. '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
  132. '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' \
  133. | node server.js
  134. ```
  135. You should see two responses, the second listing `ask_muse`, `ask_muse_start`, and `ask_muse_check`.
  136. ### Part B — Set up the relay (first time) and make sure it is running
  137. The MCP server is only the front door — without a running relay behind it, questions queue forever. If the relay already runs on this machine (for example because you installed the companion extension first), only step 5 applies. If you are starting from this server alone, work through all five steps:
  138. 1. **Create the relay folders** on this machine (Windows PowerShell):
  139. ```powershell
  140. New-Item -ItemType Directory -Force "$env:USERPROFILE\muse-relay\inbox"
  141. New-Item -ItemType Directory -Force "$env:USERPROFILE\muse-relay\outbox"
  142. New-Item -ItemType Directory -Force "$env:USERPROFILE\muse-relay\archive"
  143. ```
  144. 2. **Make this machine reachable from Claude's environment.** Install Tailscale on this machine and on the machine Muse runs on (or its jump host) from [tailscale.com/download](https://tailscale.com/download); log in with the **same Tailscale account** on both ends. Verify with `tailscale status`, and note this machine's mesh address via `tailscale ip -4` — Muse's side needs it as its SSH target. Another VPN, a plain LAN route, or a jump host is equally fine; only SSH reachability matters, Tailscale is simply the reference route.
  145. 3. **Enable SSH into this machine** and install Muse's public key (ask Muse for it in the muse.ai chat). On Windows, in an elevated PowerShell:
  146. ```powershell
  147. Add-WindowsCapability -Online -Name OpenSSH.Server~~~~0.0.1.0
  148. Start-Service sshd
  149. Set-Service -Name sshd -StartupType Automatic
  150. ```
  151. Place the key in `C:\Users\<WINDOWS_USER>\.ssh\authorized_keys` — one key per line. If `<WINDOWS_USER>` is an administrator account, Windows OpenSSH reads `C:\ProgramData\ssh\administrators_authorized_keys` instead.
  152. 4. **Create the polling hook on the Muse side.** In the muse.ai chat, ask Muse to create an event hook named `muse-relay-inbox` that polls the relay inbox over the SSH path from step 2 every 5 seconds, wakes a worker for each new `req-*.json`, and re-wakes a request that stays unanswered for 15 minutes (watchdog, max 2 retries). The worker reads the request, does the work, writes `res-<id>.json` to the outbox, and moves the request to the archive. A fuller reference — exact worker instructions and settings sync — is Part B of the companion extension's README.
  153. 5. **Confirm it is live:** in the muse.ai chat, confirm the `muse-relay-inbox` hook is **enabled** — if it is disabled, questions queue silently and calls time out. Also make sure the relay is not paused (`control.json` in the relay folder; if you use the companion extension, check its panel). Then verify end-to-end in Part C, step 5.
  154. ### Part C — Register it in your MCP host
  155. Below are ready-to-use configurations for **VS Code**, **Claude Code**, **Claude Desktop**, **OpenAI Codex CLI**, **Google Antigravity**, **Cursor / Windsurf**, and **Gemini CLI**. On Windows, escape backslashes in JSON paths (`C:\\Project\\muse-relay-mcp\\server.js`), or use forward slashes (`C:/Project/muse-relay-mcp/server.js`).
  156. #### 1. VS Code (GitHub Copilot)
  157. VS Code uses the top-level `"servers"` key in `%APPDATA%\Code\User\mcp.json` (global) or `.vscode/mcp.json` (workspace):
  158. ```json
  159. {
  160. "servers": {
  161. "muse-relay": {
  162. "type": "stdio",
  163. "command": "node",
  164. "args": ["<INSTALL_DIR>\\server.js"]
  165. }
  166. }
  167. }
  168. ```
  169. #### 2. Claude Code (CLI)
  170. Register with a single command:
  171. ```bash
  172. claude mcp add muse-relay -- node "<INSTALL_DIR>/server.js"
  173. ```
  174. Or add to `~/.claude.json` (user scope) or `.mcp.json` (project scope):
  175. ```json
  176. {
  177. "mcpServers": {
  178. "muse-relay": {
  179. "command": "node",
  180. "args": ["<INSTALL_DIR>\\server.js"]
  181. }
  182. }
  183. }
  184. ```
  185. #### 3. Claude Desktop
  186. Add to `%APPDATA%\Claude\claude_desktop_config.json` (Windows) or `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS):
  187. ```json
  188. {
  189. "mcpServers": {
  190. "muse-relay": {
  191. "command": "node",
  192. "args": ["<INSTALL_DIR>\\server.js"]
  193. }
  194. }
  195. }
  196. ```
  197. #### 4. OpenAI Codex CLI
  198. Codex CLI uses **TOML** in `~/.codex/config.toml` (or `%USERPROFILE%\.codex\config.toml` on Windows):
  199. ```toml
  200. [mcp_servers.muse-relay]
  201. command = "node"
  202. args = ["<INSTALL_DIR>/server.js"]
  203. ```
  204. *(Optional)* If your relay folder is custom, add `env = { MUSE_RELAY_DIR = "D:/path/to/muse-relay" }` under `[mcp_servers.muse-relay]`.
  205. #### 5. Google Antigravity
  206. Add to `%USERPROFILE%\.gemini\antigravity\mcp_config.json`:
  207. ```json
  208. {
  209. "mcpServers": {
  210. "muse-relay": {
  211. "command": "node",
  212. "args": ["<INSTALL_DIR>\\server.js"]
  213. }
  214. }
  215. }
  216. ```
  217. #### 6. Cursor, Windsurf, Cline, Gemini CLI & Other MCP Hosts
  218. Most other MCP hosts (`~/.cursor/mcp.json`, `~/.codeium/windsurf/mcp_config.json`, `~/.gemini/settings.json`, termigo, ODON) use the standard `"mcpServers"` schema:
  219. ```json
  220. {
  221. "mcpServers": {
  222. "muse-relay": {
  223. "command": "node",
  224. "args": ["<INSTALL_DIR>\\server.js"]
  225. }
  226. }
  227. }
  228. ```
  229. #### Custom Relay Folder (`MUSE_RELAY_DIR`)
  230. If your relay folder is not the default `~/muse-relay`, pass `MUSE_RELAY_DIR` via `"env"`:
  231. ```json
  232. {
  233. "command": "node",
  234. "args": ["<INSTALL_DIR>\\server.js"],
  235. "env": {
  236. "MUSE_RELAY_DIR": "D:\\path\\to\\muse-relay"
  237. }
  238. }
  239. ```
  240. #### Restart & Verify
  241. 1. **Restart the host app or start a new session** — MCP hosts read their server list at startup, so the new tools appear only afterwards.
  242. 2. **Verify end-to-end:** ask the host's agent to call `ask_muse_start` with a question only your personal Muse can answer (something about your own projects or earlier decisions), then `ask_muse_check` until the answer arrives. As soon as Muse finishes, `ask_muse_check` returns immediately.
  243. ## Usage
  244. - Prefer the **async pair** for coding agents: `ask_muse_start`, keep working, then `ask_muse_check` every so often.
  245. - Use **blocking** `ask_muse` for quick questions from hosts with generous tool-call timeouts. If it times out, take the ticket id from the response and continue with `ask_muse_check` — the question stays alive.
  246. - Each call is a **one-shot question**, not a conversation thread: include the context the question needs in `prompt` (and `workspaceRoot` when relevant). Follow-up questions are new calls.
  247. - Answers typically take **1–10 minutes** (relay polling + a serial worker queue + the work itself). The relay watchdog re-wakes a request that stays unanswered for 15 minutes, at most 2 times.
  248. ## Use Cases
  249. The point of the bridge is that the answer comes from **your personal Muse** — with its connected accounts, its own tools, and its long-term memory of your projects — not from a raw model that can only see the current workspace. Four patterns from real use:
  250. ### 1. Pull your Instagram or Threads into the coding chat
  251. Building a content tool, a landing page, or a social dashboard, and the data you need lives in your social accounts? Let the coding agent ask Muse instead of copy-pasting between apps:
  252. ```text
  253. ask_muse_start: "Fetch my 10 most recent Instagram posts with their like and
  254. comment counts, and summarize what performed best this week."
  255. ask_muse_start: "Read my Threads direct messages from the last 3 days, group
  256. them by topic, and list anything that still needs a reply."
  257. ```
  258. Muse reads the connected account, does the summarizing, and the result lands as a tool result **inside the chat UI of your coding app** — VS Code, Claude Code, Antigravity, a terminal agent — right next to the code it is relevant to. This needs the account connected to your Muse; Muse reads only what the prompt asks for.
  259. ### 2. Post to Instagram or Threads without leaving the editor
  260. The same path works in the other direction. The coding agent composes the request, Muse does the publishing:
  261. ```text
  262. ask_muse: "Draft a short announcement for the v0.2 release (notes attached in
  263. the prompt) and post it to my Threads and Instagram."
  264. ```
  265. Muse prepares the draft and shows you the **exact text for approval in its own chat** before anything is posted — a coding agent's say-so is never enough to publish under your name. Once you approve, Muse posts it and the confirmation comes back through the relay into the coding chat.
  266. ### 3. Delegate a long, web-heavy errand to a Muse worker — a real run
  267. On 19 Nov 2026, an Antigravity agent (Opus 5.5) delegated a multi-step audit to a Muse worker through this bridge: find CCTV streams for three cities for a streaming-directory project, validate that every stream really plays, update the allowlist and the data file. The agent kept working locally; the Muse worker did the web research and validation.
  268. <p align="center">
  269. <img src="images/delegated-task.png" alt="A real delegated task through muse-relay: an Antigravity agent asks a Muse worker to audit CCTV streams, and the result comes back by ticket" width="880">
  270. </p>
  271. <p align="center"><em>Rendered from the actual relay files of that run (ticket <code>mcp-mwnasqwq96ux4</code>), excerpted. The honest result — 0 new cameras passed, 79 existing entries re-verified — is exactly why the async pattern exists: the job took 23 minutes, far beyond any blocking tool-call timeout.</em></p>
  272. ### 4. Borrow Muse's memory of your other projects
  273. A coding agent sees one workspace. Your Muse remembers the decisions, preferences, and history across all of them:
  274. ```text
  275. ask_muse: "In my other terminal-agent project, why did we pin the parser
  276. library to a single version last month — and does that apply here?"
  277. ```
  278. Second opinions, cross-project context, "what did I decide about X" — questions no amount of grepping the current repo can answer.
  279. ## Configuration
  280. | Setting | Where | Default | Notes |
  281. | --- | --- | --- | --- |
  282. | Relay folder | `MUSE_RELAY_DIR` env var | `%USERPROFILE%\muse-relay` (Windows) / `~/muse-relay` | Must match the folder the hook and panel use |
  283. | Blocking timeout | `timeoutSecs` argument of `ask_muse` | 600 (range 5–3600) | Timeout never cancels the question; returns ticket id for `ask_muse_check` |
  284. | Long-poll wait per check | `waitSecs` argument of `ask_muse_check` | 25 (range 0–600) | Returns immediately when answer arrives; returns `PENDING` after `waitSecs` |
  285. | Answer language | `answerLanguage` argument | `id` | Sent with each request; the worker answers in this language |
  286. | Approval mode | `requireApproval` in `control.json` (set from the Muse Companion panel) | off | Requests wait in `pending/` for the owner's panel approval before reaching Muse; see Relay Protocol |
  287. | Approval expiry | `MUSE_RELAY_APPROVAL_TTL_MS` env var | `1800000` (30 min) | How long an unapproved request waits before it expires with an `EXPIRED` answer |
  288. ## Relay Protocol
  289. Requests are files named `req-<ticket>.json` in the relay inbox; the ticket id is the file id (`mcp-…`):
  290. ```json
  291. {
  292. "id": "mcp-mwn78gdy9yvl2",
  293. "createdAt": "2026-11-19T06:58:41.000Z",
  294. "prompt": "What did the watchdog change in the relay hook?",
  295. "answerLanguage": "en",
  296. "workspaceRoot": null,
  297. "source": "mcp"
  298. }
  299. ```
  300. Answers are `res-<ticket>.json` in the outbox (`{ "id", "answeredAt", "answer" }`). `ask_muse_check` looks in the outbox first, then the archive (the VS Code panel may archive a response before you check), and moves an outbox answer to the archive after returning it. `source: "mcp"` distinguishes bridge requests from panel requests (`source: "panel"`).
  301. **Approval mode.** When `control.json` contains `"requireApproval": true` (toggled from the Muse Companion panel), the server writes new requests to a `pending/` folder instead of the inbox, with `"needsApproval": true`. The Muse-side hook never sees them there. `ask_muse_start` reports status `awaiting_approval`; `ask_muse_check` reports `APPROVAL_PENDING`. When the owner approves in the panel, the panel moves the file into the inbox and the request flows as usual. If the owner rejects it, the agent receives a `DECLINED` answer; if nobody approves within 30 minutes (configurable via `MUSE_RELAY_APPROVAL_TTL_MS`), the request expires with an `EXPIRED` answer. Without the panel, a request can be approved manually by moving `pending/req-<id>.json` into `inbox/`.
  302. ## Security and Privacy
  303. - The server makes **no network calls** and collects nothing; it only reads and writes JSON files in the relay folder on your own machine.
  304. - Any local process that can write to the relay inbox can ask your Muse questions — treat the relay folder as trusted local state, and keep the Muse-side worker rule: no irreversible actions (git pushes, deletions) unless the prompt explicitly asks.
  305. - Never publish your real infrastructure details (hostnames, IPs, usernames) in a fork of this README — use the placeholders.
  306. ## Limitations
  307. - Latency is minutes, not seconds; there is no streaming.
  308. - One worker lane on the Muse side: simultaneous questions are answered one at a time, in order. A single worker execution is capped at about 10 minutes by the platform; the watchdog covers failures after that.
  309. - One-shot Q&A only — no multi-turn session state is kept by the server.
  310. - Approval mode needs the Muse Companion panel to approve requests (or a manual file move from `pending/` to `inbox/`); with approval on and nobody approving, requests expire after 30 minutes.
  311. ## Troubleshooting
  312. | Symptom | Likely cause | Fix |
  313. | --- | --- | --- |
  314. | Tool returns `PAUSED` immediately | Relay paused (panel or `control.json`) | Resume the relay in the VS Code panel, or set `"paused": false` in `control.json` |
  315. | `ask_muse_check` stays `PENDING` forever | Muse-side hook disabled | Enable the `muse-relay-inbox` hook in the muse.ai chat; queued questions are answered once it runs |
  316. | First install, nothing ever answers | Relay prerequisite not set up yet (folders, SSH reachability, hook) | Work through Part B steps 1–4 |
  317. | Blocking call times out | Normal for long answers | Use the returned ticket with `ask_muse_check`, or switch to the async pair |
  318. | Host does not list the tools | Hosts load MCP config at startup | Restart the app or start a new session; re-check the JSON for trailing commas |
  319. | Server fails to start | `node` not on PATH for the host | Use the absolute path to the Node binary as `command` |
  320. | Answers land in the panel but not the tool | Relay folder mismatch | Make sure `MUSE_RELAY_DIR` matches the folder the hook/panel actually use |
  321. | Check returns `APPROVAL_PENDING` | Approval mode is on in the panel | The owner must approve the request card in the Muse Companion panel; unapproved requests expire after 30 minutes |
  322. | Agent or host warns about bot / automation-like behaviour | Bursty automated calls, repeated blocking retries after timeouts | Prefer `ask_muse_start` + `ask_muse_check`, never resubmit the same question, and enable approval mode in the panel so a human approves each request before it reaches Muse |
  323. ## Changelog
  324. ### 0.1.2
  325. - **Approval mode (human-in-the-loop)** — when `control.json` has `"requireApproval": true` (toggled in the Muse Companion panel), new requests are written to a `pending/` folder instead of the inbox and only reach Muse after the owner approves them in the panel. `ask_muse_start` reports `awaiting_approval`, `ask_muse_check` reports `APPROVAL_PENDING`, a rejection comes back as a `DECLINED` answer, and requests left unapproved for 30 minutes (configurable via `MUSE_RELAY_APPROVAL_TTL_MS`) expire with an `EXPIRED` answer. This also answers reports of hosts flagging the bridge as bot-like: calls become human-approved instead of fully automatic.
  326. ### 0.1.1
  327. - **Instant delivery via `fs.watch`** — `ask_muse` and `ask_muse_check` watch `outbox/` and `archive/` with OS filesystem events so answers return within milliseconds of Muse finishing
  328. - **Long-polling on `ask_muse_check` (`waitSecs`)** — waits up to `waitSecs` (default 25 s, range 0–600 s) before returning `PENDING`, letting coding agents wait for long tasks without hitting host tool-call timeouts or burning rapid poll turns
  329. - **Soft `PENDING` timeout on `ask_muse` + MCP progress heartbeats** — `timeoutSecs` now extends up to 3600 s, emits `notifications/progress` when a `progressToken` is supplied, and returns a non-error `PENDING` message with the ticket id on timeout
  330. - **Relay safety & cross-agent compatibility** — atomic request file writes (`.tmp-req-*.json` → rename), 10 s grace period for in-flight SSH partial response writes, ticket ID path-traversal validation, `notifications/cancelled` support, clean shutdown on stdio close, MCP tool `annotations` (`readOnlyHint`, `idempotentHint`, etc.), `additionalProperties: false` for strict schemas, and ready-to-paste setup guides for VS Code, Claude Code, Claude Desktop, OpenAI Codex CLI (TOML), Google Antigravity, Cursor, Windsurf, and Gemini CLI
  331. ### 0.1.0 — first public release
  332. - Three tools: `ask_muse` (blocking, ticket survives timeout), `ask_muse_start`, `ask_muse_check`
  333. - Fast `PAUSED` refusal while the relay is paused
  334. - Outbox-then-archive answer lookup; answers archived after delivery
  335. - Zero dependencies; single-file Node stdio server
  336. ## License
  337. Apache License 2.0 — see the `LICENSE` file in this repository. Attribution notices live in the `NOTICE` file; redistributions must preserve them (Apache License, Section 4(d)).
  338. Unofficial project. Muse and muse.ai are products of Meta; this server is not affiliated with or endorsed by Meta.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.