# MCP reference

API-key and OAuth connections, granted scopes, and the tool families available to a remote client. For configuration snippets, use [Connect an MCP client](https://notify.belweave.tech/docs/quickstart#mcp-connect).

HTML: https://notify.belweave.tech/docs/mcp

## OAuth and discovery

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.

1. For OAuth, the first unauthenticated call returns `401` with a `resource_metadata` discovery pointer. Follow that metadata to the current authorization server. Use dynamic registration when the server advertises it and the client supports it; do not assume every hosted client registers automatically.
2. Open the consent page in the browser and sign in with Apple, Google, or AgentID.
3. Review the requested permissions and approve only the access you intend to grant. The server and client determine the consent screen; do not assume that omitting a scope grants a particular permission.
4. The client exchanges its code using PKCE and receives an access token bound to `https://notify.belweave.ai/mcp`. Follow the token response for expiry; the legacy OAuth service and Clerk need not use the same token lifetime. Request `offline_access` when a refreshable connection is needed and supported.

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.

> MCP discovery and the authentication challenge advertise the default connection scopes, excluding privileged `tokens:manage`. Listing or revoking credentials requires an API key with that scope or an explicitly configured OAuth client and grant that allow it. If a client reports that it is not allowed to request `tokens:manage` during ordinary setup, refresh its discovery metadata and retry authorization without that scope. Do not disconnect a working dashboard connection just to refresh discovery; disconnection revokes its client access.

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.

| Route | Purpose |
| --- | --- |
| `GET /.well-known/oauth-protected-resource/mcp` | Protected resource metadata (RFC 9728) for the MCP server. |
| `GET /.well-known/oauth-authorization-server` | Authorization server metadata (RFC 8414): authorize, token, and registration endpoints. |

## Tool inventory

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.

> Mini-app publish and archive download use the CLI for deterministic exact bytes, with a 12 MiB archive maximum, rather than large raw contents in MCP tool text. Signing keys remain part of the authenticated native trust operation. MCP metadata export does not export archive bytes or local app data.

> MCP does not add human-answer, page-acknowledgement/escalation, invite-acceptance, app-consent/pass, or token-creation operations. Sensitive webhook URLs and join links returned by creation tools are marked as secrets.