Hwip

@hwip/mcp-server

Your agent calls `hwip_ask`; the question lands on your phone as buttons + a text field; your reply comes back into the same tool call and the agent keeps going.

Hwip's MCP server is the agent side of that round trip — plus one-way notifications, clipboard, files, and channel broadcasts, all over the Model Context Protocol. Works with Claude Code, Cursor, Windsurf, Gemini CLI, and any MCP client.

Your agent calls hwip_ask → the question hits your phone → you tap Deploy → the call returns and the agent ships.

Part of the Hwip toolchain: @hwip/cli (installer, push CLI, tmux remote control) · hwipit/plugin (Claude Code plugin bundling this server) · the Hwip app on your phone.

New here? docs.hwip.app walks the whole setup — one command on your machine, the app on your phone, and a restart. The reference below assumes that is already done.

Setup

The easiest way to set up for all agents at once:

npm install -g @hwip/cli

hwip install

Needs Node 18.17 or later. On Node 22 or later hwip_ask hears the answer over a WebSocket the moment it is given; on older Node it polls, and the server says so on stderr at start.

This saves credentials to ~/.hwip/config.json and configures your agents automatically. The MCP server reads from this file — no env vars needed. Install globally so hwip cc (phone-driven sessions) works and hooks skip an npx cold-start; npx @hwip/cli install is a notifications-only alternative.

Claude Code (manual)

Install the server once, so each session starts the hwip-mcp binary directly instead of resolving the package through npx first:

npm install -g @hwip/mcp-server

Add to ~/.claude/settings.json:

{

"mcpServers": { "hwip": { "command": "hwip-mcp" } } }

Without a global install, "command": "npx", "args": ["-y", "@hwip/mcp-server"] works too; it only starts slower, because every session resolves the package first.

No env block needed: credentials come from ~/.hwip/config.json (written by hwip install). Add env vars only to override the file — e.g. a second account:

      "env": { "HWIP_API_KEY": "ak_other_account" }

Cursor / Other MCP Clients

{

"command": "hwip-mcp" }

(after npm install -g @hwip/mcp-server, or "command": "npx", "args": ["-y", "@hwip/mcp-server"] without it.)

Environment Variables

\* If env vars are not set, the server reads from ~/.hwip/config.json (created by hwip install or hwip login). Unresolved ${...} interpolations are also treated as unset.

~/.hwip/config.json

A file that is not used because it is not valid JSON or UTF-8 text, or cannot be read, is named on stderr ("…so it is being ignored") even when HWIP_API_KEY is set: its hookId and deviceId are dropped with it.

Without an API key the server stops at start and says why: the file does not exist, it is not valid JSON, it is not valid UTF-8 text (such a file is not used at all, as in the cli), it has no apiKey, or it was ignored (below).

The file holds the key and says where the key is sent, so the server checks it before reading, by the same rule as the cli:

• Another user owns it, or anyone can write it (mode 002): the file is ignored — HWIP_API_KEY still works — and a line on stderr says so. Run chmod 600 ~/.hwip/config.json.
• The group can read or write it, or others can read it: used, with a warning. The server only reads the file; hwip login is what narrows it to 0600.
• A symlinked file (a dotfiles checkout) is judged by what it points at.
• A file that is not valid JSON, or cannot be read, may hold the baseUrl your key belongs to (staging, self-hosted), so a key from HWIP_API_KEY is not sent to the default API in its place: the server stops at start, names the file, and goes ahead once HWIP_BASE_URL says where the key goes. (A file ignored for its mode is not trusted for a base URL either, and the default stands.)
• A key from the file does not follow an address from the environment. The key in ~/.hwip/config.json belongs to the addresses the file says (baseUrl, else the default API). If HWIP_BASE_URL names another origin, the server stops at start, naming both origins and no more, and goes ahead once HWIP_API_KEY is set too (a key you gave with the address) or the variable is unset or on the same origin. The deprecated HWIP_WS_URL is held to the same rule — with the file's key it is used only for the default socket's origin, otherwise it is skipped with a line on stderr (hwip_ask polls) — and putting wsUrl in the file is the way to name another socket.
• wsUrl has to be a ws:// or wss:// URL without a space or #fragment; one that is not is ignored with a warning (the default socket, or polling). ws:// and http:// to a host other than this machine work, with a warning that the key travels in the clear.

Limits on what the server reads

A reply from the API is read only up to 8 MiB (an error body, 64 KiB), counted on the bytes that arrive rather than on Content-Length; a file download, up to 1 GiB. Past that the call fails with RESPONSE_TOO_LARGE or FILE_TOO_LARGE. The message the API words for an error reaches the agent as one line of at most 300 characters, control characters turned into spaces, and an error code that is not made of letters, digits and _.:- becomes UNKNOWN_ERROR.

Tools

Push titles are automatically prefixed with the project directory name — myapp · Build complete — so the phone feed stays scannable when several sessions push at once.

hwip_notify

Send a one-way push notification. An optional url opens on the device; the push stays a notification (a long body goes as a response.md file push instead).

title:          "Build complete"

body: "All 42 tests passed" url: "https://github.com/org/repo/actions/runs/123" (optional) priority: "low" | "normal" | "high" | "urgent" targetDeviceId: "dev_..." (optional, overrides HWIP_DEVICE_ID)

hwip_clipboard

Copy text to the user's device clipboard. At most 96 KiB, measured as the server does (the text as JSON, UTF-8); longer text is refused with BODY_TOO_LONG before it is sent — use hwip_file with content. Not end-to-end encrypted (see Encryption): do not use it for secrets (keys, tokens, passwords); use hwip_notify or hwip_file for those.

text:           "npm install @hwip/mcp-server"

targetDeviceId: "dev_..." (optional)

hwip_list

List recent push notifications.

limit: 5         (1-20, default: 5)

type: "note" (optional filter: note, link, file, clipboard, hook)

Returns: { pushes: [...], total: 5, hasMore: true }. A body is cut to 100 characters. An end-to-end encrypted push shows encrypted: true and no title or body — only the user's devices can open it.

hwip_dismiss

Mark a specific push as read.

pushId: "push_01HX..."

hwip_dismiss_all

Clear all notifications at once. No parameters.

Returns: { dismissed: 12, badge: 0 }

hwip_devices · hwip_channels

Read-only lookups for the ids other tools take: hwip_devices returns { devices } (a deviceId is hwip_notify's targetDeviceId), hwip_channels returns { channels } (a channelId for hwip_broadcast). The same lists are the hwip://devices and hwip://channels resources, for clients that read resources.

hwip_broadcast

Send a notification to all subscribers of a channel.

channelId: "ch_..."

title: "Deploy complete" body: "v2.1.0 is live" url: "https://..." (optional) priority: "normal"

hwip_file

Send files to the user's device. One of filePath (a file already on disk), filePaths (several files on disk) or content (text you generated) is required.

filePath:       "/abs/path/screenshot.png"  (images, PDFs, logs — anything on disk)

filePaths: ["/abs/a.png", "/abs/b.png"] (up to 20, sent together; not with filePath or content) content: "{\"status\": \"ok\"}" (text only; requires fileName) fileName: "report.json" (required with content; defaults to basename of filePath) title: "Build Report" (optional, defaults to fileName, or "N files") targetDeviceId: "dev_..." (optional)

Images are delivered with their real mime type and render inline on the device. Never base64 a binary file into content — pass filePath and the server reads the bytes off disk.

Several files asked for at once (screenshots of one change, a set of logs) go in one call with filePaths: they arrive as one message, five to a push (the server's li