qvasa-mcp

# qvasa-mcp MCP server that exposes the Qvasa user-access agentic API to Claude. This is a thin proxy: Claude sends MCP tool calls over stdio, the server translates each call into one or more HTTP requests against the Qvasa Rails app, and returns the result. It owns session lifecycle (login, refresh on 401 SessionStale, two-token auth) so Claude doesn't have to. Rails counterpart: `one_qvasa_app` repo, namespace `/user_access/api/*`. The toolkit version constant lives at `app/services/user_access/api/toolkit_version.rb`. ## Configuration Set these env vars (Claude Desktop injects them from the `.mcpb` config block on install): | var | required | default | purpose | | --- | --- | --- | --- | | `QVASA_API_KEY` | yes | — | A user-access token (UAT). Generate at `/user_settings/user_access_tokens` in the Qvasa UI. Format `qva_uat_…`. | | `QVASA_API_BASE_URL` | no | `https://qvasa.com` | Override for staging or local dev (e.g. `http://localhost:3000`). | ## Local dev ```sh python3 -m venv .venv source .venv/bin/activate pip install -e '.[dev]' export QVASA_API_KEY=qva_uat_… export QVASA_API_BASE_URL=http://localhost:3000 # Run the server (it will read MCP requests on stdin, write responses on stdout). qvasa-mcp # Run the tests. pytest ``` ## Tool list (17 total) **Orientation** - `qvasa_overview` — call this FIRST. Returns positioning, intent triggers, intent-keyed workflows, a feedback guide, and the cached session manifest. One call per session; no HTTP round-trip after the first. - `qvasa_submit_feedback` — frictionless channel for filing bug reports, feature requests, friction points, unexpected_behavior notes, and impossibility reports back to Qvasa engineering. - `qvasa_search_saved_widgets` — search the user's personal-dashboard saved queries (the agent's memory layer). Call BEFORE rebuilding a metric from scratch. **Discovery — widgets** (unified: search by phrase, browse a group, or list all groups) - `qvasa_search_widgets` — pass `query` to searc…