GrantTap MCP

Keep Codex and Claude Code moving from your iPhone or Apple Watch.

Approve commands, follow active tasks, reply, attach files, start new work, and run local schedules without exposing agent traffic to the relay. GrantTap MCP is the open-source machine-side bridge: the agents stay on your Mac, and Cloudflare only routes authenticated ciphertext it cannot decrypt.

Website · npm · Security model · Self-hostable relay

The companion iPhone and Apple Watch app is currently in testing. Release status is published at granttap.com.

What you get

• Real approvals away from the Mac. Claude Code or Codex pauses at its permission hook; Allow or Deny returns to that same agent flow.
• One task view for both agents. See recent Codex and Claude Code tasks, human-readable activity, delivery state, usage, and context data the agent actually exposes.
• Continue work from the phone. Reply to an existing task or create a new one for the selected agent and advertised workspace. Send up to five photos, camera images, or documents in one message.
• A useful Watch app, not an approval-only notification. Browse tasks, open recent activity, approve a command, or reply by voice or text.
• Per-task controls that are enforced locally. Inspect MCP servers and repository skills, disable MCP servers for later GrantTap-delivered turns, choose a relevant MCP or skill, and select Codex sandbox access.
• A local scheduler, not a pretend provider API. Create recurring Codex or Claude Code runs manually or through a conversational planner, then inspect the run history from the phone.
• Receipts instead of optimistic UI. Messages have stable IDs, encrypted accepted/rejected receipts, bounded retries, and queued/sending/delivered/ failed state.

See it in action

iPhone

| Command center | Codex task controls | Observed MCP usage | Claude Code and scheduler | | --- | --- | --- | --- | | | | | |

The Codex task screen exposes the context window, supported compaction, MCP allow/deny state, and sandbox access. Claude Code gets its own visual treatment and planner while keeping its different permission and compaction limits clear. MCP usage counts only observed calls; context figures are labelled estimates, not separate MCP billing.

Apple Watch

| Task inbox | Recent activity and reply | Command approval | | --- | --- | --- | | | | |

Connect in under a minute

Add GrantTap to each agent you use:

npm install
npm install -g .
codex mcp add granttap -- granttap
claude mcp add granttap -- granttap

Those commands use this checkout. Publish/release it before replacing the local install with an npm registry version.

Start a fresh agent task and say “Connect GrantTap.” The connect tool:

1. creates a new end-to-end encrypted pairing;
2. returns a scannable one-time QR directly in the agent chat.

Then run the separate MCP setup tool. It installs Cursor shell/MCP policy hooks, the complete Claude Code matcher, both Codex hooks, and the per-user background helper for task sync and schedules.

Scan the QR with GrantTap on iPhone. No terminal QR, copied pairing JSON, or open background terminal is required.

If an MCP client cannot render image content, use the CLI fallback:

npm install -g granttap-mcp
granttap connect
granttap setup
granttap status

CLI connect prints a one-time QR and short manual code. setup is idempotent: it preserves unrelated agent settings and backs up a configuration file before changing it. The pairing is stored locally in ~/.granttap/machine.json. Existing beta state under ~/.nodvox/ is migrated automatically.

After setup, open /hooks in Codex, review and trust both exact GrantTap hooks, then restart Codex. Installation alone is not reported as trusted or connected.

Cursor Settings → Authorize

Cursor only shows Authorize / Sign in for HTTP/SSE MCP servers that speak OAuth (same pattern as Lovable / Figma). The default stdio entry (command + args) cannot show that button — Cursor documents stdio auth as Manual.

To enable Authorize for GrantTap, use the one-step local setup:

npm install -g granttap-mcp
granttap authorize

It preserves unrelated entries in ~/.cursor/mcp.json, replaces only the granttap entry with the loopback HTTP endpoint, keeps a one-time .bak-granttap, and starts the OAuth MCP server. Then open Cursor Settings → MCP → GrantTap → Authorize. The local consent page shows the pairing QR plus a manual-token fallback when the Mac is not paired yet. granttap authorize installs a loopback-only per-user LaunchAgent, verifies its exact /healthz identity, writes Cursor config only after that check succeeds, and exits. The service uses RunAtLoad + KeepAlive, so closing the terminal or restarting the Mac does not leave Cursor pointing at a dead URL.

The foreground troubleshooting flow is:

1. Run the local HTTP OAuth server (loopback only):

granttap serve
# listens on http://127.0.0.1:17342/mcp

2. Point Cursor at the HTTP URL in ~/.cursor/mcp.json (replace the stdio command entry):

{
  "mcpServers": {
    "granttap": {
      "url": "http://127.0.0.1:17342/mcp"
    }
  }
}

3. Open Cursor Settings → MCP → GrantTap and click Authorize. A local browser page confirms linking Cursor to this Mac’s pairing (~/.granttap). If unpaired, it shows a one-time QR first.

OAuth tokens are stored in ~/.granttap/mcp-oauth.json (mode 0600). They do not replace E2EE pairing keys. Claude Code / Codex can keep using the stdio transport; Authorize is a Cursor Settings affordance.

Details: docs/cursor-authorize.md.

granttap setup is the policy-hook entry point: it installs Cursor beforeShellExecution, afterShellExecution, and beforeMCPExecution hooks, plus Claude/Codex hooks and background task sync. It does not opt a new user into OAuth; when an exact Cursor HTTP entry already exists, it also repairs the persistent OAuth service. Per-chat blocks are checked before phone routing, and ambiguous/unscoped Cursor calls fall back to Cursor's native permission UI.

