Skip to main content
Glama
Simplepush MCP Server

Simplepush MCP Server

Official
by simplepush

@simplepush/mcp

MCP server for Simplepush. An agent sends tasks and notifications to people's phones and waits for the answers, appends follow-ups, cancels mistakes, and queries the record of everything that came back. Tasks, answers, replies, declines, and ad-hoc submissions stay queryable, so the stream doubles as a knowledge base of the work: what was asked, who answered what, and what is still open.

Tools

Tool

What it does

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. A copy per recipient by default — the result lists one notification_id per person; shared: true sends one all recipients see.

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: waits for everyone, reports per-recipient results with the rest pending at the deadline. shared: true sends one task all recipients answer together, first answer wins. Every result carries the append_token.

append_subtask

Appends a follow-up question or checklist item to a task or group, using the append_token from send_task. Never waits.

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_id from an earlier send_notification with an input.

query_tasks

One page of tasks as summaries: tag, topic, status, recipients, input kinds, attachment kinds, reply mode, sent time, subtask counts. Filters: status, time window, topic, member, group.

get_task

One task with all its subtasks: questions, answers, replies, declines, file ids.

get_group_status

Per-recipient status of a task group (grptsk_): who has answered, who has not.

query_events

The org's 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 and notifications, what people answered and replied, and ad-hoc submissions, across all time. Literal word matching, plus stemming in up to three languages; or a coordinate plus radius (or a polygon of corner points), returning the locations recorded within it, nearest first. Each hit carries the id to read in full (a group send hits once, as its grptsk_ id) and a snippet or a point with its distance. Plaintext records only.

get_activity

Everything going on for one member or the whole org in one call: open/declined/expired tasks plus the window's answers, replies, declines, cancellations and submissions. The tool for "any problems with X?" and "catch me up".

download_attachment

Fetches a photo, voice recording or file by scope_id (the tsk_/sub_/sbm_ id it belongs to) and file_id (an answer's inputId, a reply or submission file's id). Images are returned inline.

The query tools work in both modes: an organization credential (an integration token, or the hosted connector signed in as an organization admin) reads the whole organization, a personal one (an API token, or the hosted connector with a personal API token) reads your personal stream (subscription required on personal accounts). On the hosted transport they need the read scope; download_attachment additionally needs files:read. Encrypted content is decrypted with the keys the server holds; anything it cannot open is left as ciphertext and reported.

A timeout in send_task is not a cancellation. The questions stay live on the phones, and answers are available later via get_task_answer or get_group_status. inputs says how the task is answered: text, single or multi choice, action buttons, slider, photo, voice recording, file, location. send_task waits 90 seconds by default; per-call wait_seconds raises that, up to SP_MAX_WAIT_SECONDS.

Related MCP server: beacon

Setup

The server runs in one of two modes, decided by which credential you set.

Personal mode

Get an API token from the API Token screen in the Simplepush app, then:

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

Or with Claude Code:

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

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

Org mode unlocks full targeting: every send takes exactly one of topic, member (name or usr_ id), or broadcast. Only the tools the token's scopes cover are listed: a token minted with read files:read exposes the query and download tools and none of the send tools, which keeps the tool schemas a read-only agent carries per request to a minimum. If the org has encryption enabled, the token's second half unwraps the org master keys at startup and all sends are end-to-end encrypted; answers are decrypted the same way.

If both credentials are set, the integration token wins and a note goes to stderr. MCP clients spawn stdio servers with your shell environment attached, so an exported SP_API_TOKEN from unrelated CLI work rides along; setting SP_INTEGRATION_TOKEN is always deliberate.

Environment variables (stdio)

Variable

Default

Meaning

SP_API_TOKEN

one credential required

Personal API token from the app.

SP_INTEGRATION_TOKEN

one credential required

Org integration token from sp integration create.

SP_KEYS

unset

Personal encryption keys, see below.

SP_BASE_URL

https://api.simplepu.sh

