Skip to main content
The Qwairy MCP server uses OAuth 2.1 with PKCE for secure authentication. Your credentials are never shared with AI clients — only a secure, scoped access token.

​
How It Works

Most MCP clients handle this flow automatically. You just click “Authorize” when prompted — no manual token management needed.

​
OAuth Endpoints

EndpointURL
Discoveryhttps://mcp.qwairy.co/.well-known/oauth-authorization-server
Authorizationhttps://auth.qwairy.co/authorize
Tokenhttps://auth.qwairy.co/token
Modern MCP clients automatically discover these endpoints from the server URL. You only need to provide https://mcp.qwairy.co — the client fetches the OAuth configuration via the discovery endpoint.

​
Available Scopes

Request only the scopes you need:
ScopeDescription
read:brandsList monitored brands
read:visibilityAccess performance metrics
read:competitorsView competitor data
read:sourcesAccess source/citation data
read:promptsList monitored prompts
read:answersRead AI responses
read:topicsView topic analytics
If no scopes are specified, all scopes are granted by default.

​
Token Lifecycle

TokenDurationRefresh
Access Token1 hourAutomatic via refresh token
Refresh Token30 daysNew token issued on use
Authorization Code5 minutesOne-time use

​
PKCE Support

The server supports both PKCE methods:
  • S256 (recommended) — SHA-256 hash of code verifier
  • plain — Code verifier sent as-is
Most MCP clients automatically use S256 for maximum security.

​
Security Features

Your Qwairy password is never shared with any AI client. Authentication happens directly with Qwairy’s auth server.
Tokens are scoped to specific data types. An MCP client can only access what you’ve authorized.
Tokens are tied to your team, not just your user account. All team members’ data for brands you have access to.
Access tokens expire after 1 hour. If a token is compromised, exposure is limited.
You can revoke access at any time from your Qwairy account settings.

​
Manual Token Exchange

For developers building custom MCP clients, here’s the token exchange flow:

​
1. Start Authorization

GET https://auth.qwairy.co/authorize
  ?response_type=code
  &client_id=mcp-client
  &redirect_uri=YOUR_CALLBACK_URL
  &scope=read:brands read:visibility
  &state=RANDOM_STATE
  &code_challenge=BASE64URL_SHA256_OF_VERIFIER
  &code_challenge_method=S256

​
2. Exchange Code for Tokens

POST https://auth.qwairy.co/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=AUTH_CODE_FROM_CALLBACK
&redirect_uri=YOUR_CALLBACK_URL
&code_verifier=ORIGINAL_CODE_VERIFIER
Response: 
{
  "access_token": "qw-mcp-abc123...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "qw-mcpr-xyz789...",
  "scope": "read:brands read:visibility"
}

​
3. Refresh Token

POST https://auth.qwairy.co/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&refresh_token=qw-mcpr-xyz789...

​
Troubleshooting

​
”Invalid or expired token”

Your access token has expired. The MCP client should automatically refresh it. If the error persists, disconnect and reconnect.

​
”Insufficient scope”

The tool you’re trying to use requires a scope that wasn’t granted. Reconnect and authorize all requested scopes.

​
”Team not found”

Your Qwairy account doesn’t have an active team, or the team’s subscription has expired.