Codex and Claude Code: honest capability matrix

| Capability | Codex | Claude Code | | --- | --- | --- | | Approval hook | PermissionRequest when Codex hooks are enabled | PreToolUse | | Resume an existing task | Yes, through the local Codex CLI | Yes, through the local Claude CLI | | Start a new persistent task | Yes | Yes | | Up to five attachments within one encrypted-frame budget | Images through Codex image inputs; documents as local paths | Local image/document paths in the turn | | Change filesystem access from iPhone | Read-only, workspace, or full for the next GrantTap turn | Not exposed; the existing Claude policy remains authoritative | | Disable MCP per task | Enforced for later GrantTap-delivered turns | Enforced for later GrantTap-delivered turns | | Usage and context | Reported when present in local task logs | Reported when present in local task logs | | Trigger real context compaction | Yes, for an idle task through Codex app-server | No supported remote API; GrantTap reports this honestly | | Conversational schedule planner | Ephemeral read-only run | Ephemeral plan-mode run |

GrantTap controls local Codex and Claude Code tasks. It does not claim to create ordinary ChatGPT chats, private ChatGPT Scheduled Tasks, Codex Automations, or Claude Routines through unpublished provider APIs.

Globally disabled MCP servers stay disabled. A phone choice only narrows later turns sent through GrantTap; it cannot broaden the agent's global configuration. Repository skills are discovered only in the selected task workspace under .agents/skills or .claude/skills.

MCP tools

| Tool | Result | | --- | --- | | connect | Creates a pairing and returns a secure one-time QR in chat | | ask | Sends an open question and waits for a spoken or typed reply | | ask_yes_no | Sends a yes/no question and waits for a tap | | notify | Sends a non-blocking status update | | setup | Registers Cursor/Claude/Codex policy hooks and the terminal-free helper |

The default answer timeout is three minutes. Override it with GRANTTAP_ASK_TIMEOUT_MS.

Why the relay cannot read a session

• Endpoint keys are generated locally. The relay never receives a device's secret encryption key.
• Pairing hand-off uses an opaque mailbox ID plus an independent 256-bit transfer key. Only the mailbox ID reaches Cloudflare; the key stays in the QR or manual token.
• Every attached Codex or Claude Code task receives its own random 256-bit task key. Disclosure of one task key cannot decrypt another task.
• Questions, commands, replies, attachments, approvals, scheduler drafts, and task activity remain authenticated ciphertext across the network, relay, Durable Objects, and APNs path.
• APNs carries only a content-neutral wake. It contains no title, prompt, command, path, task kind, or response.
• Cloudflare accepts at most a 32 MiB WebSocket frame. Because task messages are sealed and base64-encoded twice, attachments share a 16,000,000-character base64 budget (about 12 MB raw total); five small files fit, five 6 MB files do not.

The in-chat QR is marked user-only for MCP hosts, but that annotation is not a cryptographic separation from the model provider. Use CLI connect when the model provider itself is part of your threat model; Cloudflare still receives only the mailbox id and ciphertext in either flow.

The relay can still observe operational metadata: opaque room/mailbox IDs, IP addresses, timing, ciphertext sizes, and APNs device token/environment. A compromised authorized endpoint can read the tasks explicitly granted to that endpoint; cryptography cannot hide plaintext from a device authorized to show it. The exact boundary and threat-model limits are documented in SECURITY.md.

Task sync and scheduling

The background helper publishes a bounded window of recent local Codex and Claude Code task metadata. Older chat metadata is available separately for up to 90 days and 160 chats; full activity for a task is sent only after the phone subscribes to it. Hidden reasoning is never converted into visible activity.

New phone-created tasks default to an isolated per-agent GrantTap workspace. The phone can instead select a same-agent folder already advertised by a recent local task. The helper rejects arbitrary unadvertised paths.

Schedules use standard five-field cron in the Mac's timezone. The app supports hourly, daily, weekday, selected-weekday, and monthly series, plus enable, disable, edit, delete, and run-now actions. Every run records local start/end time, agent, status, result, and created task ID.

CLI commands

| Command | Purpose | | --- | --- | | (no command) | Starts the GrantTap MCP stdio server | | serve | HTTP MCP + loopback OAuth for Cursor Settings → Authorize | | authorize | Installs the persistent loopback OAuth service, verifies health, and configures Cursor | | connect [relayUrl] | Creates an E2EE pairing; optionally targets a self-hosted wss:// relay | | setup | Registers Cursor/Claude/Codex hooks, background sync, and repairs configured OAuth | | status [--json] | Reads local readiness; JSON uses granttap.provider-status.v1 and contains no keys |

The installed public command is granttap; granttap-mcp remains an alias for existing scripts. status only reads configuration and runtime state—it does not install hooks, pair a device, start OAuth, or reload the background helper. If Cursor has an HTTP GrantTap entry, status requires both an owned persistent service and a live identity-checked health response; a dead URL is never shown as connected. Without an HTTP entry, OAuth remains optional and Cursor policy readiness is based on the full hook set, pairing, and background sync.

Development

Requires Node.js 20 or newer.

git clone https://github.com/sergii-ziborov/granttap-mcp.git
cd granttap-mcp
npm install
npm test
npm run typecheck

Start the stdio server with npm start. Run npm run setup only on a machine where you want GrantTap hooks installed.

Links

• GrantTap product site
• granttap-mcp on npm
• Public relay source
• Privacy
• Support
• Security policy

GrantTap is not affiliated with Anthropic or OpenAI.