Quelvio

@quelvio/mcp-server

Quelvio MCP サーバー — Model Context Protocol に対応したあらゆる AI ツールから、会社の接続済みナレッジを検索できます。

エンドポイント：https://mcp.quelvio.com/http（Streamable HTTP、MCP spec 2025-03-26） ソース：Quelvio/quelvio-mcp-server ライセンス：MIT

ツール

ツール	用途	ナレッジトークン
query_knowledge	テナントの接続済みソース（Drive、SharePoint、Confluence、Slack、Notion）を横断する主要な検索です。モード：fast、standard（デフォルト）、deep。	1,500 kT（fast）／12,500 kT（standard）／25,000 kT（deep）
list_domains	検出 — カバレッジレベルとともに分類ドメインを一覧表示します。課金対象のクエリを実行する前に、関連するナレッジがあるかどうかを判断するために使用します。	0 kT
get_source_detail	前回のクエリに対するチャンク単位の出所情報：ドキュメントパス、ライフサイクル状態、埋め込みのタイムスタンプ、寄稿者、最終更新日時。以前の query_knowledge の応答に含まれる query_id を渡します。	0 kT

権限モデル

すべての MCP クエリは、テナントだけでなく、個々の従業員 ID に紐づけられます。サーバーは、ダッシュボードと同じ3層のアクセスモデルを適用します。

1. テナント分離 — Qdrant コレクションはテナントごとに分かれており、テナントをまたぐコンテンツには構造上アクセスできません。
2. ロールベースの機能アクセス — Owner／Admin／Member によって、呼び出し可能なツールが決まります。
3. ソース権限フィルタリング — 各チャンクの permission_emails は、取り込み時にソースシステムの ACL（Google Drive の共有設定、SharePoint グループ、Confluence スペースの制限）から解決されます。MCP クエリで参照できるのは、個人アカウントが各ソースシステムで参照できる情報のみです。

ソース権限フィルターは常に適用され、無効にするフラグ、環境変数、ダッシュボードの切り替え設定はありません。MCP サーバーは各クエリに従業員ごとの ID を記録するため、従業員をまたぐ get_source_detail による出所情報の確認は 404 で拒否されます（別のメンバーのクエリを閲覧できるのは Owner／Admin のみです）。

サインイン

API キーを発行する必要はありません。クライアントから Quelvio MCP を初めて使用すると、組織のサインインページ（ダッシュボードと同じ Clerk ホストのページ）にリダイレクトされます。サインイン後、クライアントは自動的に処理を再開します。その後のクエリでは、OAuth トークンの有効期限が切れる（約30日）か、enterprise.quelvio.com で取り消すまで、同じトークンが再利用されます。

AI アシスタントが JSON 設定の「Bearer token」または「API key」ヘッダーを求める場合、設定が古くなっています。headers ブロックを削除し、OAuth の管理はクライアントに任せてください。移行は自動で行われます。次にツールを呼び出すと、クライアントがサインイン用のブラウザータブを開きます。

インストール

Claude Desktop（および Claude Web）

~/Library/Application Support/Claude/claude_desktop_config.json（macOS）または %APPDATA%\Claude\claude_desktop_config.json（Windows）に追加します。

{
  "mcpServers": {
    "quelvio": {
      "url": "https://mcp.quelvio.com/http"
    }
  }
}

Claude Desktop を再起動します。初回使用時に Claude が Clerk のホストするサインインページをブラウザータブで開きます。サインインを完了すると、Claude が自動的に処理を再開します。

Cursor

プロジェクトのルートにある .cursor/mcp.json（またはグローバル設定の ~/.cursor/mcp.json）に追加します。

{
  "mcpServers": {
    "quelvio": {
      "url": "https://mcp.quelvio.com/http"
    }
  }
}

Cursor も Claude と同じ方法で OAuth のやり取りを処理します。

Claude Code

claude mcp add quelvio --transport http https://mcp.quelvio.com/http

VS Code（Copilot）

.vscode/mcp.json に追加します。

{
  "servers": {
    "quelvio": {
      "type": "http",
      "url": "https://mcp.quelvio.com/http"
    }
  }
}

stdio ブリッジ（旧バージョンのクライアント）

Streamable HTTP にまだ対応していない MCP クライアントの場合は、npm パッケージをインストールします。

npm install -g @quelvio/mcp-server

次に、クライアントの接続先としてバイナリを指定します。

{
  "mcpServers": {
    "quelvio": {
      "command": "quelvio-mcp"
    }
  }
}

バイナリはランダムな 127.0.0.1 ポートでローカル OAuth リスナーを起動し、それ以降のすべての JSON-RPC を https://mcp.quelvio.com/http にプロキシします。

OAuth フロー

MCP サーバーは、OAuth 2.1 + PKCE（S256）で保護されたリソースです。ベアラートークンは不透明で、KV に保存され、保存時には AES-GCM で暗号化されます。RFC 9728 + RFC 8414 のディスカバリーに対応しています。

• GET /.well-known/oauth-protected-resource — リソースメタデータ
• GET /.well-known/oauth-authorization-server — 認可サーバーのメタデータ
• GET /oauth/authorize — Clerk のホスト型サインインに 302 リダイレクト（PKCE の state は KV に一時保存）
• GET /oauth/callback — Clerk のセッション JWT → POST /v1/auth/sso-bridge で従業員ごとの一時キーを発行 → クライアントの redirect_uri に 302 リダイレクト
• POST /oauth/token — auth_code または refresh_token グラント
• POST /oauth/revoke — トークンを無効化

