Simplepush MCP Server
OfficialOne-line summary: Simplepush MCP Server lets an agent push notifications and tasks to people's phones, collect their answers and submissions, and search and replay the full record of what was asked and what came back.
Send notifications (
send_notification) — alerts and heads-ups with an optional single input (text, choice, or action buttons); returns immediately or waits viawait_seconds, one copy per recipient orshared: truefor one shared copy.Send tasks (
send_task) — questions, forms and checklists using any combination of text, single/multi choice, action buttons, slider, photo, voice recording, file and location; supportstag,title,replythreads,expires_at, Markdown, links andauto_commit; waits (default 90s) for answers, reporting per-recipient results with the rest pending; every result carries anappend_token.Follow up (
append_subtask) — append questions or checklist items to an existing task or group byappend_token, optionally narrowed to specific instances; never waits.Withdraw (
cancel_task) — cancel a task (tsk_), subtask (sub_) or whole group (grptsk_) with an optional reason, note and superseding task.Read individual answers —
get_task_answer(task or subtask) andget_notification_answer(notification pick, or delivered/pending).Browse tasks (
query_tasks) — paged title-level summaries (tag, topic, status, recipients, input/attachment kinds, reply mode, subtask counts) filtered by status, time, topic, member or group.Read a task in full (
get_task) — content, questions, answers, replies, declines and file ids across the task and all its subtasks.Check a group (
get_group_status) — who answered and who has not, per recipient, for a multi-recipient task group.See the activity history (
query_events) — answers, replies, submissions, declines, cancellations and expiries with who and when, filterable by member and event type.See ad-hoc field reports (
query_submissions) — unsolicited text, photo, file, voice or location reports with sender and time.Search everything (
search_knowledge) — full-text/stemmed keyword search with quoted phrases across tasks, notifications, answers, replies and submissions, or location search by coordinate+radius or a polygon, returning nearest-first points; each hit carries the id to read in full.Catch up per member or org (
get_activity) — one call bundling open, declined and expired tasks plus the window's answers, replies, declines, cancellations and submissions.Download media (
download_attachment) — fetch photos, voice recordings and files byscope_id+file_id, images inline (needsfiles:read).Two modes — personal (API token, own devices or a topic) or organization (integration token, full targeting via
topic/member/broadcast); query tools read the whole org or just your personal stream, and only tools covered by the credential's scopes are listed.Encryption — org sends are end-to-end encrypted when the org has it enabled; personal sends can be encrypted via
SP_KEYS(personal password key and/or per-topic keys), with undecryptable answers flagged rather than silently wrong. Encrypted content is not searchable.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Simplepush MCP Server Send the team a task asking who can cover Friday's shift and wait for replies."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
@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 |
| Push for alerts and heads-ups. Can carry one |
| Sends a task and waits for the answers. Takes the full input set (text, choice, actions, slider, photo, voice recording, file, location), a |
| Appends a follow-up question or checklist item to a task or group, using the |
| Withdraws a task ( |
| Resolves a |
| Resolves what came back on a |
| 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. |
| One task with all its subtasks: questions, answers, replies, declines, file ids. |
| Per-recipient status of a task group ( |
| The org's activity history: answers, replies, submissions, declines, cancellations, expiries, with who and when. Last 7 days by default. |
| Ad-hoc reports from the field (text, photo, file, voice, location), with who and when. Last 7 days by default. |
| 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 |
| 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". |
| Fetches a photo, voice recording or file by |
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/mcpMessages 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 createclaude mcp add simplepush --env SP_INTEGRATION_TOKEN=spi_... -- npx -y @simplepush/mcpOrg 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 |
| one credential required | Personal API token from the app. |
| one credential required | Org integration token from |
| unset | Personal encryption keys, see below. |
|
| API origin. Point at |
|
| Ceiling on how long |
|
| Gap between answer polls while blocking. |
| unset | Space- or comma-separated scope codes ( |
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...=" # bothWith 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 |
| required | Bearer for the AS introspection endpoint. Must match the backend's |
| required | Public URL clients reach this server at, e.g. |
|
| Origin of the authorization server, as clients see it. |
|
| Where this server reaches the authorization server for token introspection. Set it when the backend is closer on an internal address. |
|
| API origin this server calls. |
|
| Listen port. |
Development
npm install
npm run build
npm run typecheckSmoke-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/listNote that the Inspector does not forward your shell environment to the spawned server. Pass credentials with -e, not by exporting them.
Available Tools
14 toolsappend_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
Scored across 14 tools
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.
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.
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.
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
Related MCP Connectors
Send messages and automate conversations over SMS, MMS, WhatsApp, Viber, IVR, and USSD in 150+ countries. Manage contacts, campaigns, and automated services, analyze message history, and look up channel options and pricing. Organizations can require human approval before sending messages.
Read mobile forms, entries, users and tasks; create confirmed draft or sent tasks for field workers.
Business texting for AI agents: send texts, read threads, manage contacts and run campaigns.
Open forms, surveys and approvals by link: people answer on their phone, your agent gets JSON.
Related MCP Servers
- AlicenseCqualityDmaintenanceEnables 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.161MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to communicate with humans using notify and ask semantics, supporting session management and blocking or non-blocking messages.19 npmMIT
- AlicenseBqualityBmaintenanceEnables agents to create and manage persistent task logs, decisions, dead ends, questions, and handoffs, with file staleness detection and activity reporting.2302MIT
- AlicenseNot gradedqualityBmaintenanceEnables 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.42MIT