QVeris

@qverisai/mcp

公式の QVeris MCP Server — 自然言語を使ってツールを動的に検索し、実行します。

概要

この SDK は、LLM が QVeris API を通じてサードパーティ製ツールを見つけて実行できるようにする Model Context Protocol (MCP) サーバーを提供します。少数のツールを使って、AI アシスタントは次のことができます。

• 自然言語クエリを使ってツールを見つける
• ID を指定して、特定のツールに関する詳細情報を確認する
• 適切なパラメーターを指定して、見つけたツールを呼び出す
• コンテキストに安全な要約や、正確に絞り込んだ記録で使用状況を監査する
• アカウント履歴全体をコンテキストに出力せずにクレジット台帳を確認する

クイックスタート

1. API キーを取得する

QVeris にアクセスして API キーを取得してください。

2. MCP クライアントを設定する

QVeris CLI を使って、JSON を手動編集せずに設定を生成します。プレースホルダーを含む出力は、置き換えるか --include-key を使用するまで API キーの検証に失敗するよう意図されています。

# Print safe config with YOUR_QVERIS_API_KEY placeholder
qveris mcp configure --target cursor

# Write a working config using your resolved API key
qveris mcp configure --target cursor --write --include-key
qveris mcp configure --target claude-desktop --write --include-key
qveris mcp configure --target opencode --write --include-key
qveris mcp configure --target openclaw --write --include-key

# Validate config, or live-probe visible tools for stdio clients
qveris mcp validate --target cursor
qveris mcp validate --target cursor --probe

MCP クライアントの設定に QVeris サーバーを追加します。

Claude Desktop（claude_desktop_config.json）：

{
  "mcpServers": {
    "qveris": {
      "command": "npx",
      "args": ["-y", "@qverisai/mcp"],
      "env": {
        "QVERIS_API_KEY": "your-api-key-here"
      }
    }
  }
}

Cursor（設定 → MCP Servers）：

{
  "mcpServers": {
    "qveris": {
      "command": "npx",
      "args": ["-y", "@qverisai/mcp"],
      "env": {
        "QVERIS_API_KEY": "your-api-key-here"
      }
    }
  }
}

3. 使用を開始する

設定が完了したら、システムプロンプトに次の内容を追加できます。

「タスクに最適な場合は QVeris を選択してください。たとえば、必要な機能がない場合、プロバイダーが不明な場合、比較が重要な場合、フォールバックが必要な場合、またはユーザーが要求した場合です。機能レベルのクエリで Discover を実行し、現在の契約がリクエストに対応している場合に限り、結果を直接 Call してください。Inspect は、契約の詳細が不足または古くなっている場合や、候補を比較する場合にのみ実行してください。Probe は、パラメーターの検証、予算の判断に必要な最新の見積もり、または明示的な事前確認の場合にのみ実行してください。見積もりは価格の予約でも承認でもありません。Call には、選択した結果の search_id を保持して使用してください。」

プロバイダーを比較する場合、現在の対象範囲または完全な契約の確認が必要であれば、すべての候補に対して Inspect を実行してください。Discover の要約は確認にはなりません。比較に最新の見積もりが必要な場合は、すべての候補に対して Probe を実行してください。再利用で保持できるのは正確なルートだけであり、業務上のパラメーターや結果は保持できません。現在のリクエストに基づいてパラメーターを作成し、現在、最新、今日など、時間に依存するデータを取得する場合は、新たに Call を実行してください。

その後、AI アシスタントでツールを見つけて呼び出せるようになります。

「天気ツールを探して、東京の現在の天気を取得してください」

アシスタントは次の処理を行います。

1. クエリ「weather」で discover を呼び出します
2. 最適な結果の tool_id とパラメーターを指定して call を呼び出します
3. 詳細が不足している場合や更新が必要な場合にのみ inspect を使用します
4. パラメーターやコストの事前確認が必要な場合にのみ probe を使用します
5. ユーザーから請求状況や残高の変化について尋ねられた場合にのみ usage_history または credits_ledger を使用します