最新の MCP クライアントは、WWW-Authenticate: Bearer ... resource_metadata=... チャレンジを伴う 401 を受け取ると、フローを自動的に開始します。Cursor と Claude Desktop では、この処理が透過的に行われます。

v0.8.8 の基盤削除： 従来の API キー貼り付けフォームの経路（フォーム本文に qlv_ent_* キーを含めた POST /oauth/authorize）は廃止されました。API キー貼り付け方式の MCP を使用しているお客様は、初回利用時に OAuth/Clerk の往復認証を完了する必要があります。移行は自動で行われます。次回ツールを呼び出すと、クライアントがブラウザーのタブを開きます。

使用例

1. query_knowledge — 引用付きで回答を見つける

ask Claude: "What's our deployment process for the payments service?"

Claude calls: query_knowledge(query="deployment process payments service")

Response: synthesized answer with [n] citations + structured metadata block including
query_id, coverage level, retrieval execution state, latency, and tokens consumed.
(Default mode is `standard` — synthesis is built in. Use `mode="deep"` for complex
analytical questions, `mode="fast"` for keyword-style retrieval with no synthesis.)

2. list_domains — クエリを実行する前にインデックス済みの内容を確認する

ask Claude: "What taxonomy domains does our company have indexed?"

Claude calls: list_domains()

Response: list of every domain with document count, expert count, coverage level
(expert | partial | none), top contributor by authority, and the single_expert risk
flag where applicable.

3. get_source_detail — 引用を検証する

After a query_knowledge call returned [3] citations, ask Claude:
"Show me the actual source for citation [3]."

Claude calls: get_source_detail(query_id="<uuid from prior query>")

Response: per-chunk provenance — document path, lifecycle state (live | stale |
superseded | user_deleted), embedding timestamp + model, contributor name + department,
authority score, taxonomy domain.

料金

ツール呼び出しごとの Knowledge Token 消費量（v0.9 の固定定数）：

• query_knowledge の mode=fast ：1,500 kT （検索のみ。合成なし）
• query_knowledge の mode=standard ：12,500 kT（デフォルト。合成を含む）
• query_knowledge の mode=deep ：25,000 kT（より広範な検索 + プレミアム合成）
• list_domains ：0 kT
• get_source_detail ：0 kT

これらのコストは v0.9 の Contract Lock 時点で固定されています。ダッシュボードの請求ページ（/billing）では、テナントごとの当日分の Knowledge Token プールと、次回請求額の見込みを確認できます。

セルフホスティング／開発

cd mcp-server
pnpm install

# Local dev
pnpm dev

# Deploy to Cloudflare Workers
wrangler secret put TOKEN_ENCRYPTION_KEY    # 32 bytes hex (openssl rand -hex 32)
wrangler secret put CLERK_SIGN_IN_URL       # Clerk hosted sign-in URL
pnpm deploy

Worker はステートレスです。すべての OAuth アーティファクト（認可コード、アクセストークン、リフレッシュトークン）は、バインドされた KV 名前空間に保存されます。Durable Objects は使用しません。

プロトコル

• トランスポート： Streamable HTTP（MCP spec 2025-03-26）
• エンドポイント： Content-Type: application/json を指定して POST /http
• ヘルスチェック： GET / または GET /http でサーバー情報を返します
• メソッド： initialize、tools/list、tools/call、ping
• ストリーミング： tools/call query_knowledge に Accept: text/event-stream が指定され、かつ mode が standard|deep（合成を行う v0.9 の 2 つのティア）の場合、サーバーはバックエンドの SSE パイプラインをプロキシします。fast ではストリーミングは行われません（逐次生成する合成本文がないため）。MCP のレスポンスは引き続き単一の JSON 本文です。MCP クライアントへのトークン単位のストリーミングは、仕様にネイティブの出力差分が追加された時点で利用可能になります。
• レスポンス上限： Claude Connectors のツール結果あたり 25,000 トークンの上限は、サーバー側で適用されます。切り詰める順序は、まず 200 文字を超える抜粋を削除し、次に最低 3 件を維持しながらランクの低いソースを削除し、最後に合成本文を切り詰めます。エージェントがより小さな max_sources を指定して再実行できるよう、構造化メタデータブロックの truncated: true で切り詰めを通知します。

リリースプロセス

公開は .github/workflows/publish.yml を通じて npm Trusted Publishing（OIDC）で行います。このリポジトリにも GitHub Actions のシークレットにも、長期間有効な NPM_TOKEN は保存されません。

新しいバージョンをリリースするには：

# 1. Bump version + commit
npm version patch   # or minor / major
git push origin main

# 2. Push the matching tag — this triggers the publish workflow
git push origin v$(node -p "require('./package.json').version")

ワークフローでは、タグが package.json と一致することを検証し、型チェックとビルドを実行したうえで、npm publish --provenance --access public を実行します。すべてのリリースに SLSA provenance が添付されます。

npmjs.com での初回セットアップ（運用担当者の作業）：

• パッケージ：@quelvio/mcp-server → Settings → Trusted Publishers → Add
• リポジトリ所有者：Quelvio
• リポジトリ名：quelvio-mcp-server
• ワークフローファイル名：publish.yml

変更履歴

CHANGELOG.md を参照してください。