Skip to documentation content

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:

txt
send_push_notification

Single listener

Use this when every agent notification should go to one listener.

bash
PALMPUSH_LISTENER_ID=abc123abc123abc123abc123abc123ab npx @palmpush/mcp

The tool input is simple:

json
{
  "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.

json
{
  "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:

bash
PALMPUSH_CONFIG=/path/to/palmpush-mcp.json npx @palmpush/mcp

In this mode, the tool also requires listenerName:

json
{
  "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:

json
{
  "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

json
{
  "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.