Authentication

Varolio MCP uses OAuth 2.1 with PKCE for authentication, following the MCP specification.

How it works

MCP clients handle the OAuth flow automatically. Here's what happens under the hood:

1. Discovery

When your client connects to mcp.varolio.io/mcp, it receives a 401 Unauthorized response with a WWW-Authenticate header pointing to the Protected Resource Metadata endpoint (RFC 9728).

GET /.well-known/oauth-protected-resource

This returns the authorization server URL, which the client uses to discover OAuth endpoints.

2. Authorization

The client opens your browser to the authorization endpoint with a PKCE code challenge. You'll see the Varolio consent screen where you:

• Log in with your existing Varolio credentials
• Select a workspace (if you have access to multiple)
• Approve the requested permissions

3. Token exchange

After approval, the client exchanges the authorization code for an access token using the PKCE code verifier. The access token contains:

• Your email and user ID
• Your workspace ID and role
• The MCP client identifier

4. Authenticated requests

All subsequent MCP requests include the access token as a Bearer token. The server validates the token and scopes all data access to your workspace and permissions.

Token lifecycle

Permissions

MCP access is read-only. The granted permissions are:

• Read cases and case activity
• Read email threads and messages
• Read inbox configuration
• Read organizations and teams
• Search across workspace data

Write operations (drafting replies, creating cases, updating statuses) are not available via MCP.

Data scoping

Your data access through MCP matches your Varolio account permissions:

• Admin/Manager: Can see all workspace data
• Member: Can only see data for their team's inboxes

This is the same scoping applied in the Varolio Studio app.

Workspace selection

If you have access to multiple workspaces, you select one during the consent flow. To switch workspaces, remove the MCP server from your client and re-add it — you'll be prompted to select a workspace again.

Revoking access

To revoke MCP access, contact your workspace administrator. They can disable MCP tools for the workspace from the admin panel.