OAuth for MCP clients

Supported authorization

Message.com implements OAuth for its MCP resource at https://app.message.com/api/v1/mcp. This is not a general-purpose OAuth app marketplace granting access to every dashboard REST route.

For a direct product integration, use that product’s documented API-key scopes. For MCP, discover the authorization server and supported scopes rather than guessing endpoint names or requesting broad dashboard access.

Discover the server

Read https://app.message.com/.well-known/oauth-protected-resource/api/v1/mcp and then the authorization-server metadata at https://app.message.com/.well-known/oauth-authorization-server/api/v1/mcp/oauth. Metadata supplies registration, authorization, token and revocation endpoints and supported scopes.

Register the client

POST JSON to the advertised registration endpoint. The client is public: token_endpoint_auth_method is none and no client secret is issued. Redirect URIs must be HTTPS, contain no user information or fragment, and match exactly during authorization and token exchange. Register between one and five redirect URIs.

{
  "client_name": "Example AI client",
  "redirect_uris": [
    "https://example.com/oauth/callback"
  ],
  "token_endpoint_auth_method": "none",
  "grant_types": [
    "authorization_code"
  ],
  "response_types": [
    "code"
  ]
}

Request consent

Send response_type=code, the registered client_id and redirect_uri, resource=https://app.message.com/api/v1/mcp, state (16–2048 characters), code_challenge and code_challenge_method=S256 to the authorization endpoint. The challenge is the unpadded base64url SHA-256 of a securely generated PKCE verifier. Keep that verifier and state in the initiating client session.

scope is a space-separated subset of the advertised permissions. Without it, the defaults are automation:read, mcp:inbox:read and mcp:knowledge:read. A workspace administrator reviews the requested permissions and may approve a subset or decline. Validate the returned state and issuer before exchanging the code.

Exchange the code

POST grant_type=authorization_code, client_id, redirect_uri, resource, code and code_verifier to the token endpoint. JSON and form-encoded bodies are supported. An approved code expires after two minutes and is single-use.

The response contains access_token, token_type=Bearer, expires_in=28800 and scope. The token is bound to the MCP resource and approved permissions; it is not a general dashboard session. Send it in the Authorization header when calling MCP. Keep credentials out of logs and public scripts.

Expiry and revocation

Access tokens last eight hours. Refresh-token grants are not implemented and no refresh_token is returned. Repeat the authorization flow when access expires.

POST token to the advertised revocation endpoint to revoke an MCP token. Revocation acknowledges with HTTP 200 and an empty JSON object. Workspace administrators can also manage credentials in their account. Provider connections still require their own setup and product entitlements.