AI agents (MCP)
Use @palmpush/mcp when an MCP client or AI agent should send notifications to
you.
Create a listener in the iOS app first and use Copy id for its token. The MCP server runs locally and needs Node.js 18 or newer.
Optional imageUrl and url inputs require @palmpush/mcp 0.2.0 or newer.
Version 0.1.0 supports text messages; use the HTTP API for images
and tap links until you can upgrade. A listener avatar
configured in the app is included automatically for that device, including
messages sent through MCP.
The server exposes one tool:
send_push_notificationSingle listener
Use this when every agent notification should go to one listener.
PALMPUSH_LISTENER_ID=abc123abc123abc123abc123abc123ab npx @palmpush/mcpThe tool input is simple:
{
"title": "Approval needed",
"body": "The agent is waiting for your decision."
}Named listeners
Use a private config file when the agent should choose between multiple listeners.
{
"listeners": [
{
"name": "approval",
"listenerId": "aaa123aaa123aaa123aaa123aaa123aa",
"description": "Use when the user needs to decide."
},
{
"name": "status",
"listenerId": "bbb123bbb123bbb123bbb123bbb123bb",
"description": "Use for non-blocking status updates."
}
]
}Start the server with:
PALMPUSH_CONFIG=/path/to/palmpush-mcp.json npx @palmpush/mcpIn this mode, the tool also requires listenerName:
{
"title": "Task finished",
"body": "The report is ready.",
"listenerName": "status"
}Images and tap links
With version 0.2.0 or newer, use the same tool with either optional field or both:
{
"title": "Build finished",
"body": "Open the report.",
"imageUrl": "https://www.palmpush.com/favicon/web-app-manifest-512x512.png",
"url": "https://www.palmpush.com/docs"
}For named listeners, also include listenerName as above. imageUrl is the
attachment; url is the destination opened on tap. Omit unused fields rather
than passing null or empty strings. URL validation errors return a tool error
without sending. The tool does not download either URL on the agent's machine.
See image requirements and tap behavior. After
updating the npm package or npx version in your MCP configuration, restart the
server and reconnect the client to refresh its tool schema. Existing listener
configuration can be reused.
MCP client config
{
"mcpServers": {
"palmpush": {
"command": "npx",
"args": ["-y", "@palmpush/mcp"],
"env": {
"PALMPUSH_CONFIG": "/path/to/palmpush-mcp.json"
}
}
}
}Security
The MCP server keeps the token in its local configuration. In named-listener mode, the agent chooses a configured name instead of including the token in each tool call. Anyone with the token can still send, subscribe, or change shared listener settings. Keep configuration files out of public repositories and shared prompts.
Check the result
Provider failures, including partial failures, return a tool error. Retrying the entire request after a partial failure can duplicate accepted notifications. Read the delivery counts in the tool result. Zero sends can mean a disabled listener or no eligible targets. A positive sent count means provider acceptance, not an alert appearing on the device. Use Troubleshooting if a message is missing.