OAuth integration

The MCP server advertises its authorisation server through protected-resource metadata:

GET https://mcp.brandvisibility.ai/.well-known/oauth-protected-resource

For staging, use mcp-staging.brandvisibility.ai. Discover endpoints from the metadata instead of hard-coding a different environment’s URLs.

Discovery

The matching API publishes authorisation-server metadata at:

GET /.well-known/oauth-authorization-server/api/v1/mcp/oauth

The issuer is https://api.brandvisibility.ai/api/v1/mcp/oauth in production and https://api-staging.brandvisibility.ai/api/v1/mcp/oauth in staging. Discovery names the registration, authorisation and token endpoints.

Public-client flow

1. Register the client and its exact redirect URI at the advertised registration endpoint.
2. Generate a cryptographically random PKCE verifier and its S256 challenge. Generate and validate an OAuth state value.
3. Open the advertised authorisation endpoint with response_type=code, client_id, redirect_uri, code_challenge, code_challenge_method=S256, scope=reporting:read, and the matching MCP endpoint as resource.
4. The person signs in and approves an organisation and permitted teams in BrandVisibility. Clients must not bypass the consent screen or call its dashboard-only approval endpoints.
5. Exchange the returned code at the advertised token endpoint using form-encoded grant_type=authorization_code, client_id, redirect_uri, code, code_verifier, and the same resource.
6. Present the resulting access token as a Bearer credential to the MCP endpoint.

Only the authorisation-code flow with S256 PKCE and refresh-token grant is supported. The registration response describes the supported redirect URIs and client metadata. Public clients do not need a client secret.

Refresh and disconnect

Use grant_type=refresh_token, client_id, refresh_token, and the matching resource at the token endpoint. Store each replacement refresh token atomically. Refresh tokens rotate; do not reuse an old token or run concurrent refreshes for the same token family. An authorisation code is single-use.

An MCP 401 response advertises the resource-metadata URL in WWW-Authenticate. Refresh when appropriate; if the approval has ended, ask the person to reconnect. Revocation, expired plan access, or membership changes can stop an existing connection.

BrandVisibility’s dashboard consent and organisation administration routes are not part of the third-party integration contract. Use the public OAuth flow and the dashboard to manage approvals.