The @zeph-to/mcp-server allows AI agents to interact with users across their devices via the Zeph platform. Key capabilities include:
zeph_notify: Send one-way push notifications (title, body, optional URL, priority: low/normal/high/urgent, target device).
zeph_broadcast: Send notifications to all subscribers of a channel.
zeph_clipboard: Push text directly to the user's device clipboard.
zeph_file: Upload and deliver a text file (logs, reports, code snippets, etc.) to the user's device.
zeph_list: Retrieve recent notification history (up to 20), optionally filtered by type.
zeph_dismiss: Mark a specific push notification as read by its ID.
zeph_dismiss_all: Clear the entire notification feed at once.
zeph_prompt: Present the user with 2–4 choice buttons and block until they respond (requires ZEPH_HOOK_ID).
zeph_ask: Combine quick-reply buttons and a free-form text input field in a single notification, blocking until the user responds (requires ZEPH_HOOK_ID).
zeph_input: Request free-form text input (text, password, or multiline) and block until the user replies (requires ZEPH_HOOK_ID).
Resources: zeph://devices (list connected devices) and zeph://channels (list available channels).
Additional features include AES-256-GCM encryption for notification bodies and configuration via environment variables or a config file.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@@zeph-to/mcp-server Send a notification that the build succeeded."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
New here? docs.zeph.to 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.
The easiest way to set up for all agents at once:
npm install -g @zeph-to/cli
zeph installThis 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.
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" }{
"command": "npx",
"args": ["-y", "@zeph-to/mcp-server"]
}Related MCP server: agent-comm
Variable | Required | Description |
| Yes* | API key from Settings > API Keys |
| No | Hook ID (optional — only needed for interactive tools like |
| No | Target device ID (optional — only needed for interactive tools like |
| No | API base URL (default: |
| No | WebSocket endpoint for the hook-response fast path — |
| No | Set to |
| No | Override the session id attached to pushes (grouping in the app). Auto-detected from the newest Claude Code transcript when unset |
| No | Set to |
* If env vars are not set, the server reads from ~/.zeph/config.json (created by zeph install). Unresolved ${...} interpolations are also treated as unset.
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.
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)Copy text to the user's device clipboard.
text: "npm install @zeph-to/mcp-server"
targetDeviceId: "dev_..." (optional)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 }
Mark a specific push as read.
pushId: "push_01HX..."Clear all notifications at once. No parameters.
Returns: { dismissed: 12, badge: 0 }
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"Send a file to the user's device. Either filePath (a file already on disk) or
content (text you generated) is required.
filePath: "/abs/path/screenshot.png" (images, PDFs, logs — anything on disk)
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)
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.
Returns: { pushId: "...", fileKey: "...", fileSize: 42 }
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).
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 }
Ask the user a question with quick-reply buttons and a text input field. Combines prompt (buttons) and input (text) in a single notification. Blocks until response or timeout.
actions is the steering surface: pass 2–4 buttons on nearly every ask (the next-step candidates plus a safe Done-like fallback) and leave it out only when the answer is inherently free-form text — a bare text box on a "done — what next?" ask gives the phone nothing to tap.
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 }
The user can also attach screenshots or files to their answer. Those are downloaded to ~/.zeph/attachments/hook-<eventId>/ and the result gains an attachments array of absolute local paths, alongside the button or the text:
{ value: "look at this", attachments: ["/Users/you/.zeph/attachments/hook-hevt_1/screen.png"],
attachmentsNote: "The user attached 1 file(s) to this answer. Read each path above to see them.",
timedOut: false }Reading those paths is part of reading the answer. Note that hook attachments are never end-to-end encrypted — the same limitation as the question itself, since the hook route carries no sender key.
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 } — plus attachments when the user attached files, exactly as in zeph_ask above.
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.
Lists connected devices with online status. Use to check which devices will receive notifications.
Lists channels the user owns or subscribes to. Use to find channelId for zeph_broadcast.
Situation | Tool | Example |
Long task finished |
| Build complete, test results, deploy done |
Need a decision (buttons + optional free text) |
| "Tests green. Deploy?" with a custom-instruction escape hatch |
Decision from fixed options only |
| Choose deploy target, confirm destructive action |
Free-form input only |
| Commit message, env var value, description |
Share code/logs |
| Error logs, test reports, generated config |
Share snippet |
| API key, URL, shell command |
Label this session |
| Name the run "Prod deploy" so parallel sessions stay distinguishable on the phone |
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"
)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
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.
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.
End-to-end encryption is off by default and turning it on needs Zeph Pro. The switch is in the app under Settings → E2E Encryption; until you flip it, every push leaves this server in plaintext. If the account later loses Pro the server answers PRO_REQUIRED and this one drops back to plaintext for the rest of the process. No configuration either way — but the opt-in is read once at startup, so turning it on while this server is running takes effect only after a restart.
With it on, push bodies and file attachments are encrypted with AES-256-GCM. This server holds its own ECDH P-256 keypair, generated on first use and stored in ~/.config/zeph/device-keys.json — the private half never leaves the machine, and the backend stores public keys only and rejects a private-key upload. Each push is encrypted once, and its AES key is wrapped separately for every device on your account using ECDH against that device's public key.
Threat model: against a passive backend — a leaked snapshot, an operator reading the table — the stored ciphertext and wrapped keys are useless, so push contents stay private. Three limits worth knowing:
No protection from an active malicious operator. Recipient public keys come from GET /devices on that same server, unsigned and unpinned. A backend that injects a device record carrying its own key gets the message key wrapped for it, and reads everything. The Zeph app ships the counter-measure — compare device fingerprints, mark a device verified, and strict mode then wraps only for verified devices — but it defaults off, its verified list is per browser profile, and this server does not consult it: selectRecipients asks only whether a device has a public key, and whether that key is the legacy account-wide one (ADR-0007 Phase 4).
No forward secrecy. The ECDH secret for a given sender/device pair is static, so compromising either private key opens every past push wrapped for that pair.
senderPublicKey is unsigned, so a swapped one makes a push undecryptable — that direction fails closed rather than leaking.
A device that has not registered a per-device public key cannot be sent to; it is skipped, and if no device qualifies the push goes out in the clear rather than arriving as something nothing can open.
Apache-2.0
Ask the user a question with quick-reply buttons and a text input field. Combines prompt (buttons) and input (text) in a single notification. The user can either tap a button or type a response. actions is the steering surface, not decoration: pass 2–4 buttons on nearly every ask — the next-step candidates you would otherwise write as prose (next command, review, stop) plus a safe Done-like fallback. Leave actions out ONLY when the answer is inherently free-form text (a name, a path, a paragraph); a bare text box on a "done — what next?" ask leaves the phone with nothing to tap. Blocks until the user responds or the timeout is reached. Requires ZEPH_HOOK_ID environment variable. The user may also attach screenshots or files to the answer: those arrive as local absolute paths in the attachments field of the result, and reading them is part of reading the answer. NOTE: unlike zeph_notify and zeph_file, this tool is never end-to-end encrypted — the hook route it uses cannot carry the sender key — so do not put secrets in the question or expect a private answer.
| Name | Required | Description | Default |
|---|---|---|---|
| body | No | Context or instructions | |
| title | Yes | Question or request title | |
| actions | No | Quick-reply buttons (1-4). Expected on nearly every ask — the phone steers by tapping, so put the next-step candidates here (next command, review, stop) plus a Done-like fallback. Omit ONLY when the answer is inherently free-form text; never omit on a "done — what next?" ask. | |
| timeout | No | Seconds to wait for response (default: 120) | |
| fallback | No | Action ID to auto-select on timeout | |
| inputType | No | Input field type (default: text) | text |
| placeholder | No | Input field placeholder hint |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are present (readOnlyHint=false, openWorldHint=true, destructiveHint=false) but the description adds substantial context beyond them: it blocks until timeout, requires ZEPH_HOOK_ID, exposes attachment handling, and warns that the tool is never end-to-end encrypted. This goes beyond structured fields and helps the agent anticipate side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but every sentence carries critical operational or safety information: purpose, actions best practices, blocking, environment variable, attachments, and encryption. It is front-loaded with the core purpose. Slight redundancy with schema-given actions guidance keeps it from a 5.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers parameters, environment, blocking, attachments, and security, which is comprehensive for usage. However, there is no output schema, and the description does not explain the full return value (e.g., selected action id and typed text) – only mentioning that attachments arrive as paths. This leaves a gap in what the agent can expect from the result.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and schema descriptions are detailed. The description nonetheless adds meaning to the actions parameter by recommending 2–4 buttons and a safe Done-like fallback, and by explaining the principle 'steering surface, not decoration.' While some repetition exists, the extra contextual framing improves parameter understanding beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Ask the user a question with quick-reply buttons and a text input field.' It clearly distinguishes from siblings by presenting the combined prompt+input behavior and explicitly contrasts with zeph_notify and zeph_file regarding encryption. This is a clear, actionable purpose statement.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance is provided: 'actions is the steering surface, not decoration: pass 2–4 buttons on nearly every ask... Leave actions out ONLY when the answer is inherently free-form text.' It also mentions alternatives indirectly by distinguishing from notify/file and clarifies when to omit actions. This satisfies both when-to-use and when-not-to-use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Send a push notification to all subscribers of a channel. Use zeph://channels resource to find available channels.
| Name | Required | Description | Default |
|---|---|---|---|
| url | No | Optional URL to open on the device. | |
| body | No | Notification body text | |
| title | Yes | Notification title | |
| priority | No | Notification priority | normal |
| channelId | Yes | Channel ID to broadcast to (e.g., "ch_...") |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false and destructiveHint=false. The description merely restates the sending action without adding behavioral details like rate limits, auth requirements, or side effects (openWorldHint=true suggests unknown side effects). The description lacks additional context beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core purpose, and includes a practical usage hint. Every word serves a purpose with no unnecessary information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with five parameters and no output schema, the description explains the primary action and provides a resource lookup hint. However, it fails to describe return values, error conditions, or potential impacts on subscribers, leaving gaps for an AI agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema fully describes all five parameters. The description does not contribute any parameter-specific meaning, maintaining the baseline score of 3 as per rubric when schema coverage is high.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Send a push notification to all subscribers of a channel' with a specific verb and resource. It distinguishes itself from siblings like zeph_notify by the 'broadcast' nature, but does not explicitly differentiate from zeph_notify, which may cause ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes a helpful hint to use zeph://channels to find channels, implying a prerequisite. However, it provides no guidance on when to use this tool versus alternatives (e.g., zeph_notify) or scenarios to avoid, leaving usage context vague.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Copy text to the user's device clipboard. The text will appear in their clipboard history and can be pasted immediately.
| Name | Required | Description | Default |
|---|---|---|---|
| text | Yes | Text to copy to clipboard | |
| targetDeviceId | No | Target device ID. Omit to use configured default or send to all devices. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds behavioral context beyond annotations, noting that text appears in clipboard history and can be pasted immediately. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise (one sentence, 14 words) and front-loaded with the core action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with 2 parameters and no output schema, the description adequately covers the action and a key behavioral side effect.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the description does not add significant meaning beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Copy' and the resource 'text to the user's device clipboard', distinguishing it from siblings like zeph_broadcast or zeph_notify.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage (clipboard operations) but does not provide explicit guidance on when to use this tool vs alternatives or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Dismiss (mark as read) a specific push notification by ID. Use after processing a notification to clear it from the user's feed.
| Name | Required | Description | Default |
|---|---|---|---|
| pushId | Yes | Push ID to dismiss (e.g., "push_01HX...") |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide behavioral hints (readOnlyHint=false, destructiveHint=false, idempotentHint=true). The description adds that it clears from the feed, but this is already implied by 'dismiss'. No contradictions; score is adequate but not enhanced.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single concise sentence that front-loads the action and purpose. No wasted words, and the structure is efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one required parameter and annotations providing behavioral context, the description is fairly complete. It covers what, when, and how. Minor gap: could mention nondestructive nature, but annotations already cover that.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a clear description and example for pushId. The description adds no further parameter details beyond the schema, so baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (dismiss), resource (specific push notification), and action (mark as read). It distinguishes from the sibling zeph_dismiss_all by specifying 'by ID' vs. all.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says to use after processing a notification, giving clear context. However, it lacks explicit guidance on when not to use or comparison to other sibling tools, though the distinction is implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Dismiss all push notifications at once. Clears the entire notification feed.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide destructiveHint=true and idempotentHint=true. The description adds that it clears the entire notification feed, specifying scope beyond the annotation hints. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with action. Every word serves a purpose; no waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With zero parameters, annotations present, and no output schema, the description is adequate. It could mention irreversibility or confirmation, but annotations cover destructive behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, so baseline is 4. The description does not need to add parameter information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states it dismisses all push notifications at once, distinguishing it from the sibling zeph_dismiss which likely handles individual notifications. The verb 'dismiss' and resource 'all push notifications' are clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use when you want to clear the entire notification feed, and sibling names suggest zeph_dismiss is for individual dismissal. However, no explicit when-not or alternatives are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Send a file to the user's device. Pass filePath to send a file that already exists on disk — images (png/jpg/gif/webp/heic), PDFs, logs, anything. Pass content instead to send text you generated. Images render inline on the device.
| Name | Required | Description | Default |
|---|---|---|---|
| title | No | Notification title (defaults to fileName) | |
| content | No | Text content of the file. Use only for text you generated; requires `fileName`. | |
| fileName | No | File name with extension (e.g., "report.txt"). Required with `content`; defaults to the basename of `filePath`. | |
| filePath | No | Absolute path to a local file to send. Required for images, PDFs, and any other binary — never base64 a file into `content`. | |
| targetDeviceId | No | Target device ID. Omit to use configured default or send to all devices. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds behavioral context beyond the minimal annotations: images render inline, file types are enumerated, and the two modes are explained. It doesn't contain contradictions with the annotations (readOnlyHint=false, destructiveHint=false) and offers useful operational details such as the 'never base64' rule, though it doesn't cover error handling or permission requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core action, and packs essential usage guidance without any waste. Every clause contributes meaning, making it an exemplar of concision.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the main use cases and relies on the schema for parameter details. However, it omits the implicit requirement that at least one of filePath or content must be provided, and doesn't state what happens if neither is passed. Given the optional parameters, this leaves a small completeness gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description significantly enhances parameter understanding by linking filePath to existing files and content to generated text, and clarifying that filePath is required for images/PDFs/binary. The 'never base64 a file into content' warning adds crucial semantics not present in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's primary function: 'Send a file to the user's device.' It distinguishes itself from siblings like zeph_notify or zeph_clipboard by focusing on file transfer, and further clarifies two distinct modes (filePath for existing files, content for generated text). This is a specific verb+resource with a clear scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear guidance on when to use filePath vs content, including an explicit warning against base64-encoding binary files into content. It lacks an explicit comparison to sibling tools or a 'when not to use' clause, but the context is sufficient for an agent to select it for file-sending tasks.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Request text input from the user via push notification. The tool blocks until the user responds or the timeout is reached. Requires ZEPH_HOOK_ID environment variable. The user may also attach screenshots or files: those arrive as local absolute paths in the attachments field of the result, and reading them is part of reading the answer.
| Name | Required | Description | Default |
|---|---|---|---|
| body | No | Instructions or context | |
| title | Yes | Input request title | |
| timeout | No | Seconds to wait for response (default: 120) | |
| inputType | No | Input field type | text |
| placeholder | No | Input placeholder hint |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes beyond annotations by explaining the blocking nature, timeout behavior, environment variable requirement, and that attachments arrive as local paths in the result. This adds meaningful context beyond the annotation hints and does not contradict them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences with no redundancy. It front-loads the core purpose and efficiently covers blocking behavior, prerequisites, and attachment handling.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the main functional aspects: purpose, blocking/timeout, environment requirement, and result attachment handling. It doesn't describe exact return structure beyond attachments, but given no output schema and moderate complexity, it's reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so all parameters are described in the schema. The description does not add additional parameter-level semantics beyond what's in the schema, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: requesting text input from the user via push notification. It also specifies blocking behavior and attachment delivery, but does not explicitly differentiate from sibling tools like zeph_ask or zeph_prompt.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use when interactive user input is needed, and notes the prerequisite ZEPH_HOOK_ID environment variable. However, it provides no explicit guidance on when to use this tool versus sibling tools such as zeph_notify or zeph_ask.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List recent push notifications. Use this to check notification history, avoid duplicates, or reference previous messages.
| Name | Required | Description | Default |
|---|---|---|---|
| type | No | Filter by push type | |
| limit | No | Number of pushes to return (default: 5, max: 20) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the tool's safety is clear. The description adds behavioral context like 'list recent' and 'avoid duplicates' (consistent with idempotentHint=true). No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short, front-loaded sentences with no wasted words. Efficiently conveys purpose and usage scenarios.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, complete annotations (readOnly, idempotent, openWorld), and full schema, the description adequately covers purpose and use cases. No output schema needed per rules. It could mention ordering (recent) is implicit, but not required.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with detailed descriptions for both parameters (limit and type). The description adds no additional parameter information beyond what the schema provides, so baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List recent push notifications' with a specific verb and resource, and adds usage context like checking history, avoiding duplicates, or referencing messages. This distinguishes it from sibling tools like zeph_notify (send) and zeph_dismiss (dismiss).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Use this to check notification history, avoid duplicates, or reference previous messages,' providing clear scenarios. It lacks explicit when-not-to-use or naming alternatives, but the usage context is sufficiently clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Send a one-way push notification to the user's devices. Use this to inform the user about task completion, errors, or status updates. Long bodies are automatically uploaded as a file for full viewing.
| Name | Required | Description | Default |
|---|---|---|---|
| url | No | Optional URL to open on the device. | |
| body | No | Notification body text | |
| title | Yes | Notification title | |
| priority | No | Notification priority. Use "urgent" for critical alerts, "low" for background info. | normal |
| targetDeviceId | No | Target device ID. Omit to use configured default or send to all devices. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate a write operation (readOnlyHint=false) and open world effects (openWorldHint=true). The description adds that long bodies are automatically uploaded as a file, which is a useful behavioral trait beyond annotations. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences: first sentence states core purpose, second adds usage examples and a key behavioral note. No redundant words, front-loaded with important information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple notification tool (5 params, no output schema), the description covers purpose, usage, and the file upload behavior. It lacks details on return value or error cases, but is adequate for most agents given the low complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds rich context: explains priority enum usage ('urgent' for critical, 'low' for background), describes targetDeviceId behavior (omit for default/all), and notes file upload for long bodies. Adds significant value beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it sends a one-way push notification to user devices, with specific use cases like task completion, errors, or status updates. This distinguishes it from siblings like zeph_ask (two-way) and zeph_broadcast (different broadcast mechanism).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit usage context (inform about task completion, errors, status updates) but does not explicitly mention when not to use or compare with alternatives like zeph_ask or zeph_broadcast. Still provides solid guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Ask the user to choose from predefined options via push notification. The tool blocks until the user responds or the timeout is reached. Requires ZEPH_HOOK_ID environment variable.
| Name | Required | Description | Default |
|---|---|---|---|
| body | No | Detailed description | |
| title | Yes | Question or request title | |
| actions | Yes | Choice options (2-4 items) | |
| timeout | No | Seconds to wait for response (default: 120) | |
| fallback | No | Action ID to auto-select on timeout |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds significant behavioral context beyond annotations: it blocks until response or timeout, requires an environment variable, and sends a push notification. This complements the readOnlyHint=false and openWorldHint=true annotations well.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the core purpose, and no unnecessary words. Every sentence adds essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the description covers the blocking mechanism and environment requirement, it omits what happens on a response (likely returns the chosen action ID) and does not mention the fallback parameter's behavior. For a tool with no output schema, more context on return values would be beneficial.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description does not add parameter-specific information beyond what is in the schema, though it frames actions as 'predefined options'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool asks the user to choose from predefined options via push notification. It specifies the blocking behavior and timeout, which distinguishes it from siblings like zeph_ask or zeph_input.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when a user needs to select from predefined options, but it does not explicitly contrast with sibling tools or provide when-not-to-use guidance. The blocking behavior and env variable requirement are mentioned but no alternatives are suggested.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set a custom display name for THIS agent session in the user's Zeph app (the Streams › Agents list). Label what this session is working on — e.g. "Prod deploy" or "Auth refactor" — so the user can tell parallel sessions apart on their phone. Renames the current session; the name persists until changed.
| Name | Required | Description | Default |
|---|---|---|---|
| alias | Yes | Display name for this session (max 60 characters). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate a non-read-only, open-world, non-destructive operation. The description adds context that the rename persists until changed and targets 'THIS agent session' specifically, making the side effects clear. This goes beyond simply restating the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences with no fluff. The first sentence states the action, the second provides usage guidance with examples, and the third clarifies persistence. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one parameter, no output schema, and helpful annotations, the description fully covers the action, the context of use, and the durability of the change. There are no missing details that would cause an agent to misuse the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already covers the single parameter 'alias' with a description. The tool description enhances this by giving examples of valid labels and explaining the purpose behind the parameter ('Label what this session is working on'), adding meaning beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description immediately states the tool's function with a specific verb and resource: 'Set a custom display name for THIS agent session.' It clearly differentiates from sibling tools by specifying this is for renaming the current session in the user's Zeph app, not any other action like notifications or prompts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a concrete use case: labeling sessions so the user can distinguish parallel sessions on their phone, with examples ('Prod deploy', 'Auth refactor'). It doesn't explicitly state when not to use it, but since this is a unique action among siblings, the context is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v2.3.0zeph_ask1 field changedInput schema / properties / actions / descriptionPrevious value: -"Quick-reply buttons (1-4). Omit for text-only input"New value: +"Quick-reply buttons (1-4). Expected on nearly every ask — the phone steers by tapping, so put the next-step candidates here (next command, review, stop) plus a Done-like fallback. Omit ONLY when the answer is inherently free-form text; never omit on a \"done — what next?\" ask."v2.2.0zeph_file4 fields changedInput schema / properties / content / descriptionPrevious value: -"Text content of the file"New value: +"Text content of the file. Use only for text you generated; requires `fileName`."Input schema / properties / fileName / descriptionPrevious value: -"File name with extension (e.g., \"report.txt\", \"output.json\")"New value: +"File name with extension (e.g., \"report.txt\"). Required with `content`; defaults to the basename of `filePath`."Input schema / properties / filePathAdded value: +{
+ "description": "Absolute path to a local file to send. Required for images, PDFs, and any other binary — never base64 a file into `content`.",
+ "type": "string"
+}Input schema / requiredRemoved value: -[
- "fileName",
- "content"
-]zeph_session_renamev1.11.2zeph_askzeph_broadcastzeph_clipboardzeph_dismisszeph_dismiss_allzeph_filezeph_inputzeph_listzeph_notifyzeph_promptv1.11.0zeph_askzeph_broadcastzeph_clipboardzeph_dismisszeph_dismiss_allzeph_filezeph_inputzeph_listzeph_notifyzeph_promptv1.10.0zeph_askzeph_broadcastzeph_clipboardzeph_dismisszeph_dismiss_allzeph_filezeph_inputzeph_listzeph_notifyzeph_promptv1.9.2zeph_askzeph_broadcastzeph_clipboardzeph_dismisszeph_dismiss_allzeph_filezeph_inputzeph_listzeph_notifyzeph_promptv1.4.0zeph_askv0.0.0-semantic-releasezeph_broadcastzeph_clipboardzeph_dismisszeph_dismiss_allzeph_filezeph_inputzeph_listzeph_notifyzeph_promptMost tools have clearly distinct purposes (sending notifications, clipboard, file transfer, session rename). The overlapping interactive tools (zeph_prompt, zeph_input, zeph_ask) are differentiated by their exact behavior—buttons vs text vs combined—and the descriptions make this clear, though the similarity is slight.
All tools share the 'zeph_' prefix and generally use short action-oriented names like notify, dismiss, broadcast, ask. Some names are nouns (clipboard, file) rather than verbs, but the pattern is predictable and consistent in style, making it easy to infer tool purpose.
11 tools is well within the ideal 3-15 range. The server covers a focused domain of device notifications and interactions without unnecessary bloat, and each tool serves a distinct function.
The tool surface provides comprehensive coverage for the domain: sending (notify, broadcast, file), receiving (list), managing (dismiss, dismiss_all), interacting (prompt, input, ask), and session labeling. No obvious missing operations for core workflows.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
MCP server connecting AI agents to 100+ apps (Gmail, Slack, Notion, GitHub) via one-click OAuth.
An MCP memory server. One memory your agents share — across models, devices and apps.
Push notifications for AI agents - send instant iPhone notifications from any MCP client.
MCP server for building and testing AI agents with multi-model experimentation and insights.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/zeph-to/mcp-server'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