API origin. Point at http://localhost:8000 for local development.

SP_MAX_WAIT_SECONDS

900

Ceiling on how long send_task may block. Per-call wait_seconds is clamped to it.

SP_POLL_INTERVAL_MS

2000

Gap between answer polls while blocking.

SP_SCOPES

unset

Space- or comma-separated scope codes (send, read, files:read); only the tools they cover are listed. Narrows an integration token's own scopes; the only way to trim the listing for a personal API token, which the backend always treats as full access.

Encryption

Org mode encrypts automatically when the org has encryption enabled, as described above.

Personal sends are plaintext unless you provide keys. Encrypted and plaintext tasks are distinguishable at a glance in the app: encrypted ones carry the lock icon.

Keys are exported from the Simplepush 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, used for self-sends. topic=key binds a key to one topic:

SP_KEYS="AbC...="                        # default 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 with undecryptable: true rather than silently wrong.

Keys only. There is no SP_PASSWORD.

Hosted HTTP transport

simplepush-mcp-http serves the same tools over Streamable HTTP as an OAuth resource server. No ambient credential: each request carries its own access token, verified by introspection against the authorization server and audience-checked against SP_CANONICAL_URI. Discovery metadata is served at /.well-known/oauth-protected-resource; the MCP endpoint is /mcp. GET /status is a public summary for uptime monitoring: 200 when the authorization server and the API both answer, 503 otherwise, with the same shape as the backend's /v1/status. Tools are scope-gated: send for send_notification, send_task, append_subtask and cancel_task, read for the answer and query tools, files:read for download_attachment. A grant lists only the tools its scopes cover; a direct call for anything else is refused with a challenge naming the missing scope.

Hosted mode is personal OAuth grants only. Integration tokens are not accepted there by design, and hosted sends are plaintext: a server that could decrypt for you would not be end-to-end.

Variable

Default

Meaning

SP_INTROSPECTION_SECRET

required

Bearer for the AS introspection endpoint. Must match the backend's oauth.introspectionSecret.

SP_CANONICAL_URI

required

Public URL clients reach this server at, e.g. https://mcp.simplepu.sh/mcp. Tokens are audience-bound to it.

SP_OAUTH_ISSUER

https://api.simplepu.sh

Origin of the authorization server, as clients see it.

SP_AUTH_SERVER_URL

SP_OAUTH_ISSUER

Where this server reaches the authorization server for token introspection. Set it when the backend is closer on an internal address.

SP_BASE_URL

https://api.simplepu.sh

API origin this server calls.

SP_MCP_PORT

8787

Listen port.

Development

npm install
npm run build
npm run typecheck

Smoke-test against a local backend without an MCP client:

npx @modelcontextprotocol/inspector --cli node dist/index.mjs \
  -e SP_API_TOKEN=testtoken5678 -e SP_BASE_URL=http://localhost:8000 \
  --method tools/list

Note that the Inspector does not forward your shell environment to the spawned server. Pass credentials with -e, not by exporting them.

Available Tools

14 tools
append_subtaskAppend a subtask to an earlier taskAInspect

Add a follow-up question or checklist item to a task sent with send_task. Pass the append_token from that result: a task's token appends to that one task; a group's token appends to every instance of the group (narrow with instances). Subtasks take the same content, inputs and reply as send_task and are answered on their own; read them with get_task (the chain) or get_group_status. Never waits.

Inputs: append_token (required), links, reply, title, +5 more.

cancel_taskCancel a task, subtask or groupAInspect

Withdraw something sent earlier: pass a task_id (tsk_...), subtask_id (sub_...) or group_id (grptsk_...). Pending recipients see it as canceled and can no longer answer; answers already given stay. Canceling a group cancels every still-pending instance and reports how many were already finished. Not undoable.

Inputs: id (required), note, reason, superseded_by.

download_attachmentDownload a photo or fileAInspect