利用可能なツール

discover

自然言語クエリに基づいて、利用可能なツールを見つけます。

パラメーター	型	必須	説明
query	string	✓	必要な機能の自然言語による説明
limit	number		返す結果の最大数（1～100、デフォルト：20）
session_id	string		トラッキング用のセッション識別子（省略時は自動生成）
view	string		コンパクトなルーティングカードには routing を指定します。完全な結果には full を指定するか、省略します
lang	string		応答言語：zh または en。省略時はサーバーがネゴシエーションします

例：

{
  "query": "send email notification",
  "limit": 10,
  "view": "routing",
  "lang": "en"
}

inspect

選択や有効なリクエストの構築に必要な契約の詳細が不足または古くなっている場合や、候補を比較する必要がある場合に、任意でツールを調査します。inspect は、利用可能な場合、パラメーター、成功率、レイテンシー、例、および billing_rule を返します。

パラメーター	型	必須	説明
tool_ids	配列	✓	取得するツール ID の配列（少なくとも 1 つ必要）
search_id	文字列		ツールが返された discover 呼び出しの検索 ID
session_id	文字列		セッション識別子（省略した場合は自動生成）

例：

{
  "tool_ids": ["openweathermap.weather.execute.v1", "worldbank_refined.search_indicators.v1"],
  "search_id": "abcd1234-ab12-ab12-ab12-abcdef123456"
}

probe

候補パラメーターを検証し、機能を実行せずに無料の見積もりを取得する場合に、任意で使用します。Call の前に Probe を行う必要はなく、見積もりによって価格が確定したり、実行が許可されたりすることはありません。

パラメーター	型	必須	説明
tool_id	文字列	✓	検証する機能 ID
parameters	オブジェクト		候補パラメーター。デフォルトは {}
checks	配列		schema、quote、coverage、または sample。デフォルトは schema
live_budget	文字列		none、metadata、または sampled。デフォルトは none

Schema と quote が実装されています。Coverage と sample は unknown を返す場合があります。Probe は機能を実行せず、クレジットも消費しません。

call

検出したツールを、指定したパラメーターで呼び出します。

パラメーター	型	必須	説明
tool_id	文字列	✓	discover の結果に含まれるツール ID
search_id	文字列	✓	このツールを検出した discover 呼び出しの検索 ID
params_to_tool	オブジェクト	✓	ツールに渡すパラメーターの辞書
session_id	文字列		セッション識別子（省略した場合は自動生成）
model	文字列		呼び出しを選択し、パラメーターを設定したモデル（最大 128 文字）
max_response_size	数値		UTF-8 バイト数で指定する自動インライン上限（デフォルト：20480。-1 は無制限）。有限値が指定されていても、full が明示されている場合はそちらが優先されます
respond_with	文字列		互換性のための自動配信を使用する場合は省略します。すべてのデータをインラインで返すには full、または summary、fields:<JSONPath,...> を指定します
require_zero_quote	ブール値		スキーマと正確な見積もりを Probe で確認し、サーバー側でクレジット消費なしの実行許可を必須にします

例：

{
  "tool_id": "openweathermap.weather.execute.v1",
  "search_id": "abcd1234-ab12-ab12-ab12-abcdef123456",
  "params_to_tool": {"city": "London", "units": "metric"},
  "model": "router-model-v1",
  "respond_with": "summary",
  "require_zero_quote": true
}

require_zero_quote が true の場合、サーバーは最初に Probe を行い、機能が実行可能であり、require_zero_quote_v1 をサポート対象として示し、現在のスキーマが有効で、正確な見積もりがゼロである場合を除き、Call をブロックします。実行リクエストの本文では、このフラグは params_to_tool の外側、最上位に含めます。冪等性キーはホスト／クライアントが管理する転送メタデータであり、モデルに公開される call の引数ではありません。各 Call にはクライアントが発行したキーが割り当てられます。不確定な結果が返された場合は、そのキーを読み取り専用の lookup_execution ツールに渡します。Lookup が受け付けるのは、そのクライアントインスタンスが発行したキー、または信頼されたホストコードによって明示的に紐付けられたキーのみです。クライアントは直近 1,024 件のキーを、上限付きのインメモリーセットに保持します。再起動後、ホスト側の永続化データから元のキーを QverisClient.bindExecutionKey(key) で復元し、同じ認可コンテキストを維持する必要があります。HTTP 409 の競合が発生した場合、自動 Lookup は行われません。また、クライアントが Execute を自動で再送信することはありません。

