MCP Server

The Simplepush MCP server connects AI agents to Simplepush over the Model Context Protocol. Simplepush coordinates field operations: tasks go out to the people on site, and their answers, replies, photos and reports come back into a single record. An agent connected over MCP works on both ends. It sends tasks and follow-ups and collects the answers, and it queries the record to report what happened, what is still open, and what the field reported on its own.

It comes in two forms:

• Hosted connector at https://mcp.simplepu.sh/mcp. Nothing to install. You sign in once with OAuth, either as an organization admin or with your personal API token. For claude.ai, Claude Desktop and Cowork, Claude Code, and any client that speaks Streamable HTTP.
• Self-run package @simplepush/mcp, started by the client on your machine. Needed for organizations with end-to-end encryption and for personal encryption keys, because the keys never leave your machine.

Hosted connector

claude.ai

Settings, Connectors, Add custom connector. Enter https://mcp.simplepu.sh/mcp and keep the default client settings. A consent page opens on api.simplepu.sh. Sign in as your organization admin, or paste your personal API token from the app (settings, under API Token), and approve. Claude Desktop and Cowork use the same connector settings.

Claude Code

claude mcp add --transport http simplepush https://mcp.simplepu.sh/mcp

Then run /mcp in a session and pick simplepush to sign in. The browser opens the same consent page.

What the connector can and cannot do

The consent page asks for three permissions: send for sending tasks and notifications, read for answers and queries, and files:read for downloading photos and files. Access is renewed automatically; you sign in again only after 30 days without use.

The hosted server acts for the account you signed in with: your personal account, or the whole organization when you signed in as its admin. It holds no keys, so it sends in the clear and cannot read encrypted content. A server that could decrypt for you would not be end-to-end encrypted. Encrypted tasks are marked with a lock in the app, so plaintext ones are visible as such. For encrypted sends, run the package yourself.

Self-run package

The package runs in one of two modes, decided by which credential you set. Node.js 20 or newer.

Personal mode

Get an API token from the API Token screen in the app.

Claude Code

claude mcp add simplepush --env SP_API_TOKEN=your-token -- npx -y @simplepush/mcp

JSON config

{
  "mcpServers": {
    "simplepush": {
      "command": "npx",
      "args": ["-y", "@simplepush/mcp"],
      "env": { "SP_API_TOKEN": "your-token" }
    }
  }
}

Messages go to your own devices. Pass a topic to deliver to that topic's holders instead, as a single shared task where the first answer wins.

Organization mode

Create an integration token with the CLI (admin vault unlocked):

sp integration create

claude mcp add simplepush --env SP_INTEGRATION_TOKEN=spi_... -- npx -y @simplepush/mcp

Organization mode unlocks full targeting: every send takes exactly one of topic, member (name or usr_ id), or broadcast. If the organization has encryption enabled, the token unwraps the organization's master keys at startup. Sends are end-to-end encrypted and answers are decrypted automatically.

Environment variables

Variable	Default	Meaning
SP_API_TOKEN	one credential required	Personal API token from the app.
SP_INTEGRATION_TOKEN	one credential required	Organization integration token from sp integration create.
SP_KEYS	unset	Personal encryption keys, see below.
SP_BASE_URL	https://api.simplepu.sh	API origin.
SP_MAX_WAIT_SECONDS	900	Ceiling on how long send_task may block.
SP_POLL_INTERVAL_MS	2000	Gap between answer polls while blocking.

Personal encryption

Personal sends are plaintext unless you provide keys, exported from the app: Copy Key for Integrations on the Encryption screen for the Personal Password key, and the copy action next to a topic on the Topics screen for topic keys. SP_KEYS is a comma-separated list. A bare base64 key is the Personal Password key, topic=key binds a key to one topic:

SP_KEYS="AbC...="                         # Personal Password key only
SP_KEYS="alerts=AbC...=,deploys=XyZ...="  # two topic keys
SP_KEYS="AbC...=,alerts=XyZ...="          # both

With a matching key, sends to that target are encrypted and answers are decrypted. An answer the server holds no key for comes back marked undecryptable: true rather than silently wrong. Keys only. There is no password variable, because a password derives every topic key and would grant more than one key does.

Tools

Tool	What it does
send_task	Sends a task and waits for the answers. Takes the full input set (text, choice, actions, slider, photo, voice recording, file, location), a tag, a reply mode, expires_at, Markdown and links. A copy per recipient by default, tracked as a group: waits for everyone and reports per-recipient results. shared: true sends one task all recipients answer together, first answer wins.
send_notification	Push for alerts and heads-ups. Can carry one input (a text input, a choice, or action buttons); returns right after sending unless wait_seconds is set.
append_subtask	Appends a follow-up question or checklist item to a task or group, using the append_token from send_task.
cancel_task	Withdraws a task (tsk_), subtask (sub_) or whole group (grptsk_) by id, with an optional reason and note.
get_task_answer	Resolves a task_id from an earlier send_task, or a subtask_id from append_subtask.
get_notification_answer	Resolves what came back on a notification that carried an input.
query_tasks	Task summaries (tag, topic, status, recipients, input kinds, attachment kinds, reply mode, subtask counts) with filters: status, time window, topic, member, group.
get_task	One task with all its subtasks: questions, answers, replies, declines, and the ids of photos and files.
get_group_status	Per-recipient status of a task group: who has answered, who has not.
query_events	Activity history: answers, replies, submissions, declines, cancellations, expiries, with who and when. Last 7 days by default.
query_submissions	Ad-hoc reports from the field (text, photo, file, voice, location), with who and when. Last 7 days by default.
search_knowledge	Full-text and location search over everything: tasks, notifications, answers, replies, submissions, across all time. Words, or a coordinate and radius, or a polygon. Each hit carries the id to read in full. Plaintext records only.
get_activity	Everything going on for one member or the whole organization in one call: open, declined and expired tasks plus the window's answers, replies, declines, cancellations and submissions. The tool behind "any problems on site 3?" and "catch me up".
download_attachment	Fetches a photo, voice recording or file. Images are returned to the agent inline.

Asking and waiting

send_task waits 90 seconds by default; per-call wait_seconds raises that up to SP_MAX_WAIT_SECONDS. A timeout is not a cancellation: the task stays live on the phone and get_task_answer resolves it later. inputs says how a task is answered: text, single or multi choice, action buttons, slider, photo, voice recording, file, or location.

Every send_task result carries an append_token. The agent uses it with append_subtask to grow a task into a checklist or follow-up chain, and cancel_task to take back anything sent in error.

Querying

The query tools work in both modes. In organization mode, and over the hosted connector with an organization admin sign-in, they read the whole organization's record. In personal mode, and over the hosted connector with a personal API token, they read your own record. Querying a personal record needs a subscription. Encrypted content is decrypted with the keys the server holds; anything it cannot open is left as ciphertext and reported as such, never guessed at.