# MCP reference

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

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

## OAuth and discovery

1. The first unauthenticated call returns `401` with a `resource_metadata` discovery pointer. The client discovers OAuth endpoints and dynamically registers.
2. Open the consent page in the browser and sign in with Apple or Google.
3. Review each permission, deselect unwanted scopes, and approve. Consent is remembered for that client and permission set.
4. The client receives a one-hour access token restricted to `/mcp`. Stay connected adds a refresh token.

Tool permissions use the agent scope names. `offline_access` enables Stay connected. A client omitting scopes requests all scopes except `tokens:manage`. The authorization flow requires S256 PKCE and MCP-specific resource binding.

Disconnect a client in the dashboard to revoke its access and refresh tokens. A connection with `tokens:manage` can also list OAuth connections as `kind: "oauth"` through `/api/agent/tokens` and revoke them.

| 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.

> 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.