Skip to content
notific.menotific.menotific.me

AI agents and MCP

AI agents are in production and need to ask people for permission safely, with an audit trail and little friction. notific.me gives them two ways in: the SDK and the official MCP server.

The MCP server has two jobs:

  1. Human in the loop. An agent asks for approval or asks a question and waits for the signed answer. It can also notify what it is doing.
  2. Workspace administration. It can configure and audit the whole workspace (services, tokens, rules, hooks, webhooks, audit, usage), always limited to the token’s scopes, and with human approval for every write by default.

Connect

Section titled “Connect”
Item Value
Transport Streamable HTTP, stateless, JSON responses
URL https://<api>/v0/mcp
Authentication Authorization: Bearer nm_svc_… (a service token)
Tools Only those the token’s scopes allow (tools/list is already filtered)

Create a service of kind AI agent in Services & tokens, then a token. The Agents page of app.notific.me shows the exact commands for your account.

Terminal window
claude mcp add --transport http notificme https://api.notific.me/v0/mcp --header "Authorization: Bearer nm_svc_..."

Tools

Section titled “Tools”
Tool Scope What it does
whoami any Workspace, service, scopes, locked scopes, limits and the available tools.
request_approval asks:write (+asks:read to wait) A yes/no question with summary, details, risk, level and deadline. Waits up to 55 s per call and returns approved, status, note and as_text.
ask_human asks:write A full question set (yes/no, options, text, number, date), with optional wait.
get_answer asks:read Status and reply of a question (long-poll up to 55 s).
notify events:write Sends an event: title, summary, severity, type, card_id for live cards, dedup_key, ttl, expires_when.

With workspace:read, the agent can read everything (list_rules, simulate_event, search_events, get_usage…). With write scopes it gets create_rule, put_hook, create_token, resend_webhook and others. audit:read adds search_audit and list_agent_activity.

Resources: notificme://guide (the agent guide: how to ask, levels, good practices, what is untrusted text), notificme://schemas/{event,question-set,card,reply} and notificme://workspace. Prompts: human_approval_gate, audit_review and design_rules.

Human approval for writes

Section titled “Human approval for writes”

Each token has approval_scopes: write scopes that need a person’s approval every time they are used. Tokens of ai_agent services are created with approval on for all their write scopes. The lock is enforced by the API, not just MCP, so an agent cannot avoid it by calling REST directly.

Human approval for an agent's writeAn AI agent token tries a locked write and receives 403 approval_required. It creates an approval with POST /v0/approvals, which becomes a question for the workspace owners. A person approves or denies in the app. The agent repeats exactly the same request with the Notificme-Approval header; the server checks token, method, path and body hash, consumes the approval once and executes it. Over MCP, wait_for_approval does this automatically.Agent tries a writee.g. delete_rule403 approval_requiredscope + request_hashPOST /v0/approvalsmethod · path · body· reasonQuestion for ownersreason marked asunverified agent textA person decidesapprove or denyin the appSame request again+ Notificme-Approvalsingle use, 15 minExecuted and auditedaudit: via mcp+ approval_idapproved
  1. The token tries a locked write and receives 403 approval_required with the scope and a request_hash.
  2. It asks for approval with POST /v0/approvals (method, path, body and a reason). The server creates a question for the workspace owners, showing what will happen, the body with secrets masked, and the reason marked as unverified agent text.
  3. A person approves or denies in the app.
  4. The token repeats exactly the same request with the Notificme-Approval: <approval_id> header. The server checks token, method, path and body hash, consumes the approval (single use, valid for 15 minutes) and executes it.

Over MCP this is automatic: the write tool returns {"status": "approval_pending", "approval_id": …} and wait_for_approval waits for the decision and, if approved, runs the stored operation.

Safety rules

Section titled “Safety rules”
  • Fail closed: any workspace route not mapped to a scope answers 403 to tokens.
  • A token only sees its own workspace.
  • People answer, tokens do not: POST /v0/replies always requires a person’s session.
  • Inviting people, changing roles, removing members and creating workspaces require a person (403 user_session_required).
  • A token issued by another token can only have a subset of its scopes, must keep its approval locks and expires in at most 90 days.
  • Free text from people (note, free_text) and from events is marked untrusted in tool results.
  • Every tool call is logged in Agents → Activity for 90 days, with secrets removed, and every write appears in the Audit log with via: "mcp" and the approval_id.