Fetches a photo, voice recording or file by the id of what holds it and the id of the file, the same pair the SDK's download takes. Images come back inline so you can look at them; other files come back as a short-lived download URL plus metadata. Needs the 'files:read' scope.

Inputs: file_id (required), scope_id (required).

get_activityEverything going on for a member (or the whole organization)AInspect

Use this first for 'any problems with ?', 'what is going on with / at the site?', 'catch me up', 'anything I should know?'. One call returns the bundle: open tasks, tasks that were declined or expired, and the window's answers, replies, declines, cancellations and ad-hoc submissions — with who and when. Defaults to the last 7 days. Omit member for the whole organization.

Inputs: since, member.

get_group_statusStatus of a task groupAInspect

Answers 'who has answered and who has not' for a task sent to several people as independent copies (a grptsk_ group id, as shown on tasks from query_tasks): one summary per recipient plus a count per status.

Inputs: group_id (required), status.

get_notification_answerGet the pick on an earlier notificationAInspect

Check whether a notification sent with send_notification and an input has been answered. Pass the notification_id it returned. Returns the pick, pending if untouched, or delivered when the notification carried no input (nothing to answer).

Inputs: notification_id (required).

get_taskRead one task with its subtasksAInspect

Answers 'what exactly was asked and answered on this task'. The full content of one task and every subtask appended to it: the questions, the answers given, replies, declines, and the uploads (inputId) and reply files (id) for download_attachment. Use after query_tasks or get_activity has identified the task. A task sent to several people carries its grptsk_ groupId — follow it with get_group_status for the other recipients' copies.

Inputs: task_id (required).

get_task_answerGet the answer to an earlier taskAInspect

Check whether a task sent with send_task, or a subtask added with append_subtask, has been answered. Pass exactly one of task_id or subtask_id. Returns the answer, or pending if the person has not replied yet; for a subtask the result also names its parent task. A photo, voice or file answer carries its inputId for download_attachment. For the whole task including every subtask, use get_task.

Inputs: task_id, subtask_id.

query_eventsRead the organization's activity historyAInspect

Answers 'what happened' — the place to look for anything reported, answered, replied, declined or cancelled, oldest first, each with who did it and when. This is where problems surface; query_tasks does not contain them. Defaults to the last 7 days. Filter by member or by event type (TaskCompleted, TaskInputCompleted, SubtaskCompleted, ReplyAppended, SubmissionCreated, TaskDeclinedByRecipient, TaskCanceled, TaskExpired, ...). For a ready-made bundle per member use get_activity; for ad-hoc reports alone use query_submissions.

Inputs: type, limit, since, until, +2 more.

query_submissionsRead ad-hoc submissions from the fieldAInspect

Answers 'did anyone report something on their own' — reports people sent without being asked (not answers to a task): text, photo, file, voice note, location, with who sent it and when. Check this whenever a question is about problems or reports; the task index never shows these. Oldest first; defaults to the last 7 days. Photos and files carry their id for download_attachment (scope_id = the sbm_ id).

Inputs: limit, since, until, cursor, +1 more.

query_tasksList the organization's tasksAInspect

Answers 'which tasks are open, expired, declined or done, and who has them'. Status only — it never shows what people answered or reported; for that use get_task, query_events or get_activity. One page of compact summaries, newest first: id, title, tag, topic, status, recipients, input kinds and reply mode (what sort of answer it expects), attachment kinds (file, link), sent time, and a per-status count of the task's subtasks (checklist items). Filter by status, time window, topic, member, or group.

Inputs: group, limit, since, topic, +4 more.

search_knowledgeSearch everything by words or by placeAInspect

