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 — there’s no team to pick and no manual token management. The connection is user-scoped: it can read every MCP-eligible workspace you belong to.

​
OAuth Endpoints

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:
If no scopes are specified, all read scopes are granted by default. A request that specifies only unrecognized scopes is rejected with invalid_scope.
read:measure and read:pitch-audits are newer scopes. Existing OAuth connections must reconnect and re-authorize to gain access to their tools. Scopes are never expanded silently on an already-issued token.

​
Token Lifecycle

The OAuth flow issues a single user-scoped access token — the same kind of token as a Personal Access Token (qw-usr-). It is long-lived and has no refresh token: there is nothing to rotate, and clients simply reuse the bearer until it is revoked.

​
Personal Access Tokens

For headless clients that cannot run an interactive OAuth flow — automation platforms (n8n, Make), scripts, or custom agents — Qwairy supports user-scoped Personal Access Tokens (PATs). Create and revoke them from your Qwairy account under Settings → MCP.
  • A PAT is prefixed qw-usr- and is tied to your user account, not a single team.
  • It can read every team you belong to that is on an MCP-eligible plan (Starter and above), so one token covers all your workspaces.
  • Pass it as a bearer token: Authorization: Bearer qw-usr-....
  • Like the OAuth access token, a PAT has no fixed expiry. Revoke it from Settings → MCP when it is no longer needed.
PATs are read-only, like all Qwairy MCP access — they never expose write operations.

​
Choosing a team

Brand-scoped tools take a brandId, and Qwairy resolves the owning team automatically. Call list_brands first, then pass the brandId you want. list_pitch_audits is the other cross-workspace discovery tool: it lists only agency workspaces the token may access and accepts an optional teamId filter. Detail calls still resolve one audit from one authorized workspace, so data is never mixed across teams.

​
PKCE Support

The server requires PKCE with the S256 method only:
  • S256 — SHA-256 hash of the code verifier
The plain method is not supported. Most MCP clients use S256 by default, so no extra configuration is needed.

​
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.
Both OAuth connections and Personal Access Tokens are user-scoped (qw-usr-): they span every MCP-eligible team you belong to. Each tool call still resolves to exactly one team from the requested brandId — Qwairy never mixes data across teams on a single call, so workspaces stay fully isolated even though one token reaches several.
The authorization code is single-use and expires after 5 minutes, so the window to exchange it for a token is tight. The issued access token itself is revocable at any time (see below).
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

​
2. Exchange Code for Tokens

Response:
The access token is a long-lived, user-scoped token (qw-usr-). There is no refresh_token or expires_in — reuse the bearer until you revoke it.

​
3. Reuse or Revoke

The token does not expire and has no refresh step — reuse the bearer for subsequent requests. To rotate it, revoke the old one and run the authorization flow again:

​
Troubleshooting

​
”Invalid or expired token”

The token was revoked — user-scoped tokens do not expire on their own. Disconnect and reconnect to authorize a new one.

​
”Insufficient scope”

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

​
”No eligible team”

Your account isn’t a member of any team on an MCP-eligible plan (Starter and above), or the subscription has lapsed. Authorization is denied until at least one workspace is eligible.