Qvasa MCP Server — Security and Integration Reference
This article describes the Qvasa Model Context Protocol (MCP) server: how AI agents connect to it, how access is authenticated and scoped, exactly which tools are exposed, and how every tool call reaches your Qvasa data. It is written for security reviewers evaluating the integration before connecting it.
At a glance. Connector: qvasa-mcp on PyPI · Transport: Streamable HTTP / JSON-RPC 2.0 · Auth: OAuth 2.1 + PKCE · Rate limits: 120 calls a minute per session, 20 a minute for expensive calls.
Contents
Overview
Architecture
Authentication
Token storage & validation
Authorization & scoping
Scope reference
Multi-tenancy & isolation
The MCP tools
How tools reach your data
The client connector
Token lifecycle
Auditing & observability
Data handling & limits
Independent review & download
1. Overview
The Qvasa MCP server lets an AI agent (e.g. Claude) work with your Qvasa customer-support analytics on a user's behalf — running metrics, inspecting tickets, and managing dashboards and AI classifiers — strictly within the permissions that user already holds in Qvasa. Claude users connect it from Qvasa's listing in Claude's connector directory; any other remote MCP client connects to the server URL, https://www.qvasa.com/mcp.
It is implemented natively inside the Qvasa Rails application using the official Model Context Protocol Ruby SDK. The agent talks to a single HTTPS endpoint; there is no separate hosted service, queue, or data store introduced by the MCP layer. It reuses the same application, authorization, and database paths as the rest of Qvasa.
Security posture in one line — every MCP request is authenticated, scoped to a single account, intersected against the calling user's live permissions, limited to the named endpoints of Qvasa's User Access API, and audited. There is no privileged bypass path introduced by the MCP.
2. Architecture
The integration has two halves:
Hosted MCP server: a single endpoint,
/mcp, served by the Qvasa application. It is stateless (each request is fully self-contained), speaks JSON-RPC 2.0 over the MCP Streamable HTTP transport, and is the sole authority for authentication, scope enforcement, validation, and tenant isolation.Client connector: a small, open, reviewable package that runs inside the user's AI client (Claude Desktop, Claude Code, Cursor). It is a thin proxy: it holds the user's credential locally and forwards calls to the hosted server. It enforces no business logic of its own (see section 10).
Discovery follows the standard OAuth protected-resource pattern. An unauthenticated call to /mcp returns 401 with a WWW-Authenticate header that points clients to the metadata endpoints:
/.well-known/oauth-protected-resource # RFC 9728: resource metadata + supported scopes /.well-known/oauth-authorization-server # RFC 8414: authorize / token / registration endpoints, PKCE
3. Authentication
The MCP accepts two credential forms, both of which resolve to the same backing token record:
OAuth 2.1 (hosted connector path). Authorization-code flow with PKCE required, implemented with Doorkeeper. The agent obtains a bearer access token and presents it as
Authorization: Bearer <token>on every/mcprequest. Refresh tokens are supported and rotated. This is the path the listing in Claude's connector directory uses. On Claude Team and Enterprise plans, an owner of the Claude organization adds the connector before members can connect; each member then signs in with their own Qvasa login.Personal access token (CLI path). A user-generated token (prefix
qva_uat_) for clients that pass a static credential. Same authorization and scoping rules apply.
Authentication and the foundational permission gate run as before_actions on the MCP controller, so no tool code executes until the caller is identified and authorized.
4. Token storage & validation
Raw tokens are never persisted. The plaintext token is shown to the user exactly once at creation.
What is stored is an HMAC-SHA256 digest of the token (keyed by a secret held only in the server environment), plus a short non-sensitive prefix for display (e.g.
qva_uat_1a2b…). The digest column is uniquely indexed.Validation hashes the presented token and looks it up by digest among active tokens (not revoked, not expired). A miss is an authentication failure.
OAuth access tokens are managed and validated by Doorkeeper independently of the digest path.
Implication — a database disclosure does not expose usable credentials: stored digests are not reversible to tokens, and the HMAC secret is not in the database.
5. Authorization & scoping
Access is least-privilege by construction. Every request is authorized through three independent layers, and is permitted only if all of them allow it:
Token scopes. Each token carries an explicit set of capability scopes (a bitfield). A token only ever has the scopes it was minted with.
The user's live permissions. At request time the token's scopes are intersected with the calling user's current account permissions. If a user's permission is later revoked in Qvasa, their tokens immediately lose that capability, even if the scope bit is still set on the token.
Account-level enablement (foundational gate). Before any scope is even consulted, three settings must hold: the feature is enabled for the account at the platform level (
can_enable_user_access_tokens), the account has opted in (scoped_user_access_tokens_enabled), and the user is permitted to use access tokens (can_manage_user_access_tokens). Any failure denies the request before it reaches a controller.
Baseline vs. above-baseline
Reading individual ticket detail (can_inspect_objects) and conversational content (can_access_conversational_data) are opt-in capabilities. The broad read umbrella (can_read_all_endpoints) deliberately does not auto-grant ticket-detail inspection, which is a separate, explicit scope. Writes always require an explicit write scope; nothing is writable by default.
6. Scope reference
The tables below reflect the scopes that can be granted to a token today. Two umbrella scopes (can_read_all_endpoints, can_write_all_endpoints) act as convenience grants over the granular read/write scopes; the remaining scopes can be granted individually for finer-grained tokens.
Umbrella scopes
Scope | Grants |
| Grants every Read scope listed below |
| Grants every Write scope listed below |
Additional Read Access (Above Baseline)
Scope | Capability | What it grants |
| Inspect ticket details | Drill into individual ticket details (metadata, tags, assignments, history) |
| Access conversations | Read message bodies and transcript content |
Ability to Manage Qualitative Questions (AI Classifiers)
Scope | Capability | What it grants |
| Create AI classifiers | Create new custom basic_score or two_choice questions |
| Edit inactive AI classifiers | Edit response options while the classifier is inactive |
| Activate & backfill AI classifiers | Submit for AI review, activate, run backfill |
| Cancel AI classifier backfills | Cancel an in-progress backfill job |
| Edit active AI classifiers | Edit response options on an active classifier |
Ability to Leverage On-Demand AI Insights
Scope | Capability | What it grants |
| Run AI insights jobs | Run extract_themes or knowledge_base_article on a ticket set |
Ability to Manage Generative Definitions (Generative AI Workflows)
Scope | Capability | What it grants |
| Create generative AI workflows | Create new drafts and clone existing definitions |
| Publish generative AI workflows | Publish a draft (one-way; locks core fields) |
| Edit published generative AI | Edit mutable fields of a published definition |
| Wire generative AI to classifiers | Wire a published definition to a classifier response option |
| Wire nested AI classifiers | Wire a nested classifier to a parent response option |
Ability to Manage Scheduled Report Exports
Scope | Capability | What it grants |
| Scheduled report exports | Create and schedule recurring dashboard exports |
Ability to Manage Workflow Condition Alerts
Scope | Capability | What it grants |
| Workflow condition alerts | Build threshold conditions on widgets and fire alerts |
Ability to Manage Standard Threshold Alerts
Scope | Capability | What it grants |
| Standard threshold alerts | Manage the legacy AlertCondition queue-based alerts |
Ability to Acknowledge Alerting Incidents
Scope | Capability | What it grants |
| Acknowledge alert incidents | Mark threshold-alert incidents as recognized |
Ability to Access Open Dashboards
Scope | Capability | What it grants |
| Read open dashboards | List and fetch open (team-shared) dashboards |
| Build & edit open dashboards | Create and edit widget/row layout on open dashboards |
Ability to Access Private Dashboards
Scope | Capability | What it grants |
| Read private dashboards | List and fetch private dashboards |
| Build & edit private dashboards | Create and edit widget/row layout on private dashboards |
Ability to Access Agent Dashboards
Scope | Capability | What it grants |
| Read agent dashboards | List and fetch agent dashboards |
| Build & edit agent dashboards | Create and edit widget/row layout on agent dashboards |
Note — running metric queries (single-number stats, charts, donuts, heat-maps) and maintaining a personal-dashboard "memory" are baseline capabilities of any token and do not require an additional scope. Everything above the baseline is opt-in per the scopes listed here.
Ability to Manage Dashboard Styling
Scope | Capability | What it grants |
| Manage color templates and themes | Create templates outside a dashboard, rename, restyle and delete any template, and create, rename and delete color themes. Reading templates and themes, formatting widgets, applying a theme or template to a dashboard the user can edit, and restyling the user's own templates ride on the read and write umbrellas and the dashboard scopes; every request on this scope also requires the user to be a template manager, checked live. |
| Manage saved format rules | Save, rename, re-scope, change and delete the named format rules (hide rows, color cells) that configurable table columns re-use. Reads ride on the read umbrella; setting a column's own rules is a dashboard edit under the dashboard write scopes. Filtered out at request time unless the user holds the manage-saved-format-rules permission. |
Both are covered by can_write_all_endpoints, and both are intersected with the user's live permission like every other scope.
7. Multi-tenancy & isolation
Qvasa is multi-tenant; account isolation is enforced at every layer the MCP touches:
Every token and every session record
belongs_toexactly one account.A token's user is validated to belong to the token's account; a mismatch is rejected.
Sessions are validated to share the user and account of their token.
All data access flows through the standard Qvasa application queries, which are scoped by
account_id. There is no MCP code path that reads across accounts.
8. The MCP tools
The server exposes a deliberately small "portal" of nine tools. Most Qvasa capabilities are reached not by a dedicated tool but through a search → guide → call pattern over the catalog, which keeps the tool surface minimal and auditable.
Tool | What it does | Reaches |
| Returns a small orientation packet describing how to use the API. | Read-only guidance content. |
| Searches the tool / metric / filter catalog by phrase (primary discovery verb). | Read-only catalog. |
| Fetches the full guide for one named tool: what it does, the endpoints it uses by name, the params they take, and the scopes they need. Useful once a search has found the capability. | Read-only guidance content. |
| Fetches one workflow recipe (an ordered tool sequence) by intent id. | Read-only guidance content. |
| Runs a metric (a quick stat, a chart, a donut, a heat map, a timeline or an agent scorecard view) and returns the result, or with | Analytics over your ticket data, scoped to the account. |
| Runs one read endpoint of the Qvasa User Access API, given its name (such as | Read-only. Only names of read endpoints; the name of an endpoint that changes data is refused, with the tool that runs it. Each call is independently scope-gated. |
| Runs one write endpoint of the Qvasa User Access API, given its name and its params: an endpoint that creates, updates or deletes, for example creating a dashboard or an alert. | Marked destructive, so MCP clients such as Claude ask the user before each call. Only names of write endpoints. Each call is independently scope-gated, and needs the token's write scopes. |
| Files a support ticket with the Qvasa team on the user's behalf (bug report, unexpected behavior, friction, feature request, question). Replaces the earlier | Writes a support ticket record only; needs no domain write scope. |
| Lists the support tickets the user can see, with filters for status, type, unread replies and search, so the agent can check whether Qvasa has replied. | Read-only: the user's own tickets, or every ticket on the account when the user holds the account-wide support permission. |
On qvasa_read_api and qvasa_write_api: neither can reach arbitrary parts of the application. Each takes an endpoint's name from one fixed table of the User Access API's endpoints, each marked as a read, a write or a metric; a name that is not in the table, or that belongs to the other tool, is refused before anything runs, and a metric is run by qvasa_query_metric. Reads and writes are separate tools so an MCP client can treat them differently: every tool carries a title and a read-only or destructive annotation, the read tool never changes data, and the write tool is flagged so the user approves each call. Every endpoint either tool reaches enforces its own scope and validation, and the tools grant no additional authority.
Earlier versions. Before 2026-10-21 the two were one tool, qvasa_call_api, and the hosted server also listed qvasa_create_session, which did nothing there. Since connector 0.13.0 both tools take an endpoint's name; a copy that is out of date is told so when it opens a session, and one too old to work with the server cannot open a session and is told how to update. The local package (qvasa-mcp) still has qvasa_create_session, because it opens its own session from your User Access Token.
9. How tools reach your data
A tool call does not open a new network connection or use a privileged internal channel. The server translates the tool call into an in-process request that re-enters the same Qvasa controller stack used by the rest of the application, carrying the caller's credentials. This means:
The identical authentication, scope checks, validation, and account scoping apply, so there is no parallel, less-guarded code path.
The endpoint's name is looked up in the table of the User Access API's endpoints before any controller runs; nothing outside that API is reachable.
Reads are the default; any write requires an explicit write scope (see section 6).
Errors from the underlying endpoint (a scope denial, for example) reach the agent unchanged, each with its error code.
10. The client connector
The downloadable connector (the package distributed in the .mcpb bundle, see section 14) is a thin Python proxy (Python 3.11+, run via uv). Its security-relevant properties:
Single destination. It makes outbound HTTPS calls only to the configured Qvasa host (default
https://www.qvasa.com, overridable for staging or self-hosted). There is no telemetry, analytics, or third-party / model-provider call of any kind.The same endpoint table. It carries the server's table of named endpoints and refuses a name outside it, or of the other tool's kind, before sending anything, for defense in depth on both ends.
Credential handling. The user's access token is supplied via an environment variable. In Claude Desktop it is declared as a sensitive config field and stored in the OS keychain. The short-lived session is held in process memory only and is never written to disk.
No logs of its own. The local package writes no log of credentials or of requests and their results; errors are returned as structured objects with recovery hints. The requests it sends reach Qvasa, which records them as the privacy policy describes.
No independent authority. The connector interprets no scopes and makes no authorization decisions; Qvasa is the sole authority.
11. Token lifecycle
Credential | Lifetime | Notes |
OAuth access token | 8 hours | Short-lived bearer; refreshed via rotating refresh token. |
OAuth refresh token | Rotated on use | Prior refresh token is revoked when a new one is issued. |
Personal access token (UAT) | 90 days default, 365 max | User-chosen expiry within bounds; revocable at any time. |
Session token | 24 hours | One active session per token; pins the toolkit version for the session. |
Revocation is comprehensive. Disconnecting an OAuth connection (or revoking a token) runs in a single transaction that revokes the OAuth access and refresh tokens and their grants, revokes the backing token record, and invalidates all active sessions, so in-flight agent sessions stop working immediately.
12. Auditing & observability
Token lifecycle audit trail. Creation, permission changes, revocation, expiry, and deletion are recorded as events (with the acting user and token metadata). The audit write is fail-loud: if it cannot be recorded, the surrounding operation is rolled back.
Per-request records. Metric and export requests are persisted with the account, user, token, session, status, and timestamps, providing an attributable record of what was run.
Last-used tracking. Tokens and sessions track last-used time (throttled to limit write churn).
Error reporting. Unexpected tool errors raise an internal alert with a support code that is also surfaced to the agent, so issues are traceable end-to-end.
13. Data handling & limits
Through the MCP a sufficiently-scoped token can reach the same data the user can already see in Qvasa: ticket metadata and analytics, and, only with the explicit conversational scope, message and transcript content. Nothing beyond the user's own visibility is exposed.
Rate limits. Every authenticated call counts against a standard budget of 120 calls a minute per session; calls that start server-side work (metric kickoffs, AI insight jobs, dashboard widget queries) also count against an expensive budget of 20 a minute. A call over either budget is refused with HTTP 429, error code rate_limit_exceeded, and a Retry-After header. The budgets are sized so that normal agent use never trips them (one human question is typically 10 to 30 calls with 1 to 3 kickoffs); they exist to stop runaway loops and abuse. Concurrency caps apply on top (for example one active session per token and one active bulk export per token). The MCP endpoint does not currently enforce IP allowlisting; access is bounded by the per-request scope checks, the live-permission intersection, account isolation and short credential lifetimes described above. We are happy to discuss additional network controls for your deployment.
14. Independent review & download
The client connector is provided for your team to review directly. The download is an MCP bundle (.mcpb), a standard ZIP archive, containing the connector's full source:
Qvasa MCP connector bundle — qvasa-mcp.mcpb · always the latest release · Python 3.11+ (run via uv).
To inspect it:
unzip qvasa-mcp.mcpb -d qvasa-mcp # Contents: # manifest.json : MCP/DXT manifest (declares the sensitive token field, default host) # pyproject.toml : package metadata and dependencies # uv.lock : fully pinned dependency lockfile # src/qvasa_mcp/** : connector source (tools, client, endpoint table) # README.md : usage and configuration
Reviewing the source confirms the properties in section 10: a single outbound destination, the endpoint table, in-memory-only session handling, and no telemetry. Dependencies are pinned in uv.lock for reproducible installs.