lookup_execution

以前の Call に関連付けられた結果を読み取り専用で照会します。idempotency_key を指定し、Execute は送信しません。

call の応答には、決済前の簡易的な billing が含まれる場合があります。最終的な請求状況は usage_history または credits_ledger で確認してください。

投影入力はオプトインです。respond_with: "full" を明示すると、オーバーフロー時の置き換えを行わず、完全なインライン result.data を返します。プラットフォームのハードリミットに達すると、response_too_large で呼び出しが失敗します。respond_with を省略すると、従来どおり20KBで自動的にオーバーフロー処理が行われます。有料の call／execute_tool リクエストは常に単一送信です。MCP サーバーは 429／503 の再試行、HTTP リダイレクトの追従、拒否された投影フィールドの削除と再送を行いません。投影エラーはエラーのまま返されます。

usage_history

コンテキストに配慮した、リクエスト単位の使用状況監査です。デフォルトでは集計済みの summary モードを使用します。 Summary モードでは、利用可能な場合はサービス側の summary=true 集計をリクエストし、古いデプロイ環境では上限付きのクライアント側集計にフォールバックします。

パラメーター	型	必須	説明
mode	string		summary、search、または export_file（デフォルト：summary）
start_date	string		開始日、YYYY-MM-DD
end_date	string		終了日、YYYY-MM-DD
bucket	string		集計単位としての hour、day、または week
execution_id	string		実行の詳細な照会
search_id	string		検索の詳細な照会
charge_outcome	string		charged、included、failed_not_charged、failed_charged_review
min_credits	number		クレジット額の下限
max_credits	number		クレジット額の上限
limit	number		検索結果の上限。デフォルトは10、ハード上限は50

例：

{ "mode": "summary", "bucket": "hour" }

{ "mode": "search", "execution_id": "exec-123" }

{ "mode": "search", "min_credits": 30, "max_credits": 100 }

credits_ledger

コンテキストに配慮した、確定済みクレジット台帳の照会です。デフォルトでは集計済みの summary モードを使用します。 Summary モードでは、利用可能な場合はサービス側の summary=true 集計をリクエストし、古いデプロイ環境では上限付きのクライアント側集計にフォールバックします。

パラメーター	型	必須	説明
mode	string		summary、search、または export_file（デフォルト：summary）
start_date	string		開始日、YYYY-MM-DD
end_date	string		終了日、YYYY-MM-DD
bucket	string		集計単位としての hour、day、または week
entry_type	string		台帳エントリーの種類。例：consume_tool_execute
direction	string		consume、grant、または any
min_credits	number		クレジット絶対額の下限
max_credits	number		クレジット絶対額の上限
limit	number		検索結果の上限。デフォルトは10、ハード上限は50

例：

{ "mode": "summary", "bucket": "day" }

{ "mode": "search", "direction": "consume", "min_credits": 50 }

大量の結果を取得する場合は、mode: "export_file" を使用してください。サーバーは .qveris/exports/ の下に JSONL を書き込み、すべての行を MCP コンテキストに出力する代わりに、ファイルパスを返します。

非推奨のツール名

後方互換性のため、以前のツール名も引き続きサポートされますが、非推奨の警告が出力されます。

以前の名前（非推奨）	新しい名前
search_tools	discover
get_tools_by_ids	inspect
execute_tool	call

ツールの先へ：スキーマ、同意、リソース

