# MCP OAuth

> How MCP clients sign in to the hosted SendDart MCP server: discovery, client registration, authorization code with PKCE, tokens and revocation.

The hosted MCP server at `https://www.senddart.com/mcp` is an OAuth 2.1 protected resource, following the [MCP authorization specification](https://modelcontextprotocol.io/specification). Most MCP clients do all of this for you; this page is for people building one.

## Discovery

A request without a token gets `401` with a challenge that points to the protected-resource metadata:

```http
WWW-Authenticate: Bearer resource_metadata="https://www.senddart.com/.well-known/oauth-protected-resource/mcp", scope="full_access sending_access"
```

| Document | URL |
| --- | --- |
| Protected resource metadata (RFC 9728) | `/.well-known/oauth-protected-resource/mcp` (also at `/.well-known/oauth-protected-resource`) |
| Authorization server metadata (RFC 8414) | `/.well-known/oauth-authorization-server` |

The issuer is `https://www.senddart.com`. The resource indicator (RFC 8707) to send as `resource` is `https://www.senddart.com/mcp`.

## Endpoints

| Endpoint | Purpose |
| --- | --- |
| `GET /oauth/authorize` | Authorization code request. `response_type=code`, PKCE `code_challenge_method=S256` required, `state` returned as sent, `iss` added to every response (RFC 9207). |
| `POST /oauth/token` | `authorization_code` (with `code_verifier`) and `refresh_token` grants. |
| `POST /oauth/register` | Dynamic client registration (RFC 7591). Limited per IP to 20 an hour and 100 a day. |
| `POST /oauth/revoke` | Token revocation (RFC 7009). Revoking a refresh token disconnects the app. |

## Client registration

- **Client ID Metadata Documents** — use an HTTPS URL as your `client_id`; SendDart fetches it (no redirects, 10 KB max) and requires its `client_id` to equal the URL. Only public clients (`token_endpoint_auth_method: "none"`). The client is stored once someone approves it; at most 10 per host.
- **Dynamic registration** — `POST /oauth/register` with `redirect_uris` (at most 10). Omitting `token_endpoint_auth_method` means `client_secret_basic` (RFC 7591); send `"none"` for a public client.
- Redirect URIs must be `https`, or `http` on `localhost`, `127.0.0.1` or `[::1]`. They are matched exactly, character for character. Custom URL schemes are not accepted.

## Scopes and permissions

| Scope | Means |
| --- | --- |
| `full_access` | Same as a full-access API key: every tool, except that a connected app can never create, change or revoke API keys (`403 connected_app_forbidden`). |
| `sending_access` | Same as a sending-access API key: sending only, optionally limited to chosen domains. |

The scope you request only preselects the choice; the person approving picks the permission, and the token response says which one was granted.

## Tokens

- Authorization codes are single use and expire after 60 seconds. Reusing one revokes the connection it created.
- Access tokens last 1 hour. Send them only in the `Authorization: Bearer` header of requests to `/mcp`.
- Refresh tokens last 30 days and rotate: every refresh returns a new one and retires the old. Retrying the token you just used within 60 seconds (a lost response) gets `invalid_grant` and changes nothing; presenting any older one, or the same one later, revokes the connection.
- SendDart stores only hashes of codes and tokens.

## Disconnecting

People disconnect apps under **Settings → Integrations → MCP server → Connected apps**; apps can revoke their own refresh token at `/oauth/revoke`. Either way access stops at once, for `/mcp` and for the API.
