nofax
This server lets an AI agent send phone notifications and run durable human-in-the-loop approval, choice, and free-text refinement requests.
Send a one-way informational phone notification; transport success is never approval.
Request human Allow/Deny approval, optionally allowing free-text refinement instead.
Request an explicit choice from up to three options.
Request free-text refinement of a draft or context.
Long-poll a durable request for up to 240 seconds and repeat while it remains pending; timeout never means approval.
Inspect a known request’s safe metadata and terminal state without waiting.
List unresolved pending requests to recover after interruption.
All interactive requests return durable request IDs and fail closed while pending.
Allows sending phone notifications and interactive approval requests through ntfy-compatible servers, including one-way notifications, allow/deny decisions, choices, and free-text refinements.
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., "@nofax request approval to deploy release 1.4.0 to production"
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.
Nofax
Human-in-the-loop approvals and notifications for AI coding agents, without running a Nofax SaaS.
Nofax is a small open-source bridge between an agent and a human. Local mode can pause an AI workflow, notify your phone, and return an explicit decision. An optional self-deployed Cloudflare Worker exposes a deliberately narrower remote MCP surface for one-way notifications and safe request inspection.
No Nofax account. No paid model API. No inbound port on your machine. MIT licensed.
Current status: local Nofax is on the stable
0.2.xline. The optional Cloudflare Worker is the upcoming0.3.0remote surface and is developed alongside the local package.
Why Nofax
Agent workflows increasingly need a clean answer to one question: when automation reaches a human decision boundary, how does it ask without pretending that silence means approval?
Nofax keeps that boundary explicit:
pending is never approval;
timeout and transport failure fail closed;
the first accepted terminal response wins;
agent-specific hook schemas stay isolated in adapters;
remote access is intentionally narrower than local access;
Nofax does not grant authority the calling agent did not already have.
Related MCP server: Relay
Two operating modes
Capability | Local Nofax | Remote Worker |
Transport | stdio / CLI hooks | MCP Streamable HTTP |
One-way notification | Yes | Yes |
Allow / Deny | Yes | No |
Explicit choices | Yes | No |
Free-text refinement | Yes | No |
Wait for human response | Yes | No |
Read request metadata | Yes | Yes |
Durable state | Local files | Existing SQLite Durable Object rows |
Hosted by Nofax | No | No — self-deployed Worker |
Remote authentication | Local process boundary | Private bearer key |
The remote Worker is not a hosted remote-approval service. It can send an informational notification and inspect existing request state, but it has no approval callback, choice, refinement, wait, webhook, or arbitrary remote-write endpoint.
Quick start
1. Install
npm install -g nofaxRequires Node.js 20 or newer.
2. Initialize
nofax initNofax creates ~/.nofax/config.json and generates a high-entropy notification topic. With the default transport, subscribe to the displayed topic in the ntfy mobile app.
3. Test
nofax testTo inspect local outstanding approval requests without sending a notification or
granting a decision, run nofax pending (or nofax pending --limit 10). It
prints only request IDs, kinds, statuses, and creation times as JSON; it does
not print request prompts or the ntfy subscription topic. This is a read-only
local diagnostic, not an approval interface.
4. Use it
nofax notify --title "Build finished" "All tests passed"
nofax approve --title "Deploy?" "Release 1.4.0 is ready"
nofax refine --title "Refine draft" "Tell me what to change"An approval resolves to stable terminal JSON:
{"decision":"allow"}or:
{"decision":"deny"}If the request is still pending, times out, disconnects, or hits a transport error, Nofax never converts that condition into approval.
For scripts using nofax approve, exit status 0 means explicit allow, 2 means explicit deny, 3 means timeout, and 1 means an error or unrecognized decision. The terminal JSON decision remains unchanged. Never treat a denied request as successful based solely on receipt of a response.
ntfy client compatibility: On iOS, the ntfy app may leave an HTTP action notification visible after you tap Allow or Deny, even when the action requests clear: true (upstream ntfy issue #1728). A still-visible notification does not prove whether Nofax recorded a decision: rely on Nofax's terminal allow/deny response or pending/timeout state, not on whether the notification disappears. If you use the ntfy web app instead of the mobile app, HTTP action buttons in notifications are supported in Chrome, Edge, and Opera but not Firefox or Safari; cross-origin callbacks also need the target server to allow CORS (ntfy web-app support).
Windows PowerShell with restricted script execution
If PowerShell reports that npm.ps1 or npx.ps1 cannot be loaded because
scripts are disabled, invoke npm's Windows .cmd launchers explicitly.
The usual global install creates a nofax.cmd launcher too:
npm.cmd install --global nofax
nofax.cmd init
nofax.cmd testFor a one-off local MCP launch without a global Nofax installation, use
npx.cmd -y nofax mcp (the final mcp argument is required). An MCP client
that launches npx through PowerShell can set its command to npx.cmd with
arguments ["-y", "nofax", "mcp"]. These are executable launchers, not a
request to disable or bypass your organization's PowerShell execution policy.
If executable launches themselves are restricted, follow your administrator's
policy instead. See Microsoft's PowerShell execution policy reference.
MCP
Start the local stdio MCP server:
nofax mcpConnect an MCP client
Claude Code can launch the published local MCP server directly:
claude mcp add nofax -- npx -y nofax mcpCodex CLI can register the same stdio server:
codex mcp add nofax -- npx -y nofax mcpGemini CLI can register it in user settings:
gemini mcp add --scope user --transport stdio nofax npx -- -y nofax mcpGemini CLI may mark configured servers Disabled when the current workspace is untrusted. Review and trust only workspaces you control through Gemini's normal trust flow; do not use --trust to bypass MCP tool-call confirmations. Registering an MCP server does not automatically install the separate permission hooks documented below.
VS Code can register Nofax in its user-profile MCP configuration. Open the Command Palette, choose MCP: Open User Configuration, and add this entry to mcp.json:
{
"servers": {
"nofax": {
"type": "stdio",
"command": "npx",
"args": ["-y", "nofax", "mcp"]
}
}
}Merge the nofax entry with any existing servers rather than replacing them. Review VS Code's normal server-trust prompt before starting it; MCP registration does not install separate permission hooks.
For other stdio MCP clients, set the command to npx with arguments ["-y", "nofax", "mcp"]. The final mcp argument is required: running npx -y nofax without it prints the CLI usage and exits instead of starting a server. On Windows, use npx.cmd when a PowerShell script-execution policy prevents the .ps1 shim from running. Complete the Quick start configuration before using notification or approval tools.
Local MCP exposes:
nofax_notifynofax_request_approvalnofax_request_choicenofax_request_refinementnofax_wait_for_responsenofax_get_requestnofax_list_pending
Interactive requests return a durable request ID. nofax_wait_for_response performs a bounded wait; callers must repeat the wait while the request remains pending rather than infer approval.
Agent integrations
Claude Code
Use Nofax as a local PermissionRequest hook in ~/.claude/settings.json:
{
"hooks": {
"PermissionRequest": [
{
"matcher": ".*",
"hooks": [
{
"type": "command",
"command": "nofax hook claude"
}
]
}
]
}
}Codex
Codex hooks are enabled by default. Configure ~/.codex/hooks.json:
{
"hooks": {
"PermissionRequest": [
{
"matcher": ".*",
"hooks": [
{
"type": "command",
"command": "nofax hook codex",
"statusMessage": "Waiting for Nofax approval"
}
]
}
]
}
}Restart Codex, run /hooks, and review/trust the exact Nofax hook definition before relying on it. Codex skips non-managed hooks until they are trusted, and a changed hook definition must be reviewed again. If an administrator or local policy has explicitly disabled hooks, re-enable them with [features] hooks = true in ~/.codex/config.toml.
Codex currently evaluates PermissionRequest hooks before its configured approval reviewer. A terminal Nofax Allow/Deny therefore resolves the request before Codex can route it to approvals_reviewer = "auto_review" (or the legacy guardian_subagent value). If you want Nofax to be the human approval surface, use approvals_reviewer = "user"; do not combine this Nofax approval hook with Auto-review/Guardian expecting both reviewers to run. Current Codex hook input does not expose the effective reviewer, so Nofax cannot safely distinguish a user-routed approval from one that Codex intended to auto-review.
PermissionRequest hooks are also serial with Codex's native approval UI: while Nofax is waiting, the normal Codex approval prompt is not simultaneously available. If Nofax returns no decision (for example after timeout or transport failure), Codex falls back to its normal approval flow. Nofax never converts that fallback condition into approval.
Gemini CLI
Current Gemini CLI builds expose a synchronous BeforeTool hook that can allow or deny a tool call. Route selected tools through Nofax in ~/.gemini/settings.json:
{
"hooks": {
"BeforeTool": [
{
"matcher": "run_shell_command|write_file|replace",
"hooks": [
{
"name": "nofax-approval",
"type": "command",
"command": "nofax hook gemini",
"timeout": 305000
}
]
}
],
"Notification": [
{
"matcher": "ToolPermission",
"hooks": [
{
"name": "nofax-notification",
"type": "command",
"command": "nofax hook gemini"
}
]
}
]
}
}BeforeTool waits for an explicit Nofax Allow/Deny result. A Nofax timeout or transport failure returns Gemini's ask decision, forcing the native interactive confirmation instead of allowing an auto-approval policy to treat the missing Nofax decision as permission. The Notification hook remains advisory and is forwarded only as a phone notification.
Adjust the matcher to the tools you want Nofax to gate. Keep the hook timeout longer than Nofax's configured approval timeout (timeoutSeconds, 300 seconds by default).
Pi (native MCP support)
Pi 1.x has built-in MCP support for local stdio servers; see Pi's official MCP documentation. After nofax init, register and check the Nofax server:
pi mcp add nofax -- npx -y nofax mcp
pi mcp listPi's default MCP request timeout is 60 seconds. If you use nofax_wait_for_response with waits longer than that (up to Nofax's 240-second maximum), add "timeout": 300 to the existing nofax entry in ~/.pi/agent/mcp.json. Do not replace unrelated server entries or settings:
{
"mcpServers": {
"nofax": {
"command": "npx",
"args": ["-y", "nofax", "mcp"],
"timeout": 300
}
}
}Pi's built-in MCP configuration lives in ~/.pi/agent/mcp.json. Third-party extensions that replace /mcp (such as pi-mcp-adapter) take over the interactive MCP integration and may not load that built-in configuration. Verify which MCP implementation your Pi session is using before adding or changing a server; do not disable Pi's permission gates or install a second MCP runtime just for Nofax.
This registers MCP tools, not an automatic permission hook or idle-session wake-up. While a request is pending, the agent must call nofax_wait_for_response again; a missing reply, timeout, or disconnect is never approval. Use Pi's normal trust/permission workflow and verify your installed Pi build exposes pi mcp before applying these instructions.
Optional remote Cloudflare Worker
The worker/ package provides a private, self-deployed MCP endpoint:
remote MCP client
|
| authenticated Streamable HTTP
v
Cloudflare Worker
|
+--> nofax_notify ------> ntfy ------> phone
|
+--> SQLite Durable Object
|
+--> get request metadata
+--> list pending requestsIt exposes exactly three tools:
nofax_notify— one-way notification only;nofax_get_request— read one safe request projection;nofax_list_pending— read unresolved, unexpired request projections.
Fresh deployments have no requests to inspect. These two inspection tools
read only historical records already stored in that Worker's Durable Object,
such as rows preserved from earlier experimental builds. nofax_notify does
not create a request record, and local Nofax approvals are not synchronized
with the remote Worker. On a new Worker, nofax_list_pending therefore
returns an empty list and nofax_get_request reports not found until a
historical row exists. Use the local CLI/stdio MCP for actual phone approvals.
Deploy from worker/:
npm ci
npx wrangler login
npx wrangler secret put NOFAX_REMOTE_KEY
npx wrangler secret put NTFY_TOPIC
npm run check
npm run deployPreferred MCP connection:
https://<worker>.workers.dev/mcp
Authorization: Bearer <NOFAX_REMOTE_KEY>Clients that cannot attach a static authorization header can use the compatibility capability path:
https://<worker>.workers.dev/mcp/<NOFAX_REMOTE_KEY>Treat the complete capability URL like a password.
See docs/remote-mcp.md for deployment, threat boundaries, and qualification details.
Important: public ntfy + serverless egress
The default public ntfy.sh service applies publisher quotas. Serverless platforms such as Cloudflare Workers may use shared outbound IP space, so a Worker can receive an ntfy 42908 daily-quota response even when that individual Worker has sent very little traffic. That limit is imposed by ntfy, not by the Cloudflare Workers request quota.
For reliability-sensitive deployments, use a notification provider whose quota is tied to your own authenticated account/identity, or operate a trusted self-hosted transport. Do not build a critical workflow around anonymous public-topic quota assumptions.
Security model
Nofax is a transport and human-interaction component, not an authorization policy engine.
Local mode:
pending, timeout, disconnect, malformed state, and network failure never mean approval;
the first valid terminal response wins;
notification topics and one-time response topics are capabilities;
public ntfy is not end-to-end encrypted from the provider;
redaction is best-effort and cannot reliably identify secrets embedded in arbitrary free-form text.
Remote mode:
only explicit
nofax_notifyperforms an external messaging side effect;request-inspection operations are read-only and do not perform hidden cleanup writes;
remote approval, callback, webhook, refinement, choice, and wait surfaces are absent;
NOFAX_REMOTE_KEYis a bearer credential;remote projections omit callback capabilities, prompt/message text, and internal allowed-decision lists.
Read SECURITY.md before using Nofax with sensitive information.
Configuration
Default local config lives at ~/.nofax/config.json:
{
"version": 1,
"server": "https://ntfy.sh",
"topic": "nofax_<random>",
"timeoutSeconds": 300
}Override the home directory with NOFAX_HOME:
NOFAX_HOME=/path/to/nofax-home nofax configUse another ntfy-compatible server with:
nofax init --server https://ntfy.example.com --forceNotification content and one-time response-topic callbacks can carry sensitive
capabilities. Custom servers require HTTPS; HTTP is supported only for local
development on localhost, IPv4 loopback (127.0.0.0/8) or [::1].
Previously configured non-loopback HTTP endpoints must be moved to HTTPS
before notifications or approval polling will work. This is not an approval
fallback: transport failures always remain pending, denied or timed out.
Optional authenticated ntfy publishing
If your ntfy server requires an access token to publish to the phone's topic,
set NOFAX_NTFY_TOKEN in the environment of the local NoFax process
(CLI, MCP server, or agent hook). Use an ntfy access token with the minimum
necessary publish permission. NoFax adds Authorization: Bearer only to
notification publication requests. See ntfy access tokens.
Authenticated publishing requires an HTTPS ntfy server; invalid credentials
or HTTP transport fail before publishing or persisting a new pending approval.
Do not put the token in config.json, Git, command arguments or logs.
nofax config does not print the environment token.
This does not authenticate the phone's HTTP action callbacks or the temporary response-topic polling endpoint. Keep response-topic callbacks reachable using the standard NoFax workflow; server-wide access rules that block these callbacks will cause approval to remain pending or time out, never auto-approve. Configure the ntfy phone app separately for access to the protected notification topic. The remote Cloudflare Worker is not configured by this local-only setting.
Development
Local package:
npm ci
npm run check
npm test
npm pack --dry-runRemote Worker:
cd worker
npm ci
npm run checkCI qualifies Node.js 20, 22, and 24 for the local package. The Worker gate runs TypeScript, Vitest, a production-dependency audit, and a Wrangler deployment dry-run.
Project docs
docs/architecture.md— trust boundaries and data flowdocs/remote-mcp.md— remote Worker deployment and qualificationSECURITY.md— security assumptions and vulnerability reportingCONTRIBUTING.md— contribution and test expectationsCHANGELOG.md— release history
Non-goals
Nofax deliberately does not provide:
a Nofax-operated approval SaaS;
a paid model API dependency;
persistent
always approvepolicy;an arbitrary remote shell endpoint;
a public multi-user Worker behind one shared deployment key;
a claim that MCP annotations themselves are a security boundary.
License
MIT © Tomi Šeregi. See LICENSE.
Available Tools
7 toolsnofax_get_requestGet Nofax requestARead-onlyIdempotent
Inspect safe metadata and terminal state for one known durable requestId without waiting. Use nofax_wait_for_response when the caller must wait for a human decision, or nofax_list_pending to recover requestIds after interruption. Secret response topics are never returned.
Inputs: requestId (required). Returns: status, request
nofax_list_pendingList pending Nofax requestsARead-onlyIdempotent
List a bounded set of unresolved Nofax request handles for recovery after client or conversation interruption. Secret response topics are never returned.
Inputs: limit. Returns: status, requests
nofax_notifySend Nofax notificationA
Send a one-way phone notification. This tool is informational and does not create a human-response wait. Notification transport success never counts as approval.
Inputs: message (required), title. Returns: status
nofax_request_approvalRequest human approvalA
Send Allow/Deny to the phone and return a durable pending requestId. IMPORTANT: after this tool returns pending, call nofax_wait_for_response and repeat while it remains pending. Never continue the guarded action without a terminal Allow response. Set allowRefine when the human should also be able to send refinement text.
Inputs: message (required), title, allowRefine. Returns: status, mustWait, requestId, instruction
nofax_request_choiceRequest human choiceA
Send up to three explicit options to the phone and return a durable pending requestId. IMPORTANT: call nofax_wait_for_response and repeat while pending; do not choose on the human's behalf.
Inputs: message (required), options (required), title. Returns: status, mustWait, requestId, instruction
nofax_request_refinementRequest human refinementA
Ask the human for free-text refinement through the configured Nofax Refine iOS Shortcut. Use this when free-text edits are needed; use nofax_request_approval for Allow/Deny or nofax_request_choice for predefined options. Returns a durable pending requestId; call nofax_wait_for_response and repeat while pending.
Inputs: message (required), title. Returns: status, mustWait, requestId, instruction
nofax_wait_for_responseWait for Nofax human responseAIdempotent
Long-poll a durable Nofax request for up to 240 seconds. If the result is pending, you MUST call this tool again with the same requestId. Repeat indefinitely until a terminal response is returned or the user explicitly changes/cancels the goal. Do not continue the guarded action while pending.
Inputs: requestId (required), waitSeconds. Returns: text, status, decision, mustWait, +3 more
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 7 tools
Each tool has a clearly distinct role: waiting, inspecting metadata, listing pending requests, one-way notification, and three distinct request-response modalities (approval, choice, refinement). The overlap between get_request and wait_for_response is explicitly contrasted in the descriptions, and the request_* tools are differentiated by response type.
All tools use the same nofax_ snake_case prefix with verb-led names, producing a predictable and readable pattern. Minor stylistic differences such as wait_for_response versus notify do not undermine consistent naming.
Seven tools are well-scoped for a durable human-in-the-loop approval and notification service. Each tool covers a necessary part of the lifecycle without obvious redundancy.
The surface covers sending notifications, requesting approval/choice/refinement, waiting, inspecting a request, and recovering pending handles. A cancellation or revocation operation for pending requests is missing, but agents can work around it by abandoning the requestId.
Maintenance
Related MCP Connectors
Human-in-the-loop for AI agents over MCP: durable approvals with a hosted review page & audit trail
Human-in-the-loop review and approval for AI agents. Audit trail, approval policies, native MCP.
Zero-secret MCP gateway for AI agents: risk-scored, audited calls with human-in-the-loop approval.
Give any AI agent a way to ask a person — for approval, a decision, an answer or a review.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceHuman-in-the-Loop authorization gateway for AI Agents. Securely pause MCP workflows and route high-risk actions to human approvers via Slack or Email.52 npm1MIT
- AlicenseNot gradedqualityDmaintenanceAdds a human-in-the-loop checkpoint to MCP-capable AI coding agents, enabling them to pause and request user feedback before executing actions.16 npm72MIT
- AlicenseAqualityBmaintenanceProvides tools to retrieve the GodPrompt universal system prompt and its components (core skill, protocols, gates, anti-patterns) for AI software development, plus task classification. Designed for progressive context usage.7981 npm2MIT
- FlicenseNot gradedqualityDmaintenanceEnables AI agents to request human decisions for subjective or high-stakes choices through MCP tools like ask_human and provision_api_key.-