MCP server
The remote MCP server AI agents use to notify your phone, with OAuth sign-in.
Decided The primary way agents (Claude Code, Codex, any MCP client) send notifications is the notifier MCP server at https://notifier.bartuozel.com/api/mcp. Agents sign in through the browser with your notifier account (OAuth 2.1 with PKCE), so there is no token to copy.
Connect
claude mcp add --transport http pocket-notifier https://notifier.bartuozel.com/api/mcp
# then, inside a session: /mcp → pocket-notifier → Authenticatecodex mcp add pocket-notifier --url https://notifier.bartuozel.com/api/mcp
codex mcp login pocket-notifierThe client opens the sign-in page in your browser. Sign in with your notifier email and password, allow access, and the client stores the tokens. Access tokens last 1 hour and refresh tokens 30 days, so you sign in again about once a month.
Sign-up stays invite-only: the sign-in page has no sign-up. Create your account from an invite link first.
Projects and features
Agents and the app say project and feature:
- A project is a product or repository, for example
rezme. The same project everywhere: in the app, the REST API and the database. Project rules apply: unique names, roles, retention. - A feature is a workstream inside a project, for example "Improving performance". In the app a feature is a conversation (a chat thread): its messages carry
conversation = { id: <feature slug>, title: <feature name> }. - A notification without a project goes to your personal General project. It is created on first need, is private (no members, no invites, cannot be deleted) and shows up in your project list with
personal: true.
Feature slugs are unique per project: lowercase letters, digits and -, up to 63 characters, derived from the name when not given ("Çok hızlı" becomes cok-hizli). A feature has a status, active, done or archived; only owners change it, and sending never changes it.
Tools
| Tool | Input | What it does |
|---|---|---|
list_projects | none | Your projects with name, displayName, description, role, isGeneral and feature counts by status. Creates General if needed. |
create_project | name, displayName?, description? | Creates a project owned by you. Idempotent: an existing project you own or publish to is returned. A name taken by someone else is an error: pick another name. |
list_features | project, status? (active default, done, archived, all) | A project's features, most recent activity first. |
create_feature | project, name, slug?, description? | Creates a feature. Idempotent by slug. Owners and publishers. |
update_feature_status | project, feature, status | Sets active, done or archived. Owners only. |
send_notification | project?, feature?, title, body?, priority?, tags?, url?, ask?, actions? | Sends a push. See below. Owners and publishers. |
project is a project name as list_projects shows it. general also names your General project, unless you have a project actually called general. feature is a slug or a name (any case).
send_notification
- Where it goes.
projectomitted: General.featureomitted: the project-level thread. - Feature auto-create rule.
featureis matched by slug, then by name (any case), then by the slug of the given text. If nothing matches, a feature with that text as its name is created, and the result sayscreated: true. Agents can send to their current workstream without creating it first. titleis the outcome, at most 32 characters by convention (the API allows 250).bodyis one line.priority1 to 5: 2 low (FYI), 3 normal (the default for done), 4 high (blocked on a decision), 5 urgent (production or data at risk). Omitted: the project's default priority.urlis where to look (PR, CI run, deploy). The app shows it as an Open button on the message in its thread and as an action on the notification. Tapping the notification itself opens the thread: the feature's, or the project-level thread whenfeatureis omitted.ask{ question?, quickReplies? (up to 3), allowText? (default true) }adds areplyaction, and the question is appended to the body. The app's thread composer answers it. Agents cannot read the reply through MCP in this version.actionsup to 2 link buttons{ label, url }.- Sender. The message's
senderis the OAuth client:{ id: <client_id>, name: <client_name> }, for example "Claude Code".publishedByis you.
The result has messageId, project, isGeneral, feature (slug, name, created) and deliveredTo, the number of subscribed, unmuted devices of the project.
Tool errors are written for agents, for example Project 'x' not found. Call list_projects to see your projects, or create_project to add it.
Protocol
-
Transport. Streamable HTTP, stateless: every
POST /api/mcpis answered on its own (one JSON body or a one-event SSE stream).GETandDELETEreturn405. No sessions, no Durable Objects. -
Auth.
Authorization: Bearer <access token>on every request. Without a valid token the answer is401withWWW-Authenticate: Bearer resource_metadata="https://notifier.bartuozel.com/.well-known/oauth-protected-resource/api/mcp", scope="notifier:read notifier:write offline_access" -
Instructions. The server sends a short guide (when to notify, how to pick project and feature, priorities) as MCP
instructions. The full version is thepocket-notifieragent skill atskills/pocket-notifier/SKILL.mdin the repository.
OAuth
The authorization server is better-auth's OAuth 2.1 provider (@better-auth/mcp), issuer https://notifier.bartuozel.com/api/auth.
| What | Where |
|---|---|
| Protected-resource metadata (RFC 9728) | /.well-known/oauth-protected-resource/api/mcp (also without /api/mcp) |
| Authorization-server metadata (RFC 8414) | /.well-known/oauth-authorization-server/api/auth, /api/auth/.well-known/openid-configuration |
| Dynamic client registration (RFC 7591) | POST /api/auth/oauth2/register |
| Authorize | GET /api/auth/oauth2/authorize |
| Token | POST /api/auth/oauth2/token |
| Signing keys | GET /api/auth/jwks |
| Sign-in and consent pages | /oauth/login, /oauth/consent |
- Clients register themselves without a session as public clients (
token_endpoint_auth_method: "none") and must use PKCE withS256. A client that omitsapplication_typeand uses a loopback or custom-scheme redirect registers as a native app. - Redirects.
http://127.0.0.1:<port>/…,http://localhost:<port>/…andhttp://[::1]:<port>/…are accepted; the port may differ from the registered one (RFC 8252). Otherhttp:redirects are refused. - Scopes.
notifier:readandnotifier:write(both required by/api/mcp),offline_accessfor a refresh token, plusopenid,profile,email. - Tokens. Access tokens are JWTs signed with the server's Ed25519 key, with the
/api/mcpURL as audience,sub= user id,azp= client id; they last 1 hour. Refresh tokens last 30 days and rotate on use. - Consent is asked once per client and scope set. The page shows the client's name and where it returns to.
- Pages. The sign-in and consent pages are plain HTML forms served by the Worker. Their posts must come from the same origin, and they cannot be framed.
Fallback: REST and agent-notify
Scripts without MCP keep using POST /api/v1/projects/{project}/messages with an access token, for example agent-notify. See Coding agents.