Full-text and location search over everything this credential reads — the organization's records, or what a personal account sent and submitted: task titles and content, answers, replies, notifications and their answers, and ad-hoc submissions — across all time, ranked. Use it for 'anything about X?', 'what was said about X?', 'who mentioned X?'. Words match literally, and by stem in the languages the organization configured (so 'leak' finds 'leaking' only where stemming is on); several words must all appear; quote a phrase for adjacency. For 'what happened around ?' pass center/radius_meters instead of (or on top of) the query: alone they return the location answers, replies and submissions recorded within the radius, nearest first; with a query, text hits are kept only when their task or submission carries an in-radius point. For a shape rather than a circle — a site, a block, a stretch of road — pass area_points, a polygon of 3 to 50 corners, instead; those hits carry no distance and come newest first. Resolve a street or site name to coordinates yourself first, and prefer a generous radius when the coordinates are geocoded rather than known. Each hit carries the id to read in full (tsk_/sub_ with get_task, grptsk_ — a task sent to several people — with get_group_status, ntf_ with get_notification_answer, sbm_ with query_submissions) and a snippet with the matching words in brackets (a location hit carries its point and distance instead). Encrypted records are not searchable.

Inputs: kind, limit, query, since, +5 more.

send_notificationSend a push notificationAInspect

Send a push notification to phones. A notification lives only in the banner: once dismissed it is gone, so it suits alerts and heads-ups, not questions that must be answered. It can still carry one input — a text input, a choice, or action buttons. By default the call returns right after sending and the answer is readable later with get_notification_answer; set wait_seconds to wait for it in the same call. Each recipient gets their own copy by default; with several recipients the result lists one notification_id per person. For a question that needs an answer, a photo, file, location, slider or several inputs, use send_task.

Inputs: content (required), input, title, topic, +6 more.

send_taskSend a task (a question, form or checklist item that needs an answer)AInspect

Create a task on people's phones and wait for the answers. content says what to do or answer; inputs says how to answer: one or more of text, choice (single or multi), action buttons, slider, photo, voice recording, file, location, all answered in one submission. reply opens a comment thread on the task instead of, or in addition to, inputs. By default every recipient gets their own copy of the task, tied together by a group; the call waits up to wait_seconds (default 90s) for ALL of them to answer and returns per-recipient results, with whoever has not answered yet marked pending — a timeout is not a cancellation, the tasks stay live and get_group_status or get_task_answer resolve them later. shared: true sends ONE task that all recipients see and answer together (the first answer resolves it) — use it for questions where any one person's answer settles the matter. Every result carries an append_token for append_subtask.

Inputs: tag, links, reply, title, +10 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.4/5.0

    Scored across 14 tools

    Disambiguation4/5

    The core send/get/cancel tools are clearly separated by resource and action, but the retrieval tools—query_tasks, query_events, query_submissions, get_activity, and search_knowledge—overlap in scope and rely heavily on their detailed descriptions to keep an agent from picking the wrong one.

    Naming Consistency5/5

    All tool names follow a consistent snake_case verb_noun pattern, with parallel names for parallel resources such as get_task_answer and get_notification_answer. There are no mixed conventions or vague generic verbs.

    Tool Count5/5

    Fourteen tools cover the domain well: sending tasks and notifications, managing subtasks, retrieving answers, querying statuses and events, searching knowledge, and downloading attachments. Each tool maps to a distinct workflow without the set feeling bloated.

    Completeness4/5

    The lifecycle is broadly complete: create, append, cancel, read, list, search, and download are all represented. Minor gaps remain, such as no direct full read of a sent notification and no update path for already-sent tasks, but these are outside the core workflow's critical path.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      C
      quality
      D
      maintenance
      Enables AI agents to send, receive, schedule, and manage SMS and MMS messages using the Twilio Programmable Messaging API. It provides comprehensive tools for handling bulk messaging, conversation threads, and real-time inbox monitoring through a secure, production-grade architecture.
      16
      1
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI agents to communicate with humans using notify and ask semantics, supporting session management and blocking or non-blocking messages.
      19 npm
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to ring or text a user's actual iPhone, read a question or update aloud, and return the spoken answer back to the agent as text. Calls and messages land in a single titled thread per agent, with tools for polling results, waiting for replies, and labeling conversations.
      42
      MIT