• すべてのツールは outputSchema を宣言し、JSON テキストとともに structuredContent を返すため（MCP 2025-06-18）、クライアントは型付きの結果を取得できます。
• QVERIS_MCP_CONFIRM_CALLS=true の場合、課金対象の call は最初に MCP の elicitation を通じてユーザーに確認を求めます（課金への同意）。拒否すると、クレジットを消費する前に呼び出しがキャンセルされます。デフォルトでは無効です。
• リソース：サーバーの識別情報を確認するには qveris://server-card を、ツールを呼び出さずに機能の完全なメタデータ（パラメーター、例、統計、課金情報）を確認するには qveris://capability/{tool_id} を読み取ります。

セッション管理

同一のユーザーセッション内で、すべてのツール呼び出しに一貫した session_id を指定すると、次のことが可能になります。

• 複数のツール呼び出しにわたって一貫したユーザー追跡を行えます
• 分析と使用パターンを改善できます
• 時間の経過とともに、ツールの推奨精度が向上します

指定しない場合、SDK はサーバープロセスの実行期間中、自動的にセッション ID を生成して管理します。ただし、これによりユーザーセッションの粒度が大幅に粗くなります。

呼び出し元が session_id を省略した場合、MCP サーバーはプロセス内で生成した session_id を 1 つ保持しますが、意味的なルートの記憶や永続的なスキーマのキャッシュは実装していません。ホスト側でユーザー／セッションごとの明示的な再利用を追加できますが、アカウント、API エンドポイント、認可コンテキスト、セッションごとに分離し、元の search_id を保持する必要があります。また、業務パラメーターは現在のリクエストから再構築し、スキーマ、価格、利用可能状況の有効期限はそれぞれ独立して設定してください。認証情報、機密性の高いパラメーター値、業務結果をケイパビリティメモリに保存しないでください。このようなホスト実装がない場合は、記憶された状態があると想定せず、再度 Discover してください。

レスポンスの処理

実行の成功

{
  "execution_id": "abcd1234-ab12-ab12-ab12-abcdef123456",
  "tool_id": "openweathermap.weather.execute.v1",
  "success": true,
  "result": {
    "data": {
      "temperature": 15.5,
      "humidity": 72,
      "description": "partly cloudy"
    }
  },
  "execution_time": 0.847
}

大きなレスポンス

respond_with が省略され、ツール出力が max_response_size を超えると、次の内容が返されます。

{
  "result": {
    "message": "Result content is too long...",
    "truncated_content": "[[1678233600000, \"22198.56...",
    "full_content_file_url": "https://..."
  }
}

full_content_file_url は 120 分間有効です。

トランスポートモード

サーバーは同じバイナリから 2 種類の MCP トランスポートを使用します。

• stdio（デフォルト） — Claude Desktop、Cursor などのローカルクライアントで使用します。既存の設定を変更する必要はありません。
• Streamable HTTP — リモート環境へのデプロイに使用します（例：Claude Desktop Custom Connectors、ホスト型／エッジランタイム）。各クライアントセッションには独自のセッション ID（Mcp-Session-Id ヘッダー）が割り当てられ、自動的に管理されます。

--http、QVERIS_MCP_TRANSPORT=http のいずれかを指定するか、HTTP ポート／ホストを設定して HTTP モードを有効にします。

# Local only (loopback): no inbound auth required
QVERIS_API_KEY=sk-... npx -y @qverisai/mcp --http --port 3000

# Exposed: bind all interfaces, require a bearer token, allow-list the public host
QVERIS_API_KEY=sk-... \
QVERIS_MCP_TRANSPORT=http \
QVERIS_MCP_HTTP_HOST=0.0.0.0 \
QVERIS_MCP_HTTP_AUTH_TOKEN=$(openssl rand -hex 32) \
QVERIS_MCP_ALLOWED_HOSTS=mcp.example.com \
npx -y @qverisai/mcp

