MCP Server
Usage Guide
Which tool to reach for, with patterns worth copying and cases worth skipping.
When to use each tool
| Situation | Tool | Example |
|---|---|---|
| Long task finished | zeph_notify | Build complete, test results, deploy done |
| Need a decision, buttons plus optional free text | zeph_ask | "Tests green. Deploy?" with a custom-instruction escape hatch |
| Decision from fixed options only | zeph_prompt | Choose a deploy target, confirm a destructive action |
| Free-form input only | zeph_input | Commit message, env var value, description |
| Share code or logs | zeph_file | Error logs, test reports, generated config |
| Share a snippet | zeph_clipboard | API key, URL, shell command |
| Label this session | zeph_session_rename | Name the run "Prod deploy" so parallel sessions stay distinguishable on the phone |
Patterns worth copying
Decision gate with an escape hatch — the preferred shape, because it lets the user answer something you did not anticipate:
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 a CI or 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 a 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 these
- Short responses the user can see immediately in the terminal.
- Read-only operations such as file search or code analysis.
- Every single tool call. Notify on meaningful milestones only.
Multi-session workflow
When running several agent sessions in parallel, use zeph_notify to signal completion so the
user knows which session finished without checking each terminal.