MCP reference

For API-key MCP access, configure your client’s HTTP headers with Authorization: Bearer followed by your scoped ntf_ or ak_ user API key. Save the value in the client’s secure credential settings. This path does not use OAuth client IDs, client secrets, or browser consent; route scope checks still apply.

Tool permissions use the agent scope names. Request and inspect the needed scopes explicitly; offline_access concerns refresh access, not additional tool permissions. Every registered client requires S256 PKCE, including confidential clients. The OAuth resource/audience is exactly https://notify.belweave.ai/mcp; direct authorization and token requests must use that resource.

Disconnect a client in the dashboard to stop its access. A connection with tokens:manage can also list OAuth connections as kind: "oauth" through /api/agent/tokens and revoke them. Disconnecting a Clerk OAuth client also blocks that client ID for your Notify account, covering other independent grants for the same client. Reconnecting requires a newly registered client ID; merely obtaining another token for the disconnected client does not restore access.

If a hosted client asks for a static OAuth client ID, use Dashboard → Connected MCP clients → Custom OAuth clients when available. Obtain the exact callback URL from the client before registering; do not guess a callback for Meta Muse or another hosted service. Callbacks must be HTTPS, with HTTP allowed only for localhost, 127.0.0.1, or IPv6 loopback clients. Select the required permissions. Public clients have no secret. Choose a confidential client only when its server can securely store a secret, and save the secret when it is shown once. PKCE remains required.

Copy the issuer, authorization endpoint, and token endpoint displayed by Notify rather than deriving URLs from a client ID. The manual authorization and token endpoints from /api/oauth/config are Notify compatibility endpoints: they bind an omitted resource to the Notify MCP URL and reject a different resource. If your client supports a resource field, set it explicitly to https://notify.belweave.ai/mcp. Discovery clients should follow the advertised metadata. Rotate a confidential client secret to replace a lost or exposed secret, then update the client’s secure settings. A missing callback, unsupported PKCE, or an unavailable registration feature must be resolved before retrying OAuth; use scoped API-key MCP when the client supports Bearer headers.

MCP exposes the supported agent operations through the same handlers, validation, scopes, and limits, plus helpers such as ask. A missing permission becomes a tool error identifying the required scope.

• notify creates an update; notification_withdraw requests its removal.
• ask creates a choice/reply question. Notification presentations wait for at most 25 seconds per MCP call, then return the existing interaction with timedOut: true if it is still pending. Continue with interactions_wait and that same interaction.id; each wait call also waits at most 25 seconds. Older requested timeoutSeconds values up to 600 remain accepted but are capped to this waiting budget. Creation and progress reporting consume the ask budget; stalled creation or network transport can still exceed 25 seconds of wall-clock time. The prompt expiry is separate and a wait timeout never cancels it. With presentation: live_activity, it returns the pending interaction immediately with accepted: 0 and queued: N; use interactions_wait or interactions_get with the same creating token to observe a server-confirmed answer. Queued delivery is not provider acceptance or approval. For separate steps, use interactions_create, interactions_wait, interactions_get, interactions_list, and interactions_cancel.
• activities_start, activities_update, activities_end, activities_get, and activities_list manage ongoing work.
• services_*, devices_*, events_list, activity_feed, inbox_*, apps_*, billing_get, and tokens_* cover account resources.
• teams_*, groups_*, oncall_*, pages_*, and connectors_* cover shared workplace resources and internal-service connections. webhooks_* manages account reply endpoints.
• auth_status inspects the current grant; auth_revoke disconnects it.

Personal offline mini apps expose mini_apps_list, mini_apps_get, mini_apps_review, mini_apps_export, mini_apps_offer, mini_apps_report, mini_apps_block, mini_apps_disable, and mini_apps_remove. These use the same owner-only API routes. Offer requires apps:write and notifications:send and sends a push only when explicitly invoked; native installation requires consent.