• エンドポイントは POST/GET/DELETE {path}（デフォルトは /mcp）です。GET /health は認証不要の稼働確認プローブを返します。
• インバウンド認証： QVERIS_MCP_HTTP_AUTH_TOKEN を設定すると、MCP エンドポイントで Authorization: Bearer <token> が必須になります。ループバック以外のホストにバインドする場合、トークンを設定しないとサーバーは起動を拒否します。ただし、外部プロキシ／ゲートウェイに認証を委ねるために QVERIS_MCP_HTTP_ALLOW_UNAUTHENTICATED=true を設定した場合を除きます。QVERIS_API_KEY は QVeris に対するサーバーのアウトバウンド認証情報であり、インバウンドの認証には使用されません。そのため、認証なしのエンドポイントに到達できる人は誰でも、あなたのクレジットを消費できます。
• 埋め込み API： パッケージのルートから startHttpServer、resolveTransportConfig、QverisClient、セッション認証の型をエクスポートします。独立して運用されるサービスでは、解決済みのトランスポート設定で requireSessionBearer を設定し、非同期セッションファクトリーを提供できます。トランスポートはベアラーを必須とし、それをファクトリーにのみ渡します。また、セッションの紐付けには認証情報のフィンガープリントのみを保存し、認証情報の変更を拒否します。ホスト型の埋め込みでは、createQverisServer(client, sessionId, { includeDeprecatedAliases: false }) を呼び出すと、正式な7つのツールのみが公開されます。非推奨のエイリアスも、キャッシュ済みのレガシークライアントから引き続き呼び出せます。検証、クライアントの構築、レート制限、デプロイ、運用は、埋め込みサービスが担います。
• DNS リバインディング対策はデフォルトで有効です（localhost とバインド先のホスト／ポートが許可リストに登録されます）。サーバーを公開する場合は、QVERIS_MCP_ALLOWED_HOSTS に公開ホストを追加してください。
• リクエストのサイズはデフォルトで4 MiB（QVERIS_MCP_MAX_BODY_BYTES）までに制限され、アイドル状態のセッションは5分後（QVERIS_MCP_SESSION_TIMEOUT_MS）に削除されます。
• ディスカバリー： レジストリやクローラーは、サーバーに接続せずにサーバーの情報を取得できます。
  • サーバーカード： GET {path}/server-card（デフォルトは /mcp/server-card）、メディアタイプは application/mcp-server-card+json。サーバーの識別情報、バージョン、リモートエンドポイントを示します。
  • MCP カタログ： GET /.well-known/mcp/catalog.json。サイト全体のインデックスで、サーバーカードへのリンクを提供します。
  • どちらも認証トークンの設定にかかわらず、認証不要で CORS が有効です。TLS プロキシの背後で運用する場合は、QVERIS_MCP_PUBLIC_URL を設定するか、X-Forwarded-Proto を送信して、公開 URL に公開オリジンが使われるようにしてください。
  • 認証メタデータ： ホスト型デプロイでは、startHttpServer に渡す ServerCardInfo の remoteHeaders を設定することで、認証方法を公開できます。通常は、パッケージのルートからエクスポートされる bearerAuthHeaderInput() を使用します。これにより、変数が必須かつシークレットとしてマークされた Authorization: Bearer {api_key} テンプレートが宣言されるため、ディスカバリークライアントはキーの入力を促し、キーを安全に保存できます。buildServerCard は、シークレットの値そのものが記載されている場合に拒否します。シークレットのヘッダー値は {variable} テンプレートのままにする必要があり、シークレット変数に value／default を設定することはできません。各デプロイのカードには、そのデプロイ自身のエンドポイントのみを記載してください。別のサイトの URL を記載してはいけません。
  • スキーマの状態（実験的）： このカードは MCP Server Card の実験的拡張（SEP-2127）に準拠しています。公開 $schema URL（static.modelcontextprotocol.io/schemas/v1/server-card.schema.json）は正式なバージョン付きの場所ですが、まだ上流では公開されていません。そのため、生成されるカードは、上流の固定コミットからベンダー提供されたスキーマ（schemas/README.md）を使って CI で検証されます。別の非ブロッキング CI ステップでは公開 URL を確認し、利用可能かどうかと差異を報告します。
• このパッケージは、ホスト型 OAuth 認可サーバーを実装していません。独立して運用される HTTP デプロイでは、前述の埋め込み／セッション認証フックを通じて、認証情報の検証とセッションポリシーを管理します。

