@zeph-to/mcp-server

Your agent calls zeph_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.

Zeph'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.

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

Setup

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

npm install -g @zeph-to/cli
zeph install

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

Claude Code (manual)

Add to ~/.claude/settings.json:

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

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

      "env": { "ZEPH_API_KEY": "ak_other_account" }

Cursor / Other MCP Clients

{
  "command": "npx",
  "args": ["-y", "@zeph-to/mcp-server"]
}

Related MCP server: MCP Discord Agent Communication

Environment Variables

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

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.

zeph_notify

Send a one-way push notification. Supports optional URL (auto-switches to link type).

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 ZEPH_DEVICE_ID)

zeph_clipboard

Copy text to the user's device clipboard.

text:           "npm install @zeph-to/mcp-server"
targetDeviceId: "dev_..."  (optional)

zeph_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 }

zeph_dismiss

Mark a specific push as read.

pushId: "push_01HX..."

zeph_dismiss_all

Clear all notifications at once. No parameters.

Returns: { dismissed: 12, badge: 0 }

zeph_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"

zeph_file

Send a text file to the user's device.

fileName:       "report.json"
content:        "{\"status\": \"ok\"}"
title:          "Build Report"  (optional, defaults to fileName)
targetDeviceId: "dev_..."       (optional)

Returns: { pushId: "...", fileKey: "...", fileSize: 42 }

zeph_session_rename

Set a custom display name for the current agent session, shown in the Zeph app's Streams › Agents list. Lets an agent label what it's working on — "Prod deploy", "Auth refactor" — so parallel sessions are easy to tell apart on your phone. Renames the session this server runs in (resolved from the listener device id + tmux session name); the name persists until changed.

alias: "Prod deploy watcher"   (1-60 chars)

Returns: { renamed: true, session: "zeph-myapp", alias: "Prod deploy watcher" }, or { renamed: false, reason: "..." } when there's no active session to rename (not running inside a zeph listener tmux session).

zeph_prompt

Ask the user to choose from 2-4 options. Blocks until response or timeout.

Requires ZEPH_HOOK_ID.

title:    "Deploy to production?"
body:     "3 migrations pending"
actions:  [{ id: "yes", label: "Deploy", style: "primary" },
           { id: "no",  label: "Cancel", style: "danger" }]
timeout:  120        (seconds, default: 120, max: 300)
fallback: "no"       (auto-select on timeout, optional)

Returns: { actionId: "yes", timedOut: false }

zeph_ask

Ask the user a question with optional quick-reply buttons and a text input field. Combines prompt (buttons) and input (text) in a single notification. Blocks until response or timeout.

Requires ZEPH_HOOK_ID.

title:       "What should we do?"
body:        "3 tests failed in auth module"  (optional)
actions:     [{ id: "fix", label: "Fix now", style: "primary" },
              { id: "skip", label: "Skip", style: "secondary" }]  (optional, 1-4)
placeholder: "Or type a custom response..."  (optional)
inputType:   "text" | "multiline"  (default: text)
timeout:     120    (seconds, default: 120, max: 600)
fallback:    "skip" (auto-select on timeout, optional)

Returns: { actionId: "fix", timedOut: false } or { value: "custom text", timedOut: false }

zeph_input

Request free-form text input from the user. Blocks until response or timeout.

Requires ZEPH_HOOK_ID.

title:       "Commit message"
body:        "Summarize the changes"
placeholder: "feat: ..."
inputType:   "text" | "password" | "multiline"
timeout:     120    (seconds, default: 120, max: 600)

Returns: { value: "feat: add clipboard sync", timedOut: false }

Client timeouts

zeph_ask, zeph_prompt, and zeph_input block until the user responds, up to their timeout (max 600s). With ZEPH_WS_URL configured the response arrives over WebSocket the instant it's submitted; otherwise the server polls. Either way the MCP request stays open the whole time. To keep the client from giving up early, the server emits a notifications/progress every 5s while waiting. Clients must either set a per-request timeout above the tool's timeout, or reset their timeout on progress notifications. Claude Code does the latter by default.

Resources

zeph://devices

Lists connected devices with online status. Use to check which devices will receive notifications.

zeph://channels

Lists channels the user owns or subscribes to. Use to find channelId for zeph_broadcast.

Usage Guide

When to use each tool

Recommended patterns

Decision gate with an escape hatch (preferred):

zeph_ask(
  title: "Tests green. Deploy to production?",
  actions: [
    { id: "deploy", label: "Deploy", style: "primary" },
    { id: "hold", label: "Hold", style: "secondary" }
  ],
  placeholder: "Or tell me what to do instead...",
  fallback: "hold"
)

Task completion notification:

zeph_notify(
  title: "Build complete: web app",
  body: "All 42 tests passed. Bundle size: 1.2MB (-3%)"
)

Decision gate in CI/deploy flow:

zeph_prompt(
  title: "Deploy to production?",
  body: "3 migrations pending. Last deploy: 2h ago.",
  actions: [
    { id: "deploy", label: "Deploy", style: "primary" },
    { id: "staging", label: "Staging only", style: "secondary" },
    { id: "cancel", label: "Cancel", style: "danger" }
  ],
  fallback: "cancel"
)

Collecting user input remotely:

zeph_input(
  title: "Commit message",
  body: "Changed: hooks.ts, input.ts, prompt.ts",
  placeholder: "feat: ..."
)

Error alert with link:

zeph_notify(
  title: "CI failed: lint errors",
  body: "2 errors in src/auth.ts",
  url: "https://github.com/org/repo/actions/runs/456",
  priority: "high"
)

When NOT to use

• Short responses the user can see immediately in the terminal

• Read-only operations (file search, code analysis)

• Every single tool call — only notify on meaningful milestones

Multi-session workflow

When running multiple AI agent sessions in parallel, use zeph_notify to signal completion so the user knows which session finished without checking each terminal.

API Key Permissions

The API key needs the following scopes:

• push:read — for zeph_list

• push:write — for zeph_notify, zeph_clipboard, zeph_dismiss, zeph_dismiss_all, zeph_file

• hook:write — for zeph_ask, zeph_prompt, and zeph_input

• device:write — for zeph_session_rename

• channel:read — for zeph://channels resource

Create an API key with the MCP preset in Settings > API Keys for the correct permissions.

Encryption

Push bodies are encrypted with AES-256-GCM. The wrapping key is derived via ECDH P-256 and synced across your own devices on first server startup so every device can read the same push. Toggle encryption in the Zeph app (Settings → Encryption); when disabled, the server sends plaintext. No configuration needed.

Threat model honesty: keys are persisted on the Zeph backend to enable cross-device sync, so this is device-shared encryption — not true end-to-end. It protects push contents from passive network observers and from a leaked database snapshot taken without the key store, but it does not protect against the Zeph backend itself (it has the keys it serves to your devices). A true E2E mode (per-device keypairs, server stores only public keys, no key escrow) is on the roadmap.

License

Apache-2.0