paigy
OfficialThis MCP server turns Paigy into an agent's voice/text inbox: it pairs an AI agent to a person's phone and lets the agent ask, report, track work, and receive replies.
Pair/configure an agent identity, choose a voice, rename, re-pair, or log out.
Ask the person questions with free text or options (single, multi, ranked), optional HTML/image previews, and blocking metadata.
Send progress updates, requested messages/calls, and atomic Goal completion reports with units and reply/next-step buttons.
Create, edit, assign, defer, move, dependency-manage, cancel, reopen, and complete Goals.
Receive events addressed to the agent, answer questions, withdraw questions, acknowledge events, and wait briefly for new replies.
Read deliveries, Goals and conversations, search entries/Goals/answers, and check recent agent activity.
Check whether listening/resume is available and get the command to run a background listener.
Send bug/idea feedback to the Paigy team when the person asks or agrees.
Pairs with the native Paigy iOS app to receive calls (via CallKit), banner notifications, and reply from the lock screen, integrating the user's iPhone as an interface for agent notifications.
Allows local AI models running via Ollama to use Paigy for notifying users and awaiting replies through phone calls, banners, or push notifications.
Paigy — MCP server
A voice inbox for your AI agents. When an agent needs your input — mid-task, blocked, or done with something long-running — it can place an actual phone call and read the question aloud, text, push, or ring your phone with a banner, so you can reply by voice instead of babysitting a terminal.
Without Paigy, a long agent session means one of two bad options: sit and watch the terminal so you don't miss the moment it needs you, or walk away and come back to a task that stalled an hour ago waiting on a question you never saw. Paigy closes that gap — the moment your agent actually needs a decision, your phone gets pulled into the loop with the level of urgency that matches the moment (a silent inbox card, a quiet push, a banner, or a real ringing call), so you find out immediately instead of on your next check-in. Answer by voice or text and the reply lands back with the agent exactly like any other tool response, so it just continues — no copy-pasting, no reopening the terminal. It also pairs with the native Paigy iOS app, so a call rings through like a real phone call (CallKit) even when your phone is locked, and you can glance at or reply to anything from the lock screen.
Works with
A standard MCP server (stdio, TypeScript) — no client-specific code anywhere, verified over the raw protocol against a non-Claude client identity.
Claude Code (this repo is also the plugin + marketplace for it)
Codex CLI
Gemini CLI
Any other MCP client via standard config: Cline, Continue.dev, Zed, Cursor, Goose, mcphost — including local-model setups over Ollama, LM Studio, or llama.cpp
(The app + backend live in a separate repo.)
Related MCP server: Switchboard
Install
One line, any terminal — detects your agents (Claude Code, Codex,
Antigravity), wires Paigy into each, and pairs your phone once. Prints every
command before running it; --dry-run shows the plan:
curl -fsSL https://paigy.ai/install | shPrefer to do it by hand? Pick your client below.
Homebrew (macOS and Linux):
brew tap paigy-ai/mcp https://github.com/paigy-ai/mcp
brew trust paigy-ai/mcp
brew install paigy(brew trust is how current Homebrew opts in to a tap outside homebrew-core.)
Installs the server and its commands (paigy-mcp, paigy-listen, paigy-mcp-onboard, ...). Point your
MCP client at paigy-mcp, then run paigy-mcp-onboard once to pair your phone.
Claude Code (plugin — easiest path on Claude):
/plugin marketplace add paigy-ai/mcp
/plugin install paigyConnects automatically; the first time an agent uses it while unpaired, it'll
prompt you to pair — run /paigy-onboard (opens your browser to approve).
Claude Desktop (MCPB bundle — no terminal needed):
download paigy.mcpb,
then in Claude Desktop open Settings → Extensions and drag the file in (or
double-click it). Ask Claude to "pair with Paigy" — it runs pairing itself and
shows a code to approve on your phone. Also on
Smithery.
Codex CLI:
codex plugin marketplace add paigy-ai/mcp --ref main
codex plugin add paigy@paigy-ai
npx -y -p @paigy/mcp@latest paigy-mcp-onboardThe plugin configures the Paigy MCP server and includes guidance for calls, replies, and callbacks. Start a new Codex session after installation.
Codex CLI — direct MCP fallback:
codex mcp add paigy -- npx -y @paigy/mcp@latestThen forward Codex's thread id into the server, so each Codex conversation gets its own
Paigy identity — Codex builds the MCP server's environment from a fixed allow-list, so a
variable it isn't told to pass never reaches us. Add this line under [mcp_servers.paigy]
in ~/.codex/config.toml (paigy-harness setup does it for you):
env_vars = ["CODEX_THREAD_ID", "CODEX_SESSION_ID"](Don't pass it as a -c override on mcp add — that lands before the block is written
and Codex rejects the half-table with "invalid transport", writing nothing.)
Gemini CLI:
gemini mcp add -s user paigy npx -y @paigy/mcp@latestAny other MCP client (Cline, Continue.dev, Zed, Cursor, or a CLI that
takes the standard MCP JSON config directly) — most GUI clients take this in
their MCP settings (Cline: cline_mcp_settings.json; Continue:
~/.continue/config.json):
{
"mcpServers": {
"paigy": {
"command": "npx",
"args": ["-y", "@paigy/mcp@latest"]
}
}
}Then pair your phone:
npx -y -p @paigy/mcp@latest paigy-mcp-onboardEach session hatches its own identity automatically the first time it reaches Paigy —
no agent name to set or match. (Set PAIGY_AGENT=<name> only if you deliberately want a
client to always speak as one fixed named identity; then run onboard with the same name.)
Approve on your phone, then sign in at paigy.ai to start
receiving messages.
Heads-up for smaller/local models: the tool descriptions ask the agent to pick between a few answer shapes (confirm, options, free text) based on context — Claude follows this reliably; smaller local models may be less consistent about it. Free text always works as a fallback.
Choosing how the user answers
notify_user should ask in the shape that's fastest to answer — don't leave a
decision as free text. Pick with select (and options):
You need… | Use | Answer comes back as |
Yes/No or Approve/Deny |
|
|
Pick one of several |
|
|
Pick several |
|
|
Rank / order a subset |
|
|
A visual choice | options with an | one of the above |
An open-ended reply | no options |
|
confirm is answerable straight from the banner (Yes/No or Approve/Deny
buttons). Other paiges get banner actions See Options · Hear them · Remind me
later.
urgency is a request, not a guarantee — the user's account settings can
cap it lower. Four levels, low to high: "inbox" (silent, sits in the inbox),
"push" (a quiet passive notification, no sound), "banner" (a
time-sensitive lock-screen banner with sound), "call" (rings the phone —
use only when you genuinely need the user in the moment).
If you're about to start something long-running or blocking — the kind of thing where the user would otherwise sit and wait on you — mention once, in passing, that you can text or call them when it's done or if you hit a blocker. Don't offer it for quick tasks, and don't repeat the offer once they've answered.
Stalled work (automatic, no setup)
When a session stops and its agent owns Paigy Goals with no progress for three days, a Stop
hook holds the stop once a day and lists them, so the agent updates, finishes or cancels
each before it goes quiet. It runs paigy-stalled from @paigy/mcp (0.40.15 or later) and is
silent otherwise: nothing stalled, a stop already being continued by a hook, a reminder already
given that day, or any error. One script, the same hook in each harness's plugin:
Claude Code —
hooks/hooks.json, wired by the plugin; nothing to set up.Codex CLI —
plugins/paigy/hooks/hooks.json, wired by the Codex plugin. Codex runs a plugin's hooks only after you trust them: review and trust the Paigy hook when Codex asks.Any other harness with a Claude-style Stop hook — register
npx -y -p @paigy/mcp@latest paigy-stalledas the Stop command. It reads the hook's JSON (session_id,stop_hook_active) on stdin and prints{"decision":"block","reason":…}.
Hosts with no hooks still get the list: check_replies (which the server's instructions tell
every agent to call on startup and after a wake) returns it under stalled, and paigy-listen
carries it in the work it hands a session it wakes.
License
MIT
Available Tools
11 toolscheck_activityRecent agent activityARead-only
Read your person's agents that contributed in the last 24 hours, newest first: at most 30 agents and their five most recently touched Goals, with their latest entry headline and time. Use get_goals to read a Goal and its other contributors before starting overlapping work. Read-only; no arguments.
Inputs: no named parameters.
configureSet up this agentADestructive
Set this agent up with Paigy — call it FIRST, before contact, and any time you're unsure who you are. One call does whatever the situation needs: NOT SET UP → if this machine holds a device credential (the user ran the Paigy desktop app or harness) it hatches an identity INSTANTLY, no code and no approval; otherwise it starts the code ceremony. ALREADY SET UP → returns your current identity and the two things left to decide, renaming it or logging out. TOKEN NO LONGER VALID → says so, then re-pairs. Pass { name, voice } to choose who you are when hatching, or to RENAME yourself when already set up (pick your own; voices: rachel, george, jessica, brian, lily). Safe to call any time: idempotent, and it never writes settings.
THE CODE CEREMONY does not open a browser; the user enters the code in the Paigy app (or scans qr). A result with { user_code, device_code, qr, user_message } has already started polling for approval in the background: you MUST immediately print the user_message (the bare code) to the user, AND in that same turn call configure again with that device_code to collect the result. It returns the moment the user approves; on { status:'pending' } call again to keep waiting; on { status:'awaiting_confirmation' } (E2EE) show the bare user_message verify code and call again to finish. Every result's first text block states the code plainly.
On { status:'paired' }, or whenever it returns enable_command, ALWAYS follow the enable_prompt: PRINT that command for the user to run, so Paigy's tools stop prompting each time. You cannot apply it yourself (it writes your own permission allowlist, which hosts block as privilege escalation), so print it, don't wait for it, and carry on.
LOG OUT with { logOut: true }: it logs out THIS agent only — its token is revoked server-side and its local entry removed. Other agents and this device's credential are untouched, and a later configure re-hatches instantly while the device credential exists. Disconnecting the device itself is not an agent tool.
Inputs: name, scope, voice, logOut, +1 more.
contactContact the personADestructive
Send to and receive from the person: completions, updates, questions, answers to questions addressed to you, withdrawals, and what a question holds up. Every Goal named must exist: an unknown one refuses the whole contact. Each item applies on its own: read results, where a failed one names why.
HOW TO ASK:
One question per object in
questions, so each is answered on its own.goalIdnames the existing Goal it is about (create one with manage_goals first); the answer comes back there.They asked you to call?
userExplicitlyRequested:"call";workItBlocksrings when blocked.No while-loops. While any Call is open, even one your question joined from their items, keep receiving through empty windows; otherwise stop at one: the answer reaches you on the Goal. Yield only with a listener or wakeup.
One question, one row: never re-send one still waiting; take back one that no longer matters with
withdrawQuestionIds.Read the Goal before asking; never re-ask what was answered or shipped.
repliedmeans they chose no option: it is still yours to settle.Give options when you have them. Each label names its choice in full (never "Option 2"); never add "Other".
A diagnosis says when, why and how it happens, then proposes one fix.
Give a report its
reply: one line in THEIR voice for THAT report, so you learn whether they verified it or only received it. Required when it is delivered or its Goal is done.
LENGTH: the question, message or answer is the one point, at most 80 characters; the rest goes in units, one idea each. Over a cap is refused by name and nothing is sent. Several results are several updates.
UPDATES ask nothing. One reaches the person only when they asked for it, it answers something they said, or its Goal is done; else it is kept as progress. One that reaches them joins an open report card or a live call.
RECEIVING: contact({}) waits ~45 s; contact({wait:false}) returns events at once. Confirm the ones you handled with contact({ackEventIds}).
Inputs: wait, answers, updates, questions, +5 more.
get_deliveryRead a deliveryARead-only
Read a Delivery in full: its whole ask, units, options and answers, plus current callState and callOutcome for a Call. For a Call, transcript: true adds what was said: each spoken line in order, who said it, and when from pickup, a page at a time. A line from the room, not the person, is marked room. Any agent of the same account may read it; another account is not disclosed. Reading never acknowledges or resends anything. Use this after a call or when receive names a Call you are waiting on.
Inputs: deliveryId (required), after, transcript.
get_goalsRead GoalsARead-only
Read one to ten Goals by goalIds, returned in the same order under goals (a read never puts you on them). history applies to every requested Goal. A refused read fails the call with its original refusal; no partial result is presented as complete. Each Goal includes its ten most recent other contributors (names, latest entry headlines and times), outcome, state, revision, progress, blockers, the conversation on it (each question with its options and what was decided), next, the one step to take, and more, where to read further. A question in that conversation reads open (nothing yet), answered (a choice was made, and answer carries it), replied (they said something and the read settled the question on their words — NO option of yours was chosen, and the words are the reply line beside it, so read that before you act), or closed. The conversation carries everything the person said, every open question and your newest entry; your older entries are left out and counted — history: true reads every entry in full. Every Goal of your person is readable, whichever of their agents owns it; another account's Goals are not disclosed.
Inputs: goalIds (required), history.
helpPaigy guideARead-only
Start here: how to use Paigy, in full — pairing, listening, receiving, asking, updates and completions, Goals, organizing work, and calls. Pass a topic for one section. Read-only; needs no setup.
Inputs: topic.
launchLaunch a sessionADestructive
Start a new agent session on one of your person's computers: their host runs it as it runs a launch from their phone. Only what the person approved: a board card they answered, or else ask them first, one question on the Goal it is for naming the session, its role, model and mode; pass that question's questionId as approvalQuestionId. brief becomes the session's first Goal, under parentGoalId when given. Name a workspace the host granted or the repo. mode is bypass unless ask. A refusal says why. Returns sessionId, the agent, the brief's goalId and next.
Inputs: name (required), brief (required), harness (required), approvalQuestionId (required), +6 more.
listenAm I listeningARead-only
Am I listening for answers, and can Paigy resume this session? Takes no arguments. Returns status listening for harness delivery or a running listener with a ready wake adapter; receiving means a process is running but automatic resume is not confirmed (read its wake error or watch its output); unpaired means call configure; start gives the exact command to run NOW with your harness's Monitor tool (not a background command, which speaks only when it exits). Start it once. Codex queues into CODEX_THREAD_ID automatically when its CLI supports queue; PAIGY_ON_WAKE overrides it. A successful queue is not evidence the agent handled the answer: receive with contact({ wait: false }) and read the relevant Goal, then respond with contact. This tool never subscribes or starts anything itself.
Inputs: no named parameters.
manage_goalsManage GoalsADestructive
Create, edit, assign, organize or close work. SHAPE IT AS PROJECTS WITH STEPS: create a project under its area (parentGoalId; a top-level Goal with children is an area), then each part as its child Goal, so the person sees N of M steps. Move a flat or orphaned Goal of yours into that shape when you touch it; a flat Goal is valid. Every change here changes Goals; answering, withdrawing or asking Questions stays in contact. Each change applies independently: a refused one names why (results[i].error, e.g. goal_revision_conflict, goal_children_open, goal_not_found) and the rest still apply, so read every result: a partial result is never a complete success. Kinds: complete (goalId, message capped at 50 characters, units, reply, optional next-step options {label, hint}) closes and reports atomically, exactly as contact.completions; create (title, outcome, ownerId, parentGoalId, sourceEntryIds) returns the new Goal's id in results[i].goalId, in the order requested, to use in later calls (an outcome is one paragraph, at most 500 characters: split more into child Goals with parentGoalId); edit (title and/or outcome); state (open, completed, canceled); assign (ownerId); defer (until: the Goal waits until then and its owner is woken when it passes; null takes it back); move (parentGoalId, or null for a root: only this Goal moves); dependency (add or remove: goalId waits on dependsOnGoalId to start or to complete). A Goal cannot be completed while its required children or dependencies remain open: finish or move them first. Finishing the children does not prove the parent's own work is done. An edit applies at the version you last read: if someone changed the Goal since, it is refused as goal_revision_conflict, so read it again (get_goals) and reconsider. You may change any Goal of your person; a change puts you on it. Returns ok (every change applied), results per change (applied or failed), and goals, each changed Goal's id, state, title, outcome and revision.
Inputs: changes (required).
searchSearch historyARead-only
Search your person's history across all of their agents: Entries (what anyone said or wrote, typed or spoken on a call), Goals (by title and outcome) and replies -- the person's answers, acknowledgements and deferrals (type answer; found by their summary, by the question or report they reply to, or by the words that gave them). query is words to look for; records sharing more of its words rank first, and exact names work. types narrows it to entry, goal and/or answer (default: all three). goalId searches under one Goal: its Entries, the replies to its items, and it and its immediate children. limit is matches per type, 1 to 20 (default 8). Read-only. Each match carries its whole saved words, its ID and its links (a reply carries its kind -- answered, acknowledged or deferred -- whether it is closed (a deferral is not), its summary in under ten words, its question or report, the choice made and the Entries that support it); omitted counts what matched but was left out, so narrow the words or add a goalId to see it. Nothing found is not proof that nothing exists; a refused search says why. Sealed (encrypted) content is never searched or returned.
Inputs: query (required), limit, types, goalId.
send_feedbackSend feedback to PaigyADestructive
Send feedback about Paigy itself (a bug report, an idea) straight to the Paigy team. Send it only when the person asked you to, or agreed when you offered: it goes to Paigy, never to the person, and nobody answers it here. Not for your work or a question for the person: use contact for those. Returns whether it was stored.
Inputs: text (required), kind, title.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 11 tools
The tool boundaries are fuzzy in important places: `contact` covers asking, updates, completions, receiving, and acknowledgements, while `manage_goals` can also complete Goals 'exactly as contact.completions.' `contact` also reads results and interacts with Deliveries, while `get_delivery` reads a Delivery in full, so agents may have to guess which tool is authoritative for several workflows.
All names use lowercase snake_case, which helps, but the set mixes bare verbs/nouns (`contact`, `listen`, `search`, `launch`, `help`, `configure`) with verb_noun names (`manage_goals`, `get_delivery`, `get_goals`, `send_feedback`). The convention is readable but not predictable enough for a 5.
Eleven tools is well within the 3-15 range and seems appropriate for a platform covering agent setup, messaging, goals, search, launches, deliveries, and feedback. No tool count issue is apparent from the surface.
The set covers the main lifecycle: setup, listening/receiving, contact, goal management, search, launching agents, deliveries/calls, activity, help, and feedback. Minor gaps remain, such as no explicit call initiation/control and no general list-goals operation outside search/activity/get-by-id workarounds.
Maintenance
Related MCP Connectors
Calls your phone when an AI task finishes or is blocked — hear it, say what's next.
Your agent asks you a question on your phone, waits for the answer, then resumes.
Let your AI agents ask you for decisions and get your answers back, from your phone or the web.
Your agent asks you before it acts. You answer with one tap on your phone. Human-in-the-loop.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceHuman-in-the-loop approvals and notifications for AI agents via WhatsApp. Enables Cursor, Claude Code, and autonomous AI agents to reach users away from their computers.112 npmISC
- AlicenseNot gradedqualityDmaintenanceA human-in-the-loop input gateway for AI coding agents that lets agents pause mid-task and ask questions via a native Android app, designed for away-from-desk workflows.MIT
- AlicenseNot gradedqualityBmaintenanceEnables agents to pause and ask a human for a decision, then resume with the answer, via a self-hosted SQLite-backed MCP server with console or phone interfaces.1AGPL 3.0

tmgr-notifyofficial
AlicenseBqualityBmaintenanceEnables AI agents to reach users on their phone through push notifications, and to raise urgent, escalating alarms that fall back to a voice call until someone acknowledges. It also ships hooks that notify users automatically when Claude Code or Codex needs input or finishes a turn.39 npmMIT