@briefroom/mcp

@briefroom/mcp

日本語版 README: README.ja.md

briefroom stdio MCP server — expose the briefroom CLI to Claude Code, Codex, Cursor, and other agents so they can deploy HTML and pull reviewer comments without spawning shells themselves.

• Deploy in one call — zip a local directory, upload it, get a share URL back.
• Pull reviewer feedback — grab comments from the browser as AI-agent-ready Markdown.
• List your rooms — enumerate your existing deploys with their share URLs.

Add it to Claude Code (one command)

claude mcp add briefroom -- npx -y @briefroom/mcp

Set BRIEFROOM_TOKEN in your environment (create a PAT at briefroom.net/dashboard/settings/tokens) or run npx @briefroom/cli login once to store it in the OS keychain.

What it gives your agent

Tool	What it does
deploy_html	Zip a local directory and upload it to briefroom. Returns a share URL.
get_feedback	Fetch reviewer comments for a share URL as AI-agent-ready Markdown (default) or JSON.
list_deployments	List rooms owned by the current PAT with their latest deploy and share URL.

Internally each tool runs @briefroom/cli as a child process (process.execPath → node <cli>/dist/index.js), so behavior stays identical to the CLI and both packages evolve together.

Install

npm i -g @briefroom/mcp
# or use it via npx (recommended for .mcp.json)

Configure

Config file location and env interpolation semantics differ per client. Pick the block that matches yours.

Claude Code

Put .mcp.json at your project root. Claude Code expands ${VAR} against the launching shell's environment:

{
  "mcpServers": {
    "briefroom": {
      "command": "npx",
      "args": ["-y", "@briefroom/mcp"],
      "env": {
        "BRIEFROOM_TOKEN": "${BRIEFROOM_TOKEN}"
      }
    }
  }
}

Or register it via the Claude Code CLI:

claude mcp add briefroom -- npx -y @briefroom/mcp

Codex CLI

Codex reads MCP server definitions from ~/.codex/config.toml (see the Codex CLI docs):

[mcp_servers.briefroom]
command = "npx"
args = ["-y", "@briefroom/mcp"]
env = { BRIEFROOM_TOKEN = "hak_your_pat_here" }

Or omit the env block and let the MCP process inherit BRIEFROOM_TOKEN from the shell that launched Codex.

Cursor

Cursor does not expand ${VAR} inside env blocks in its MCP config, so you have to decide up front how to supply the PAT. Options, in preference order:

Option A — user-wide config with a literal PAT (keeps PAT out of any repo):

~/.cursor/mcp.json:

{
  "mcpServers": {
    "briefroom": {
      "command": "npx",
      "args": ["-y", "@briefroom/mcp"],
      "env": { "BRIEFROOM_TOKEN": "hak_your_pat_here" }
    }
  }
}

The file lives in your home directory, so there's no path for it to end up in a project's git history.

Option B — inherit from the parent shell (no PAT in any config file):

Either ~/.cursor/mcp.json or the project's .cursor/mcp.json, with no env block:

{
  "mcpServers": {
    "briefroom": {
      "command": "npx",
      "args": ["-y", "@briefroom/mcp"]
    }
  }
}

With env omitted, the MCP process inherits your shell's environment. If you've run npx @briefroom/cli login, the CLI reads the PAT from the OS keychain. Alternatively, launch Cursor from a shell that has BRIEFROOM_TOKEN=hak_... exported.

Not recommended — project .cursor/mcp.json with a literal PAT:

If you must put a literal PAT in the project's .cursor/mcp.json, add that file to .gitignore and never commit it. Leaked PATs in public repos are a well-known incident class — prefer options A or B above. Rotate the PAT at briefroom.net/dashboard/settings/tokens if you commit one by accident.

Other stdio-MCP clients (Cline / Roo Code / Continue / …)

The stanza above works verbatim, but consult your client's docs for ${VAR} interpolation semantics and PAT-in-file safety before adopting it — the same "user-wide file or env inheritance" preference order applies.

Authentication

Two options — pick whichever fits your setup:

• BRIEFROOM_TOKEN env var (recommended for .mcp.json): create a PAT at briefroom.net/dashboard/settings/tokens and pass it through the env block above.
• OS keychain (recommended for local dev): run npx @briefroom/cli login once. The MCP server picks up the same credential automatically.

BRIEFROOM_TOKEN takes precedence over the keychain when both are set.

get_feedback also works without any credentials — comments on a share URL are public API. Auth only unlocks owner-only fields.

Configuration reference

Env var	Purpose	Default
BRIEFROOM_TOKEN	Personal Access Token. Skips the keychain lookup.	(unset)
BRIEFROOM_API_URL	Point the CLI at a different backend (dev / staging).	https://briefroom.net

Tool reference

deploy_html

{
  "path": "./mockups",        // required — directory to deploy
  "room": "demo-a",           // optional — room slug: ascii identifier of the room to redeploy into
  "name": "企画書 v2",         // optional — room display name, 1-100 chars, any language
  "expires": "7d",            // optional — "7d" | "30d" | "never" (also updates the existing link on redeploy)
  "new": false,               // optional — start a brand new room
  "password": "s3cret",       // optional — password-protect the link (Pro+ plans; passed to the CLI via env, never argv)
  "visibility": "unlisted"    // optional — "unlisted" | "password_protected"; "unlisted" clears an existing password
}

Returns the raw CLI JSON (share_url, room_id, version_number, visibility, …).

Three identifiers that are easy to confuse:

Field	What it is
name	Display name shown on the dashboard and in the viewer. Any language. Set it on the first deploy; on a redeploy it updates the room name only when passed explicitly (omit it to keep the current name).
room	Room slug — an ascii kebab-case identifier used only to find the existing room to redeploy into. Never part of the share URL.
share URL	Always auto-issued with a random token (/s/<token>). Not derived from name or room.

get_feedback

{
  "share": "https://briefroom.net/s/aB3xQ2mK9pNvR4", // URL or bare token
  "status": "all",             // optional — "open" | "resolved" | "all"
  "since": "2026-07-01T00:00Z",// optional ISO 8601 for delta pulls
  "format": "prompt",          // optional — "prompt" (Markdown) | "json"
  "locale": "ja"               // optional — "ja" | "en"
}

Returns Markdown by default, formatted so an agent can paste it straight back into context.

list_deployments

{
  "limit": 20,     // optional — 1-100, default 20
  "archived": false
}

Returns the raw /api/v1/rooms JSON.

Debugging

Log lines are written to stderr only — stdout is reserved for JSON-RPC. To see what the server does:

BRIEFROOM_TOKEN=$YOUR_PAT npx @modelcontextprotocol/inspector \
  npx -y @briefroom/mcp

Point the inspector at a running backend with BRIEFROOM_API_URL=http://localhost:3000 when developing against a local dev server.

Roadmap

• resolve_comment — pending backend PAT support on the comment PATCH endpoint.
• Streamable HTTP transport for hosted usage.

Contributing

Issues and pull requests are welcome at github.com/briefroom/mcp. The public repo mirrors the internal source of truth in the briefroom monorepo; changes land upstream first, then are exported here.

Local dev inside this repo:

npm install
npm run build
npm test

License

MIT © Talent Cloud, Inc.