@blipr/mcp

@blipr/mcp

Previously published as @applogico/blipr-mcp. That package is deprecated; new releases ship as @blipr/mcp. Update your MCP config to npx -y @blipr/mcp.

An MCP server that lets AI agents send Blipr push alerts to your phone. Your agent finishes a long task, breaks a build, needs approval, or gets stuck — and it pages you. It can also ask you a question and block until you answer, for human-in-the-loop approval gates.

It's a thin stdio client: your MCP host (Claude Code, Cursor, …) launches it, the agent calls a tool, and this process makes one outbound HTTPS POST to your Blipr server. No inbound socket, nothing to host.

Claude Code ──stdio──► @blipr/mcp ──POST /blip/<topic>──► blipr.dev ──APNs──► 📱

Setup

No install needed — npx fetches it on demand. Point it at a Blipr server (blipr.dev or your own self-hosted instance).

Claude Code

claude mcp add blipr \
  --env BLIPR_URL=https://blipr.dev \
  -- npx -y @blipr/mcp

Cursor / Claude Desktop / any MCP host (JSON)

{
  "mcpServers": {
    "blipr": {
      "command": "npx",
      "args": ["-y", "@blipr/mcp"],
      "env": {
        "BLIPR_URL": "https://blipr.dev"
      }
    }
  }
}

Pick a topic (per project, not global)

Every blip goes to a topic, and each project should use its own, so alerts from different projects land separately on your phone. The topic for a call is resolved in this order:

1. topic tool argument — the agent passes it on the call. Always wins.
2. .blipr-topic file — per-project default. Put the topic name on the first line of a .blipr-topic file in the project root; the server picks up the nearest one from its launch directory upward (# lines are comments).
3. BLIPR_TOPIC env var — global fallback, kept for backward compatibility. Avoid it when one machine hosts several projects: a global default makes every project ping the same topic.

echo my-project-alerts > .blipr-topic

Then subscribe to the same topic (my-project-alerts) in the Blipr iOS app, and you'll get the agent's pushes on your phone. On blipr.dev that subscribe, made while signed in, is also what creates the topic, so do it before the agent's first blip: publishing to a topic that does not exist returns 404. A self-hosted server still creates the topic on the first publish.

Configuration

Tools

send_alert

Send a push notification. Parameters:

• message (required) — the alert body.
• title — short bold title.
• topic — topic to publish to; pass it explicitly (falls back to .blipr-topic, then BLIPR_TOPIC).
• priority — 1 silent · 2 low · 3 default · 4 high (plays a sound, respects Focus) · 5 critical (breaks Focus).
• tags — emoji shortcodes, e.g. ["warning"].
• click — URL opened when the notification is tapped.
• markdown: render the body as Markdown (bold, italics, links, code). Off by default.

send_critical

A priority-5 page for things that genuinely can't wait. Bypasses silent/Focus when the Blipr app has Apple's Critical Alerts entitlement enabled; otherwise it's delivered as time-sensitive. Also takes markdown.

ask — human-in-the-loop yes/no (blocks)

Send a yes/no question to your phone and block until you tap an answer, then return it. This is an approval gate: the agent calls it before doing something consequential or irreversible and waits for your decision instead of guessing.

• message (required) — the yes/no question.
• title — short bold title.
• topic — topic to publish to; pass it explicitly (falls back to .blipr-topic, then BLIPR_TOPIC).
• priority — defaults to 4 (high) since it needs an answer.
• tags — emoji shortcodes, e.g. ["question"].
• markdown: render the body as Markdown (bold, italics, links, code). Off by default.
• timeout_seconds — how long to wait for your answer (default 120).

Returns { responded, approved, value, message_id, topic }. Branch on approved — it is true only when you tapped Yes, and false on No, a timeout, or an error, so a refusal or non-answer can never be misread as a go-ahead. On a timeout you get { responded: false, approved: false, reason: "timeout", message_id, topic }. If it times out (or your MCP client cancels the call), you can still answer for ~30 min — pass the returned message_id to check_reply to resume.

Under the hood it publishes with reply: "binary", captures the message id from the publish response, then long-polls GET /blip/<topic>/<id>/reply?wait=… until you answer or the timeout budget runs out.

request_ack — require acknowledgement (blocks)

Send a message that you must acknowledge, and block until you tap "Acknowledge". Use it when the human has to see and confirm something before the agent continues. Same parameters as ask; publishes with reply: "ack".

Returns { responded, message_id, topic } plus replied_at when acked, or { responded: false, reason: "timeout", … }. As with ask, on a timeout you can resume later with check_reply and the returned message_id.

check_reply — resume / poll an earlier ask or request_ack

Look up whether you've replied to an earlier ask/request_ack — handy if the blocking call timed out or your MCP client cancelled it. Pass the message_id (and topic) it returned; non-blocking by default, or set wait_seconds to briefly long-poll. Returns { responded, value?, replied_at? } (value is "yes" / "no" / "ack"). Replies are kept ~30 minutes after the original message was sent.

Example prompts

"Run the migration, and send_alert me when it's done — priority 4 if it fails."

"If the nightly backup fails, send_critical me with the error — that one can't wait."

"Before you DROP the production table, ask me to approve it — only proceed if I answer yes."

A concrete approval-gate flow:

Agent: about to delete the prod `events` table → calls
       ask("Delete prod `events` table (12M rows)? This cannot be undone.")
        … blocks; your phone buzzes …
You:   tap "No"
Agent: ask returns { responded: true, approved: false, value: "no" } → aborts the deletion.

Develop

npm install
npm run build      # → dist/index.js
npm test           # vitest: unit (publish, config) + in-memory MCP integration
BLIPR_URL=https://blipr.dev BLIPR_TOPIC=demo node dist/index.js   # stdio

License

MIT © Applogico LLC. This is the open client adapter; the Blipr server is distributed as a container image.