Keelcroft · Focus Keys documentation
Focus Keys
Agent-controlled Screen Time for iPhone. The user groups distracting apps in the Focus Keys iOS app (“Social”, “Video”, “Delivery”); the connected assistant blocks groups for a while, sets recurring windows and decides the timed passes the phone asks for — so the assistant, not willpower, holds the keys. Shields run on Apple's Screen Time framework and survive a killed app.
Endpoints
| Purpose | URL |
|---|---|
| MCP (Streamable HTTP, JSON-RPC) | https://focus.keelcroft.com/mcp |
| REST alternative | https://focus.keelcroft.com/v1/… — described by openapi.json |
| Authorization-server metadata | /.well-known/oauth-authorization-server |
| Protected-resource metadata | /.well-known/oauth-protected-resource |
| Dynamic client registration | https://focus.keelcroft.com/oauth/register |
| Connector manifest | /.well-known/muse-connector.json |
| Companion app | /app (iOS 16+; pairs with a 6-character code) |
| Health | /health |
Authentication
OAuth 2.1 authorization code with PKCE (S256). Clients register dynamically or present a Client-ID Metadata Document. Access tokens are bearer tokens valid for one hour; refresh tokens rotate on use. Scopes: focus:read, focus:manage, alerts:read. API keys (Authorization: Bearer fk_…) are available from the account page for scripts and for adding Focus Keys to an assistant as a custom connector before a directory listing is live. The iPhone app authenticates separately with a device token issued at pairing; agent tokens never reach the phone and device tokens never reach agents.
The authorization flow shows a consent page listing what the agent will be able to do, then a passwordless email sign-in (magic link). Connecting never requires payment; tools that change the phone require an active subscription and tell the agent where the user can start one.
Tools
| Tool | Approval | Description |
|---|---|---|
get_status | no | Paired phones, every group with its state (open / blocked / on a pass), active blocks and passes, pending pass requests, pass policy, subscription and a next_step hint when setup is incomplete. |
list_groups | no | App groups by name, kind and counts (apps, categories, websites). Apple never reveals which apps are inside a group. |
list_schedules | no | Recurring block windows, with the number of Screen Time monitors they consume (Apple allows 20 per phone). |
get_history | no | Recent blocks and pass requests plus plain facts: blocks ended early, passes granted / denied / unanswered, most-requested group, busiest request hour. Facts only. |
get_recent_alerts | no | Proactive events since an ISO-8601 timestamp: pass_requested, pass_granted/denied/expired, block_started/ended/extended/failed, phone_unreachable, screen_time_permission_changed, device_paired/unpaired. |
block_now | yes | Shields a group for 15–720 minutes; extends an existing block when the new end is later. Applied by the phone within seconds when online. |
end_block | yes | Lifts a block early (the agent is instructed to prefer a timed pass). |
grant_pass | no | Unlocks a group for 15–120 minutes, then it re-locks automatically. Answers a pending request from the phone (minutes may be shortened) or gives an unsolicited break; the note is shown on the phone. |
deny_pass | no | Refuses a pending request with a short note shown on the phone. |
set_schedule | no | Creates or updates a recurring window (days, start, end in the phone's local time; overnight windows supported; 15-minute minimum). |
delete_schedule | yes | Removes a recurring window. |
set_settings | no | Pass policy when no assistant answers (wait / auto-grant within a daily budget / always deny), default pass length, request timeout, the assistant's display name on the shield, optional alert email. |
create_pairing_code | no | 6-character code (10-minute expiry, single use) the user types into the iPhone app to attach it to the account. |
Tool results include both human-readable text and structuredContent. Times are returned in the phone's time zone alongside ISO-8601 UTC.
Consent and safety design
- The user installs the app on their own iPhone, grants Apple's Screen Time permission themselves and pairs the phone with a code. Unpairing (in the app or on the dashboard) lifts every shield set through Focus Keys and removes the phone's data.
- Which apps are in a group never leaves the phone: Apple's selection tokens are opaque and device-bound. The server stores group names, kinds and counts only. Screen-time minutes and app usage are never collected.
- Passes are timed unlocks that re-lock on their own (on the phone via a DeviceActivity window and, belt-and-braces, by a server re-apply). Unanswered pass requests expire after the account's timeout and the block stays.
- Blocking, unblocking early and deleting schedules are marked as requiring the user's approval. The agent instructions tell it to coach, not lecture, and to report history as counts and times, never judgements.
- Focus Keys is a productivity tool for adults managing their own devices — not a medical, mental-health, safety or parental-control product.
Access requirements
- iPhone on iOS 16 or later with the Focus Keys app; the account holder must be 18+.
- Subscription: $6.99/month or $49.99/year per account (all the user's phones), billed by Dodo Payments (merchant of record), cancel any time; no free trial, 30-day refund on request. Schedules and blocks set on the phone itself never need a subscription. Reviewers using the test path need no subscription.
- Limits from Apple's Screen Time framework: blocks 15–720 minutes, passes 15–120 minutes, at most 20 monitored windows per phone.
Reviewer test path
No iPhone is needed. Reviewers receive a private reviewer link that signs in a demo account with a simulated iPhone (three groups, a “Weeknights” schedule) and a 90-day entitlement. Commands sent to the simulated phone are acknowledged automatically within seconds, and the dashboard has buttons to make the phone “ask for a pass”, so every tool outcome — block, extend, pass requested/granted/denied/expired, schedule changes, alerts — can be exercised in minutes. The link is supplied with the submission, not published here.
Data handling
Collected: account email and time zone; per phone its name, model, iOS and app version, a push-notification token and whether Screen Time access is granted; per group its name, kind and counts; schedules, blocks and pass requests with the reasons the user typed and the notes the agent wrote; a command and event log (events kept 90 days). Shared with Cloudflare (hosting), Expo (push delivery), Resend (email), Dodo Payments (billing) and the connected agent (only what it requests). Never sold or used for advertising. Unpairing a phone removes its groups, schedules and commands; deleting the account (in-app or on the account page) removes everything. Full text: privacy policy, terms.
Support
support@keelcroft.com · security reports: same address, subject “Security”.