Paigy AI MCP

What paigy-ai/mcp MCP server does

The paigy-ai/mcp MCP server gives an agent a way to contact its user during work that may block or run for a long time. The agent can request a response through a phone call, text message, push notification, or a phone banner. The user can answer by voice or text, and the response is returned to the agent as a normal tool result so the task can continue.

Notifications have four requested urgency levels: inbox, push, banner, and call. Inbox items remain silent, push sends a passive notification, banner adds a time-sensitive lock-screen notification with sound, and call rings the phone. Account settings can reduce the requested urgency, so these levels are not guarantees.

The paigy-ai/mcp MCP server also supports structured questions. Agents can request confirmation, a single choice, multiple choices, or a ranked selection. Options may include HTML or image previews. Open-ended questions fall back to free-text replies.

How it works

The server uses the standard MCP protocol over stdio and does not require client-specific implementation. It is documented for Claude Code, Claude Desktop, Codex CLI, Gemini CLI, Cline, Continue.dev, Zed, Cursor, Goose, mcphost, and local-model configurations using Ollama, LM Studio, or llama.cpp.

A session pairs with the user's phone through Paigy. Each session normally receives its own identity automatically. PAIGY_AGENT can instead assign a fixed named identity when that behavior is needed. The native Paigy iOS app can receive calls through CallKit, including while the phone is locked, according to the project documentation.

Claude Code installations also include hooks that check for pending or unanswered items. A ten-minute check can escalate pending items, while a two-minute check handles replies that have not yet been acknowledged by an agent. These hooks are described as a Claude Code plugin feature rather than a general MCP client behavior.

Setup and configuration

The paigy-ai/mcp MCP server can be run with npx -y @paigy/mcp@latest. Generic MCP clients use a server entry with command set to npx and arguments -y and @paigy/mcp@latest. The repository also documents a shell installer, Claude Code plugin commands, a Claude Desktop MCPB bundle, and client-specific setup for Codex and Gemini CLI.

After installation, run npx -y -p @paigy/mcp@latest paigy-mcp-onboard to pair the phone, approve the pairing request, and sign in at Paigy. Claude Desktop can initiate pairing from a prompt after its MCPB extension is installed. Codex direct MCP configuration may need CODEX_THREAD_ID and CODEX_SESSION_ID passed through its environment allow-list so conversations retain separate identities.

Tools and capabilities

The paigy-ai/mcp MCP server supports workflows involving:

• Asking for approval or confirmation during an agent task.
• Presenting one or more choices and receiving selected option IDs.
• Collecting ranked choices or unrestricted text.
• Notifying a user when a long-running task finishes or becomes blocked.
• Checking and escalating pending or unacknowledged replies in supported Claude Code hook workflows.

Limitations and notes

Urgency is requested by the agent but may be capped by account settings. The README also notes that smaller local models may be less consistent when selecting among confirmation, option, and free-text response shapes; free text remains available as a fallback. The application and backend are maintained in a separate repository, while this repository contains the MCP server and related Claude Code plugin material.