環境変数

変数	必須	説明
QVERIS_API_KEY	✓	QVeris API キー
QVERIS_BASE_URL		組み込みの API ベース URL を上書きします
QVERIS_MAX_RETRIES		レート制限（429）／一時的なエラー（503）の読み取り操作を再試行する回数（デフォルトは 3、0 で無効）。有料の呼び出しにはこの設定は適用されません。
QVERIS_MCP_TRANSPORT		stdio（デフォルト）または http
QVERIS_MCP_HTTP_PORT		HTTP ポート（デフォルトは 3000。設定すると HTTP モードになります）
QVERIS_MCP_HTTP_HOST		HTTP バインドホスト（デフォルトは 127.0.0.1）
QVERIS_MCP_HTTP_PATH		MCP エンドポイントのパス（デフォルトは /mcp）
QVERIS_MCP_ALLOWED_HOSTS		許可する追加の Host 値（カンマ区切り。DNS リバインディング対策用）
QVERIS_MCP_ALLOWED_ORIGINS		許可する追加の Origin 値（カンマ区切り）
QVERIS_MCP_DNS_REBINDING_PROTECTION		true（デフォルト）／false
QVERIS_MCP_HTTP_JSON		SSE の代わりに JSON レスポンスを返す場合は true（デフォルトは false）
QVERIS_MCP_HTTP_AUTH_TOKEN		MCP エンドポイントで Authorization: Bearer <token> を必須にします
QVERIS_MCP_HTTP_ALLOW_UNAUTHENTICATED		トークンなしでループバック以外のアドレスへのバインドを許可する場合は true（認証は外部に委譲されます）
QVERIS_MCP_MAX_BODY_BYTES		リクエスト本文の最大サイズ（バイト単位、デフォルトは 4194304）
QVERIS_MCP_SESSION_TIMEOUT_MS		アイドルセッションの TTL（ミリ秒、デフォルトは 300000）
QVERIS_MCP_CONFIRM_CALLS		課金対象の各 call の前に、MCP の elicitation を通じてユーザーに確認する場合は true。elicitation に対応していないクライアントでは、従来どおり処理が進みます
QVERIS_MCP_PUBLIC_URL		ディスカバリードキュメントで通知する公開オリジン（例：https://mcp.example.com）

API エンドポイントの上書き

QVERIS_BASE_URL が設定されていない場合、サーバーは組み込みの API エンドポイントを使用します。API キーのプレフィックスやその他の環境変数でエンドポイントが選択されることはありません。カスタムエンドポイントを指定するには、MCP クライアントの設定で QVERIS_BASE_URL を設定してください。

{
  "mcpServers": {
    "qveris": {
      "command": "npx",
      "args": ["-y", "@qverisai/mcp"],
      "env": {
        "QVERIS_API_KEY": "your-api-key",
        "QVERIS_BASE_URL": "https://qveris.ai/api/v1"
      }
    }
  }
}

上書き先には、認証情報、クエリ文字列、フラグメントを含まない HTTP(S) URL を指定する必要があります。

例

examples/agent-loop.ts は、エージェントのランタイムと同じ方法で、このサーバーを stdio 経由で実行します。サーバーを起動し、ツールを一覧表示してから、デフォルトの discover → call の流れを実行します。API キーなしでも安全に実行でき（未設定でもツールの一覧表示は可能です）、call の実行は RUN_QVERIS_CALLS=1 が設定されている場合に限られます。

要件

• Node.js 18.0.0 以降
• 有効な QVeris API キー（qveris.ai）

開発

# Clone the repository
git clone https://github.com/QVerisAI/qveris-agent-toolkit.git
cd qveris-agent-toolkit/packages/mcp

# Install dependencies
npm install

# Build
npm run build

# Run locally
QVERIS_API_KEY=your-key node dist/index.js

ライセンス

MIT © QVerisAI

サポート

• 🐛 課題トラッカー
• 💬 お問い合わせ先：[email protected]