{
  "markdown": "# @quelvio/mcp-server\n\nQuelvio MCP server — search your company's connected knowledge from any AI tool that speaks the Model Context Protocol.\n\nEndpoint: `https://mcp.quelvio.com/http` (Streamable HTTP, MCP spec 2025-03-26)\nSource: [Quelvio/quelvio-mcp-server](https://github.com/Quelvio/quelvio-mcp-server)\nLicense: MIT\n\n## Tools\n\n| Tool | Purpose | Knowledge Tokens |\n|---|---|---|\n| `query_knowledge` | Primary search across the tenant's connected sources (Drive, SharePoint, Confluence, Slack, Notion). Modes: `fast`, `standard` (default), `deep`. | 1,500 kT (`fast`) / 12,500 kT (`standard`) / 25,000 kT (`deep`) |\n| `list_domains` | Discovery — list taxonomy domains with coverage levels. Use to decide whether the brain has relevant knowledge before issuing a billable query. | 0 kT |\n| `get_source_detail` | Per-chunk provenance for a previous query: document path, lifecycle state, embedding timestamp, contributor, last-updated. Pass a `query_id` from an earlier `query_knowledge` response. | 0 kT |\n\n## Permission model\n\nEvery MCP query is scoped to your **individual employee identity**, not just your tenant. The server applies the same three-layer access model the dashboard uses:\n\n1. **Tenant isolation** — Qdrant collections are per-tenant; cross-tenant content is structurally unreachable.\n2. **Role-based feature access** — Owner / Admin / Member determines which tools are callable.\n3. **Source permission filtering** — `permission_emails` on every chunk, resolved at ingest time from the source system's ACLs (Google Drive shares, SharePoint groups, Confluence space restrictions). MCP queries see only what your individual account would see in those source systems.\n\nThe source-permission filter is unconditional — there is no flag, env var, or dashboard toggle that disables it. The MCP server records the per-employee identity on every query so cross-employee provenance inspection via `get_source_detail` is rejected with 404 (only Owner/Admin can view another member's queries).\n\n## Sign in\n\nThere is no API key to provision. The first time you use Quelvio MCP from any client, you'll be redirected to your organization's sign-in page (Clerk-hosted, the same one the dashboard uses). After signing in, your client resumes automatically. Subsequent queries reuse the OAuth token until it expires (~30 days) or you revoke it from `enterprise.quelvio.com`.\n\nIf your AI assistant prompts you for a \"Bearer token\" or \"API key\" header in the JSON config, you have an outdated configuration — delete the `headers` block and let your client manage OAuth. The migration is automatic: the next time you invoke a tool, the client opens a browser tab for sign-in.\n\n## Install\n\n### Claude Desktop (and Claude Web)\n\nAdd to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\\Claude\\claude_desktop_config.json` (Windows):\n\n```json\n{\n  \"mcpServers\": {\n    \"quelvio\": {\n      \"url\": \"https://mcp.quelvio.com/http\"\n    }\n  }\n}\n```\n\nRestart Claude Desktop. On first use Claude opens a browser tab pointing at Clerk's hosted sign-in page; complete sign-in and Claude resumes automatically.\n\n### Cursor\n\nAdd to `.cursor/mcp.json` in your project root (or globally at `~/.cursor/mcp.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"quelvio\": {\n      \"url\": \"https://mcp.quelvio.com/http\"\n    }\n  }\n}\n```\n\nCursor handles the OAuth round-trip the same way Claude does.\n\n### Claude Code\n\n```bash\nclaude mcp add quelvio --transport http https://mcp.quelvio.com/http\n```\n\n### VS Code (Copilot)\n\nAdd to `.vscode/mcp.json`:\n\n```json\n{\n  \"servers\": {\n    \"quelvio\": {\n      \"type\": \"http\",\n      \"url\": \"https://mcp.quelvio.com/http\"\n    }\n  }\n}\n```\n\n### stdio bridge (older clients)\n\nFor MCP clients that don't speak Streamable HTTP yet, install the npm package:\n\n```bash\nnpm install -g @quelvio/mcp-server\n```\n\nThen point your client at the binary:\n\n```json\n{\n  \"mcpServers\": {\n    \"quelvio\": {\n      \"command\": \"quelvio-mcp\"\n    }\n  }\n}\n```\n\nThe binary opens a local OAuth listener on a random `127.0.0.1` port and proxies all subsequent JSON-RPC to `https://mcp.quelvio.com/http`.\n\n## OAuth flow\n\nThe MCP server is an OAuth 2.1 + PKCE (S256) protected resource. Bearer tokens are opaque, KV-backed, and AES-GCM encrypted at rest. RFC 9728 + RFC 8414 discovery is wired:\n\n- `GET /.well-known/oauth-protected-resource` — resource metadata\n- `GET /.well-known/oauth-authorization-server` — authorization server metadata\n- `GET /oauth/authorize` — 302 to Clerk hosted sign-in (with PKCE state stashed in KV)\n- `GET /oauth/callback` — Clerk session JWT → `POST /v1/auth/sso-bridge` mints a per-employee ephemeral key → 302 back to client `redirect_uri`\n- `POST /oauth/token` — auth_code or refresh_token grant\n- `POST /oauth/revoke` — invalidate a token\n\nModern MCP clients auto-bootstrap the flow when they hit a 401 with the `WWW-Authenticate: Bearer ... resource_metadata=...` challenge. Cursor and Claude Desktop do this transparently.\n\n**v0.8.8 foundation deletion:** the legacy paste-an-API-key form path (`POST /oauth/authorize` with a `qlv_ent_*` key in the form body) is gone. Customers using paste-key MCP must complete the OAuth/Clerk round-trip on first use; the migration is automatic — the client just opens a browser tab the next time you invoke a tool.\n\n## Examples\n\n### 1. `query_knowledge` — find an answer with citations\n\n```\nask Claude: \"What's our deployment process for the payments service?\"\n\nClaude calls: query_knowledge(query=\"deployment process payments service\")\n\nResponse: synthesized answer with [n] citations + structured metadata block including\nquery_id, coverage level, retrieval execution state, latency, and tokens consumed.\n(Default mode is `standard` — synthesis is built in. Use `mode=\"deep\"` for complex\nanalytical questions, `mode=\"fast\"` for keyword-style retrieval with no synthesis.)\n```\n\n### 2. `list_domains` — discover what's indexed before querying\n\n```\nask Claude: \"What taxonomy domains does our company have indexed?\"\n\nClaude calls: list_domains()\n\nResponse: list of every domain with document count, expert count, coverage level\n(expert | partial | none), top contributor by authority, and the single_expert risk\nflag where applicable.\n```\n\n### 3. `get_source_detail` — verify a citation\n\n```\nAfter a query_knowledge call returned [3] citations, ask Claude:\n\"Show me the actual source for citation [3].\"\n\nClaude calls: get_source_detail(query_id=\"<uuid from prior query>\")\n\nResponse: per-chunk provenance — document path, lifecycle state (live | stale |\nsuperseded | user_deleted), embedding timestamp + model, contributor name + department,\nauthority score, taxonomy domain.\n```\n\n## Pricing\n\nKnowledge Token consumption per tool call (v0.9 frozen constants):\n\n- `query_knowledge` with `mode=fast`     : **1,500 kT**  (retrieval-only, no synthesis)\n- `query_knowledge` with `mode=standard` : **12,500 kT** (default; synthesis bundled)\n- `query_knowledge` with `mode=deep`     : **25,000 kT** (wider retrieval + premium synthesis)\n- `list_domains`                          : 0 kT\n- `get_source_detail`                     : 0 kT\n\nThese costs are frozen at the v0.9 Contract Lock. The dashboard's billing page (`/billing`) shows the live per-tenant daily Knowledge Token pool and the projected next invoice.\n\n## Self-hosting / development\n\n```bash\ncd mcp-server\npnpm install\n\n# Local dev\npnpm dev\n\n# Deploy to Cloudflare Workers\nwrangler secret put TOKEN_ENCRYPTION_KEY    # 32 bytes hex (openssl rand -hex 32)\nwrangler secret put CLERK_SIGN_IN_URL       # Clerk hosted sign-in URL\npnpm deploy\n```\n\nThe Worker is stateless — every OAuth artifact (auth codes, access tokens, refresh tokens) lives in the bound KV namespace. No Durable Objects.\n\n## Protocol\n\n- **Transport:** Streamable HTTP (MCP spec 2025-03-26)\n- **Endpoint:** `POST /http` with `Content-Type: application/json`\n- **Health check:** `GET /` or `GET /http` returns server info\n- **Methods:** `initialize`, `tools/list`, `tools/call`, `ping`\n- **Streaming:** when `tools/call query_knowledge` carries `Accept: text/event-stream` AND `mode` is `standard|deep` (the two v0.9 tiers that synthesize), the server proxies the backend's SSE pipeline. `fast` never streams (no synthesis body to incrementally produce). The MCP response is still a single JSON body — token-by-token streaming to the MCP client lands when the spec adds native output deltas.\n- **Response cap:** Claude Connectors' 25,000-token-per-tool-result limit is enforced server-side. Truncation order: drop excerpts past 200 chars first, then drop lowest-rank sources (preserving ≥3), then truncate the synthesis body. Truncation is signalled via `truncated: true` in the structured metadata block so agents can re-issue with a smaller `max_sources`.\n\n## Release process\n\nPublishes go through `.github/workflows/publish.yml` via **npm Trusted Publishing** (OIDC). No long-lived `NPM_TOKEN` lives in this repo or in GitHub Actions secrets.\n\nTo ship a new version:\n\n```bash\n# 1. Bump version + commit\nnpm version patch   # or minor / major\ngit push origin main\n\n# 2. Push the matching tag — this triggers the publish workflow\ngit push origin v$(node -p \"require('./package.json').version\")\n```\n\nThe workflow verifies the tag matches `package.json`, type-checks, builds, and runs `npm publish --provenance --access public`. SLSA provenance is attached to every release.\n\nOne-time bootstrap on npmjs.com (operator step):\n\n- Package: `@quelvio/mcp-server` → Settings → Trusted Publishers → Add\n- Repository owner: `Quelvio`\n- Repository name: `quelvio-mcp-server`\n- Workflow filename: `publish.yml`\n\n## Changelog\n\nSee [CHANGELOG.md](./CHANGELOG.md).\n",
  "bytes": 9645,
  "sha": "d065e48b24ac8181f799d4495e4abfcdce713f6c8c8a17341086c7203b1bff5b",
  "repo_slug": "quelvio/quelvio-mcp-server",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_com_quelvio_mcp_server_bd90cef2/readme"
}