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. It also 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. It works with claude.ai, Claude Desktop and Cowork, Claude Code, and any client that supports Streamable HTTP.
• Self-run package @simplepush/mcp. The client starts it on your machine. You need it for organizations with end-to-end encryption and for personal encryption keys, because the keys never leave your machine.

Hosted connector

claude.ai

Open Settings, then Connectors, then 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 only sign in again after 30 days without use.

The hosted server acts for the account you signed in with. That is your personal account, or the whole organization when you signed in as its admin. It holds no keys, so it sends plaintext 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 you can tell plaintext ones apart. For encrypted sends, run the package yourself.

Self-run package

The package runs in one of two modes. The credential you set decides the mode. It needs 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. The topic then receives a single shared task, and the first answer completes it.

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 supports 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 then 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	Maximum time send_task may block.
SP_POLL_INTERVAL_MS	2000	Time between answer polls while blocking.

Personal encryption

Personal sends are plaintext unless you provide keys exported from the app. Use Copy Key for Integrations on the Encryption screen for the Personal Password key. Use 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 has no key for comes back marked undecryptable: true, never as silently wrong content. Only keys are accepted. There is no password variable, because a password derives every topic key and would grant more access 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. By default each recipient gets a copy, tracked as a group. The tool waits for everyone and reports per-recipient results. shared: true sends one task all recipients answer together, and the first answer completes it.
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 tasks, notifications, answers, replies and submissions, across all time. Search by words, by a coordinate and radius, or by a polygon. Each hit carries the id to read it in full. Plaintext records only.
get_activity	Everything going on for one member or the whole organization in one call. Returns open, declined and expired tasks plus the answers, replies, declines, cancellations and submissions in the time window. Use it for questions like "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. A 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 defines 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 add checklist items or follow-up questions to a task. cancel_task takes 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.