How It Works

Architecture

Pushary runs a hosted Model Context Protocol (MCP) server. Your AI agent connects to it over HTTP, gets access to notification and question tools, and can reach you on any device you've subscribed on.

AI Agent → MCP (Streamable HTTP) → pushary.com/api/mcp → Web Push → Your Phone

The MCP server is a thin layer over the Pushary REST API. Every tool call maps to an API endpoint. Authentication, rate limits, and plan limits are shared between MCP and REST.

Any MCP-compatible client works: Claude Code, Codex, Cursor, Windsurf, Hermes, Lovable, and any tool that supports Streamable HTTP or stdio via mcp-remote.

Connection methods

Streamable HTTP (recommended)

Most modern MCP clients support HTTP transport:

{
  "pushary": {
    "url": "https://pushary.com/api/mcp/mcp",
    "headers": {
      "Authorization": "Bearer pk_xxx.sk_xxx"
    }
  }
}

stdio via mcp-remote

For clients that only support stdio transport, use the mcp-remote bridge:

{
  "pushary": {
    "command": "npx",
    "args": [
      "-y",
      "mcp-remote",
      "https://pushary.com/api/mcp/mcp",
      "--header",
      "Authorization:Bearer pk_xxx.sk_xxx"
    ]
  }
}

Agent skill

Install the Pushary skill to teach your agent when and how to use notifications:

npx skills add pushary/pushary-skill

Works with Claude Code, Codex, Cursor, Windsurf, and 38+ other agents. The skill includes tool documentation and best practices for notification etiquette.

Authentication

The MCP server authenticates via a site API key passed as a Bearer token. Keys are site-scoped. Each key is tied to a specific workspace.

The key format is pk_xxx.sk_xxx and is shown once at creation time. Store it securely.

If the key is missing or invalid, the server returns HTTP 401 and all tool calls fail.

Authentication details

Agent identity

When you run several agents at once, Pushary keeps them apart. The hook attaches two fields to every call: a sessionId (one per agent window) and a machineId (a hashed hostname). The pair keys each session, so two Claude Code windows in the same repo show up as two distinct sessions — and a blocked approval points at the exact one that raised it.

Multi-Agent Control Panel

Task titles and privacy

For Claude Code, the setup wizard also registers a UserPromptSubmit hook. When you submit a prompt, the hook sends the first 120 characters of it to Pushary as the session's task title, so the dashboard can show what each session is working on instead of a bare session id. That truncated snippet is the only prompt text that leaves your machine. The hook never sends the rest of the prompt, file contents, or tool output.

Task titles are on by default. To turn them off, set an environment variable where your agent runs:

export PUSHARY_TASK_TITLES=off

With titles off, the hook still reports that a prompt was submitted so the session shows as active, but it sends no prompt text at all. Each new prompt in a session replaces the title, so the dashboard always shows the latest instruction.

Rate limits

MCP tool calls share rate limits with the REST API. Limits are per-workspace and vary by plan.

Approval questions have their own two-tier limit so a fan-out of parallel agents is never throttled while a single runaway agent is still bounded:

• 3 pending questions per agent session
• 25 pending questions per site
• 10 notifications per 5 minutes per site

A pending question that times out frees its slot automatically after 10 minutes.

Pricing and limits

Tool categories

The MCP server exposes 20 tools across six categories:

Full tools reference