vectros-ai

@vectros-ai/mcp-server

ワンクリックバッジを使うと、クライアントにサーバーのエントリがインストールされます。キーは別途用意してください。npx -y @vectros-ai/cli bootstrap を実行することをおすすめします。あるいは ssk_... を貼り付けてください。クライアントから接続すると正直な注意事項をご覧ください。

Model Context Protocol サーバーです。Vectros は、型付きのマルチテナント型ハイブリッド検索を統合したレコードストアと、引用に基づく RAG を提供します。顧客ごとに分離された単一のレコードおよびドキュメント用インデックスに対して、決定論的な検索と列挙に加え、セマンティック検索も実行できます。これにより、エージェントは曖昧な想起ではなく、正確なメモリを利用できます。ここでは MCP を介してエージェントネイティブに利用でき（Claude Desktop、Cursor、Claude Code、Cline、Continue、VS Code、ホスト型プラットフォーム）、同じデータに Vectros アプリと SDK から人間もアクセスできます。

npx -y @vectros-ai/mcp-server

エージェントは、インデックス化されたコーパスを検索し、構造化レコードをクエリし、ドキュメントを取り込み、ドキュメントに基づいた質問をすることができます。アクセスできるのは自分のテナントのデータだけで、公開ウェブにはアクセスしません（ウェブツールはありません）。

クイックスタート — 1 つのコマンドで設定

最もすばやく設定するには、@vectros-ai/cli の bootstrap コマンドを使います。絞り込まれた AccessProfile に紐づく最小権限のスコープ付きキー（ssk_*）を発行し、必要に応じてユースケース向けのデータモデルを作成します。また、MCP クライアントの設定に vectros サーバーを安全にマージします。 ルートキーは不要で、JSON を手作業で編集する必要もありません。

npx -y @vectros-ai/cli bootstrap

設定する内容（空の読み取り専用クレデンシャル、またはタスク追跡などのブループリント）を選び、開発者ポータルのトークンを使って一度だけサインインします。その後、コマンドは次の処理を行います。

• このマシン専用のスコープ付き ssk_* を発行します（個別にローテーション可能）。
• 対応する AccessProfile を作成します。データプレーン専用であり、コマンドはコントロールプレーンのスコープ（キー／プロファイル／請求など）のプロビジョニングを拒否します。
• claude_desktop_config.json（Claude Desktop、Cursor、Cline）のバックアップを作成してから、エントリーをマージします。Claude Code の場合は --client code を追加すると、プロジェクトの .mcp.json をマージし、同等の claude mcp add コマンドを表示します。

MCP クライアントを再起動すれば完了です。何度でも実行でき、冪等性があります。 --rotate を指定すると、このマシンのキーを置き換えます。

自分でデータを見たい場合：bootstrap が設定するのはエージェント用のキーであり、あなたのログインではありません。そのため、ブループリントのコンテキストに自分のユーザーを参加させるまでは、データプレーンアプリの切り替えメニューに表示されません（アプリには、ユーザーがアクセスできるコンテキストのみが表示されます）。管理アプリ（Access → Contexts → your context → Profiles → Create profile で、メールアドレスによる選択欄から自分を選び、ロールを選択します。生の ID は不要です）または CLI から --principal me を指定して、自分に一度ロールを付与してください（自分のユーザーに解決されます）。

vectros access grant --principal me --context <context-id> --role <role>

人間向けロールが用意されているブループリント（例：agentic-sdlc の editor）では --role を使えます。それ以外の場合は、--actions records:r,search:r,… でスコープをインライン指定します。

スクリプトやエージェントで使う場合は、サインイン用トークンを環境変数に設定して、プロンプトを省略できます。

VECTROS_BOOTSTRAP_TOKEN=… npx -y @vectros-ai/cli bootstrap \
  --blueprint task-management --yes

手動で接続したい場合は、以下の手動で設定を参照してください。

クライアントから接続

クライアント	ワンクリック	手動
Claude Desktop	デスクトップ拡張機能（.mcpb） — ダブルクリックして、キーを貼り付けます	JSON スニペット
Cursor		.cursor/mcp.json（以下と同じ形式）
VS Code		.vscode/mcp.json（最上位の servers キーの下に同じエントリーを追加します）
Claude Code	claude mcp add（以下）	プロジェクトの .mcp.json
Cline / Continue	—	Claude Desktop と同じ JSON スニペット
Smithery	npx -y @smithery/cli install @vectros-ai/mcp-server	—
Codex	—	TOML スニペット（以下）

すべてのクライアントで最も手早い方法は、npx -y @vectros-ai/cli bootstrap です。スコープ付きキーを発行し、設定を書き込みます。ワンクリックボタンでサーバーのエントリーをインストールした後、キーを指定します（bootstrap を使うか、ssk_... を貼り付けます）。

Codex（~/.codex/config.toml）：

[mcp_servers.vectros]
command = "npx"
args = ["-y", "@vectros-ai/mcp-server"]
env = { VECTROS_API_KEY = "ssk_live_..." }

率直な注意点

精度が売りです。意図的にこのサーバーが行わないことは次のとおりです。

• 人による手順が必要です。 ブートストラップには、開発者ポータルへのサインイン／ブリッジトークンが必要です。コマンドは1つですが、人がサインインする必要があり、完全に無人でのプロビジョニングはできません。
• 意図的にウェブツールはありません。 エージェント向けの機能には、ウェブ検索やウェブ取得のツールが一切ありません。Vectros はメモリーであり、ブラウザーではありません。
• 現在、エージェントからのドキュメントアップロードはテキストのインライン入力です。 エージェントはドキュメントのテキストをインラインで取り込みます。stdio トランスポートでは、隔離されたローカルファイルのアップロードがサポートされていますが、エージェント向けの機能からファイルを一括アップロードする方法は、現時点では用意されていません。
• 監査履歴は改ざんを防止するのではなく、改ざんを検出できるものです。 状態継続チェーンによって、範囲外で行われた変更を検出可能にしますが、継続的な自動検証を行うものではありません。

手動で設定する（Claude Desktop または任意の MCP クライアント）

@vectros-ai/cli をグローバルにインストールし（npm install -g @vectros-ai/cli。一度限りの npx の実行ではありません。ブートストラップの実行中だけでなく、後で IT を実行する際にもサーバーから vectros を PATH 上で参照できる必要があります）、その CLI で vectros bootstrap を実行済みの場合は、env ブロックを丸ごと省略できます。サーバーはローカルの vectros CLI キーリングからキーを自動的に解決します（詳しくは下記の認証情報の解決を参照してください）。vectros login だけではこの処理は行われません。別のサインインセッションが保存されるだけで、このキーは保存されません。そのため、実際に実行しておく必要があるのは bootstrap です。

{
  "mcpServers": {
    "vectros": {
      "command": "npx",
      "args": ["-y", "@vectros-ai/mcp-server"]
    }
  }
}

CLI がインストールされていない場合、またはログインできないマシンの場合は、代わりにキーを直接設定してください。

{
  "mcpServers": {
    "vectros": {
      "command": "npx",
      "args": ["-y", "@vectros-ai/mcp-server"],
      "env": {
        "VECTROS_API_KEY": "ssk_live_..."
      }
    }
  }
}

このファイルは共有リポジトリではなく、Claude Desktop 専用のユーザーごとのアプリケーションサポートディレクトリにあります。ただし、実際のキーを貼り付けると、保存されている間も有効なシークレットであることに変わりはありません。値をそのままチャット、チケット、スクリーンショットに貼り付けないでください。可能であれば、上記のキーリング方式を使用してください。

Claude Desktop を再起動してください。これでエージェントから、Vectros のツールと2つのリソースを呼び出せるようになります。

手動で設定する（Claude Code）

Claude Code は、同じ形式のプロジェクト単位の .mcp.json を読み込みます。 実際のキーを絶対にコミットしないでください。.mcp.json は、チームがプロジェクトのツールを共有するためにチェックインする典型的なファイルであり、そこに有効な ssk_*／sk_* の値を記載すると、リポジトリが公開されているかどうかにかかわらず、git の履歴に追加された時点で認証情報が漏えいします。

この設定を安全に共有するには、env ブロックをまったく含めずにエントリーをコミットし、各開発者が自身の vectros CLI キーリングからキーを提供するようにします（以下の認証情報の解決を参照してください。これは git credential／docker-credential-* と同じ委任方式です）。これには、各チームメイトが @vectros-ai/cli をグローバルにインストールし、そこで vectros bootstrap を実行している必要があります。CLI を一度だけ npx で実行したり、vectros login のみを実行したりしても（これは別個のサインインセッションであり、このキーではありません）、後でサーバーが見つけられるような PATH 上の実行ファイルもキーリング内のキーも用意されません。

{
  "mcpServers": {
    "vectros": {
      "command": "npx",
      "args": ["-y", "@vectros-ai/mcp-server"]
    }
  }
}

または、Claude Code の CLI にキーリングベースのエントリーを書き込ませることもできます。

claude mcp add vectros -- npx -y @vectros-ai/mcp-server

マシンに vectros CLI がインストールされていない場合は、キーを -e VECTROS_API_KEY=ssk_live_... で直接渡すことができます。ただし、その場合は設定をローカルに保ってください。キーを含めてコミットするのではなく、まず .mcp.json を .gitignore に追加してください。

サーバーを別の環境に接続するには、-e VECTROS_API_BASE_URL=<your environment's API base URL> を追加します。

セッションに読み込むには、再起動してください。 サーバーを追加した時点ですでに開いていた Claude Code セッションでは、セッションの途中で設定は反映されません。プロジェクトを完全に終了して開き直してください（タブを選び直すだけでは不十分です）。/mcp パネルに表示されるのはコネクタのマーケットプレイスであり、ローカルに設定された stdio サーバーではないため、サーバーが読み込まれたことの確認には使えません。代わりに、エージェントに Vectros ツールを呼び出すよう依頼してください。設定はgit の共通ルートをキーとして管理されるため、リンクされたワークツリーではメインリポジトリの .mcp.json が使われます。同じプロジェクトから追加し、開いてください。

Windows に関する注意： .npmrc（またはグローバルの npm 設定）で @vectros-ai スコープが別のレジストリを参照している場合、引数を指定しない npx -y @vectros-ai/mcp-server によって、公開リリース以外のビルドが解決されることがあります。上記のコマンドで起動に失敗する場合は、スコープ付きレジストリの上書きを解除して通常の npx を実行するか、動作確認済みの明示的なバージョン（npx -y @vectros-ai/mcp-server@<version>）を指定してください。

ツール（23 個）

検索と RAG

ツール	機能
hybrid_search	テナントのインデックス済みコンテンツ（レコード＋ドキュメント）を対象に、BM25 と密ベクトル検索を組み合わせて検索します。所有権（1 つの次元には scope、複数の次元には scopeFilters を使用します。例：1 つの組織内の 1 つのクライアント）、フォルダー、種類、メタデータフィルター、作成日の範囲、キーワード精度（textMode）／関連性の下限で絞り込めます。各検索結果のインデックス済みプロジェクションを返します。
rag_ask	インデックス済みコーパスに基づいて質問します。search（所有権。search.scope または複数の次元に対応する search.scopeFilters を使用します。フォルダー／種類／メタデータフィルター／日付範囲も指定できます）で検索対象を絞り込み、生成を調整できます（instructions と、対応モデルで使用できる temperature）。ストリーミング生成を集約します。進行状況通知により、生成中も呼び出しが維持されます。オプションの providerAlias を指定すると、1 回の呼び出しを独自のモデルプロバイダー経由で実行できます（下記を参照）。
document_ask	1 つのドキュメントに基づいて質問します。オプションの providerAlias を含め、rag_ask と同じ集約方式および進行状況通知方式を使用します。

レコード（構造化されたスキーマ検証済みデータ）

ツール	機能
list_schemas	認証情報から参照できるレコードスキーマカタログを一覧表示します（surface で絞り込むか、recordType でいずれかを解決します）。record_query／record_create の検出に利用できます。
record_query	検索フィールドでレコードを検索します。等価（value）、範囲、プレフィックスによる検索に対応し、asc／desc の並べ替えと、任意の sortFrom／sortTo ウィンドウを指定できます。またはリストモードで、type、folderId（フォルダー内の全レコード。型は問いません。type と組み合わせると絞り込めます）、recent（全型を対象とした、アカウント全体の最近更新されたレコードの一覧）からいずれかを選び、最初の2つについては必要に応じて所有権で絞り込めます。複合等価検索（values）で2～3フィールドを指定することもできますが、対象にできるのは、スキーマでそれらのフィールドをまとめた検索が宣言されている場合に限られます（list_schemas を参照）。任意の2フィールドを選べるわけではありません。
record_get	IDでレコードを1件取得します。全ペイロードを含みます（大きなペイロードは、エージェントのコンテキストウィンドウを保護するために切り詰められます）。
record_batch_get	1回の呼び出しで、IDを指定して複数のレコード（1～100件）を取得します。それぞれ全ペイロードを含みます。APIはアクセスできないIDを通知なく省略するため、取得できない要求済みIDは missingIds として返します。
record_create	指定した型のレコードを作成します。externalId による冪等性に対応し、レコードごとに任意の indexMode を指定できます。
record_batch_write	record_create をN回呼び出す代わりに、1回の呼び出しで最大50件のレコードを作成またはアップサートします。アイテムは複数の型を混在させることができ、それぞれ個別に検証およびスコープ確認されます。atomicity: all_or_nothing を指定すると、1つのトランザクションとしてコミットされます（いずれかのアイテムが失敗した場合、何も書き込まれません）。デフォルトの best_effort では、それぞれ個別に書き込まれます。バッチが処理された場合は成功として報告されます。エラーがないことだけで判断せず、アイテムごとの results を確認してください。
record_update	レコードのペイロードにパッチを適用します（ディープマージ。null はキーを削除します）。expectedVersion による楽観的同時実行制御に対応します。
record_delete	IDでレコードを完全に削除します（墓石が残ります）。

ドキュメント（検索とQ&A用にインデックス化されたテキスト／ファイルのコンテンツ）

ツール	機能
document_ingest	ドキュメントを作成します。テキスト本文を直接指定する方法と、ローカルファイルをアップロードする方法があります（ファイルモードはstdioトランスポートのみ）。externalId による冪等性に対応し、型付きで検索フィールドによるクエリが可能なドキュメントにするための、任意の schemaId と payload を指定できます。schemaId を指定せずに externalId を指定すると、confirmUntyped: true も渡さない限り、プラットフォーム0.46.0以降では拒否されます。
document_query	検索フィールドでドキュメントを検索します（等価／範囲／プレフィックス検索に対応し、asc／desc で並べ替え可能）。またはリストモードで、フォルダーと所有権で絞り込めます。
document_get	IDでドキュメントを取得します（ライフサイクルの status と処理状況の indexStatus を含むメタデータを取得します。任意でテキストを取得できますが、約8Kトークンを超える部分は切り詰められます。ファイルを使用するドキュメントには、任意で署名付きの downloadUrl を指定できます。ファイルの種類にかかわらず、常にダウンロードを強制し、インライン表示は行いません）。
document_update	ドキュメントのメタデータ／型付きペイロードにパッチを適用します（ディープマージ）。status によってアーカイブ／復元できます（ARCHIVED は検索対象からソフト削除し、ACTIVE は復元します）。expectedVersion による楽観的同時実行制御に対応します。
document_delete	IDでドキュメントを完全に削除します（ドキュメントとインデックス化されたコンテンツを削除します）。

フォルダー（レコードとドキュメントをグループ化）

ツール	機能
folder_query	IDでフォルダーを取得するか、フォルダーの一覧を表示します（ツリーをたどるための親フォルダーの子フォルダー、またはテナント全体のフラットな一覧。nextCursor によるページネーションに対応します）。
folder_create	フォルダーを作成します。
folder_update	フォルダーの名前／説明／所有権を更新します（マージパッチ。expectedVersion による楽観的同時実行制御に対応します。フォルダーの親を変更することはできません）。
folder_delete	フォルダーを削除します。事前に空にしておく必要があります（ドキュメント、レコード、サブフォルダーがないこと）。また、コンテキストルートは削除できません。

IDと履歴

ツール	機能
current_identity	認証情報について、tenantId、environment、principalType、principalKeyId、principalLabel、および（スコープ付き認証情報の場合）allowedActions と dataScope を説明します。granted_capabilities（API 0.40.0 時点では member-lifecycle／forensic-read／context-directory-read／delegate-mint。0.42.0 では delegate-principal-stamp、0.44.0 では trigger-control-plane-grant が追加されています）はまだ含まれません。これはスコープ句に含められる別の到達範囲を示すもので、現時点では /v1/ping には報告されないため、allowedActions と dataScope だけでは認証情報が実際に持つ到達範囲を過小評価する場合があります。また、このサーバー自体のバージョンと同梱 SDK のバージョン（mcpServerVersion、sdkVersion）も報告します。
lookup_principal	ユーザー、または名前空間（org／client／登録した任意の名前空間）内の ID エンティティを、独自の externalId（→所有者フィルターに使う Vectros UUID）またはスキーマの検索フィールドで特定します。コンテキスト所有の名前空間を対象にするには、特定のアプリコンテキストを指定する contextId を渡します。読み取り専用です。
version_history	1 件のレコードまたはドキュメントの監査／バージョン履歴（実行者と差分を含む CREATE／UPDATE／DELETE）を読み取ります。読み取り専用です。

23 個のツールはすべて、公開されている Vectros HTTP API エンドポイントをラップします。JSON レスポンスがツール出力としてエージェントに表示されます。呼び出しごとのコストは、推論レスポンスの usage フィールドで確認できます。

同時更新。 record_update、document_update、folder_update および upsert: true を指定した document_ingest は、 expectedVersion を渡したかどうかにかかわらず、別のリクエストが同じアイテムを同時に変更すると 409（errorCode: VERSION_CONFLICT）を返します。書き込みは行われず、相手側の変更が保持されます。アイテムを再読み込みしてから、もう一度試してください。 expectedVersion を指定すると、相手側の変更がかなり前に完了していた場合でも、以前に読み取ったバージョンに基づく更新は拒否されます。直前に削除されたアイテムを更新すると 404 が返されます。upsert を指定した record_batch_write では、同時に別の変更が行われたアイテムは、結果内で status: conflict と errorCode: VERSION_CONFLICT とともに報告されます。そのアイテムを再送してください。atomicity: all_or_nothing で書き込まれたアイテムは対象外です。

削除済みスキーマのアイテム。 スキーマが存在しなくなったアイテムは提供されません。そのアイテムの読み取り（record_get、 document_get）はエラーになり、更新、version_history の読み取り、ドキュメントのテキスト、ダウンロードまたは回答（document_ask）の読み取りは拒否されます。また、record_query、document_query、record_batch_get の結果には含まれません。アイテムを削除してください。

独自のモデルプロバイダー経由で呼び出しをルーティングする

rag_ask と document_ask には、オプションの providerAlias を指定できます。これは、Vectros アカウントで有効化したモデルプロバイダー設定のエイリアスです。指定すると、その呼び出しはプラットフォームがホストするデフォルトではなく、独自のプロバイダーによって処理されます。この場合、model にはプロバイダー独自の ID 空間にあるモデルを指定します。省略すると、そのプロバイダー設定のデフォルトモデルが使用されます。サーバーは providerAlias が指定された場合にのみ転送し、自動で補完することはありません。

この機能を使うには、アカウントでプロバイダーを設定し、プラットフォームのリスク承諾免責条項に署名する必要があります。両方が揃っていない場合、プラットフォームは呼び出しを 403 で拒否し、ツールはその内容をそのまま返します。免責条項が原因の場合、403 には該当するケースを示す errorCode が含まれます。WAIVER_NOT_SIGNED（免責条項に署名していない）、WAIVER_TEXT_CHANGED（署名済みだが、その後に文面が変更されたため、以前の署名が無効になった）、または WAIVER_REVOKED（アカウント所有者が取り消した）のいずれかです。アカウント所有者は開発者ポータルの Model Providers でそれぞれの問題を解決できます。呼び出しを再試行しても解決しません。

アカウントが開発者ポータルで Vectros との Business Associate Agreement に同意している場合、呼び出しでプロバイダー設定を使用するには、アカウント所有者が開発者ポータルの Model Providers で各プロバイダー設定を認証する必要もあります。それまでは、プラットフォームは BAA 保持者による認証が必要であることを示す 403 で呼び出しを拒否します。認証は所有者がポータルで行います。このサーバーでは行いません。

独自のプロバイダーで処理される呼び出しは、プラットフォームがホストする Bedrock の経路と Vectros の AWS BAA の適用範囲から外れるため、個々の呼び出しで使用するかどうかを慎重に判断してください。ここに記載されている内容は、選択したプロバイダーがデータをどのように扱うかを示すものではありません。

使用するツールを一部に限定する

VECTROS_MCP_TOOLS=hybrid_search,record_query,record_get を渡すと、その3つのみが登録されます。これは、エージェントに読み取り専用アクセスを提供しながら、認証情報による取り込みや推論のコスト発生を避けたい場合に便利です。認証情報で推論残高を使用させる場合に限り、rag_ask または document_ask を追加してください。不明なツール名がある場合、起動時にすぐエラーになります。

リソース

周辺コンテキスト用の読み取り専用リソースが2つあります（ツール呼び出しは不要です）。

URI	返される内容
vectros://schemas	list_schemas と同じペイロードです。エージェントがスキーマをコンテキストに事前読み込みし、周辺情報を探索できるようにします。
vectros://identity	current_identity と同じペイロードです。エージェントがツール呼び出しを使わずに自身の情報を提示できます。

推奨する認証情報

ルートキー（sk_*）ではなく、スコープ付きの永続 API キー（ssk_*）を使用してください。

スコープ付きキーは、範囲を絞った AccessProfile に紐付けられています。たとえば、1 つの組織スコープ（scope:org）全体に対する読み取り専用の設定です。MCP のインストール環境が侵害された場合でも、被害範囲はプロファイルが許可する範囲に限られ、テナント全体には及びません。このため、ワイルドカードの sk_* を指定すると、サーバーは起動時に warn ログを出力します。

最も簡単な取得方法は、（上記の）npx -y @vectros-ai/cli bootstrap を実行することです。 ルートキーを使わずに、最小権限の ssk_* と AccessProfile が自動的に発行されます。手動で行う場合は、開発者ポータルの Keys → Create scoped key からスコープ付きキーを発行し、読み取り専用の AccessProfile（名前は任意です。たとえば mcp-read）に紐付けて、生成された ssk_live_... を上記の設定に追加してください。

最小権限の認証情報を設定する方法については、スコープ付きトークンに関する Vectros の開発者向けドキュメントをご覧ください。vectros bootstrap フローでは、1 つのコマンドでスコープ付きの ssk_* キーとその AccessProfile が作成されます。

API 0.43.0 以降、ルート sk_* では別のアプリコンテキストにファイルを登録できなくなりました。 このサーバーをルートキーで実行し、ツール呼び出しで default 以外のコンテキストに属する folderId / parentFolderId、またはドキュメントの schemaId を指定すると、呼び出しは一律に 400 "Folder not found" / "Schema not found" で拒否されます。これは document_ingest、document_update、 record_create、record_update、folder_create に影響し、結果が変わる変更です。以前はこれらの呼び出しは成功していました。 ただし、実際には見かけどおりの動作をしていたわけではありません。ルートキーによる書き込みには常に default が付与されるため、行は default に登録される一方で、フォルダーやスキーマは別の場所にあり、それらを所有するコンテキストからは永久に見えない状態になっていました。以前の方法で書き込まれた既存の行には影響がなく、引き続き読み取り、更新、削除が可能です。解決策は、上記で推奨したスコープ付きキーを使うことです。対象のコンテキストに紐付けられたキーであれば、そのコンテキストにファイルを登録できます。

認証情報の解決

サーバーは、キーが見つかった最初のソースから API キーを取得します。

1. VECTROS_API_KEY — 設定されている場合は常に優先されます。
2. vectros CLI のキーリング — キーが未設定で、@vectros-ai/cli 0.9.0+ が PATH 上にある場合、サーバーはサブプロセスとして vectros keyring show --format raw を実行し、出力されたキーを使用します。デフォルトではアクティブな ID が使われます。特定のエントリーを選択するには、VECTROS_KEYRING_ALIAS を設定してください。これは git credential / docker-credential-* / aws credential_process と同じパターンです。キーは 1 か所に保管され、サーバー、スクリプト、エージェントのフックはそれぞれ平文のコピーを保持して不整合が生じるのではなく、同じ場所からキーを読み込みます。
3. どちらも利用できない場合 — 2 つの選択肢を示すメッセージとともに、起動に失敗します。

解決されたキーはメモリ上に保持され、ログに記録されることはありません。起動ログには、解決に使用したエイリアス（キーではありません）が出力されるため、サーバーがどの ID として実行されているかをすぐに確認できます。vectros keyring doctor（CLI 0.10.0+）でも同じ情報を確認できます。

指定していない ID が選択されると、起動時に警告が表示されます。 VECTROS_API_KEY が未設定で VECTROS_KEYRING_ALIAS も設定されていない場合、サーバーはアクティブなキーリングエントリーを使用し、警告をログに出力します。 実行時には、最後に vectros switch で選択した ID が使われます。実データを操作する ssk_live_* キーの場合もあれば、 実データを操作しない ssk_test_* キーの場合もあります。どちらも意図しない結果を招く可能性があります。これは、クライアント設定の空のプレースホルダー（"VECTROS_API_KEY": ""）や、Docker で未設定の変数を渡す -e VECTROS_API_KEY が「まだ設定されていない」と解釈される一方、キー未設定時と同じように解決されるためです。処理がブロックされることはありません。VECTROS_KEYRING_ALIAS でエントリーを指定するか、VECTROS_API_KEY を設定すると、警告は表示されなくなります。vectros keyring doctor（CLI 0.10.0+）では、アクティブなエントリーと、キーのうちどれが live かを確認できます。

環境変数

Var	必須	デフォルト	用途
VECTROS_API_KEY	いいえ*	—	Vectros API キーです。sk_*／ssk_*／st_* を受け付けます。ssk_* を推奨します。*vectros CLI が使用可能なキーリングエントリとともにインストールされている場合を除き必須です。認証情報の解決を参照してください。設定されている場合は、こちらが優先されます。
VECTROS_KEYRING_ALIAS	いいえ	（アクティブなエントリ）	アクティブなエントリの代わりに、この vectros キーリングエントリを解決します。VECTROS_API_KEY が設定されている場合は無視されます。
VECTROS_API_BASE_URL	いいえ	https://api.vectros.ai	別の環境を使用する場合のオーバーライドです。検証されます。https://（または localhost への http://）で始まり、公式の *.vectros.ai ホストである必要があります。
VECTROS_ALLOW_INSECURE_BASE_URL	いいえ	—	1 を設定すると、ベース URL の許可リストを無効にします（例：信頼できるローカルプロキシ）。推奨されません。検証されていないホストにキーが送信され、警告がログに記録されます。
VECTROS_MCP_INGEST_ROOT	いいえ	プロセスの cwd	document_ingest の filePath モードで許可されるディレクトリです。ここから逸脱するパス（トラバーサル／絶対パス／シンボリックリンク）や、機密パターンに一致するパスは拒否されます。
VECTROS_MCP_TOOLS	いいえ	（すべてのツール）	ツール名をカンマ区切りで指定します（例：hybrid_search,rag_ask）。
VECTROS_MCP_DEBUG	いいえ	—	1 を設定すると、詳細な stderr ログを出力します。
VECTROS_MCP_SKIP_PING_VALIDATION	いいえ	—	1 を設定すると、起動時の /v1/ping チェックを無効にします。
VECTROS_MCP_HTTP_PORT	HTTP のみ	8765	HTTP トランスポートのポートです。
VECTROS_MCP_HTTP_HOST	HTTP のみ	127.0.0.1	バインドアドレスです。すべてのインターフェースで待ち受けるには 0.0.0.0 を使用します（その場合はベアラートークンを設定してください）。
VECTROS_MCP_HTTP_BEARER_TOKEN	HTTP のみ	—	クライアント→サーバーのベアラートークンです。localhost の範囲を超えて使用する場合は強く推奨され、ループバック以外にバインドする場合は必須です。
VECTROS_MCP_HTTP_ALLOWED_HOSTS	HTTP のみ	—	許可する追加の Host 値をカンマ区切りで指定します（DNS リバインディング対策）。リバースプロキシの背後にある公開ホスト名を設定します。
VECTROS_MCP_HTTP_ALLOWED_ORIGINS	HTTP のみ	—	許可する追加の Origin 値をカンマ区切りで指定します。
VECTROS_MCP_HTTP_ALLOW_INSECURE	HTTP のみ	—	1 を設定すると、ベアラートークンなしでループバック以外にバインドできるようになります。推奨されません。

起動時の認証情報検証

最初のツール呼び出しの前に、サーバーは認証情報に対して GET /v1/ping チェックを実行します。不正なキーの場合は、 会話の途中で不明瞭な 401 エラーになるのではなく、明確な エラーが表示されて起動に失敗します。無効にするには VECTROS_MCP_SKIP_PING_VALIDATION=1 を設定してください。

HTTP トランスポート

ホスト型 MCP の用途（ネットワーク境界の背後でサーバーを実行する、 複数のエージェントインスタンス間で共有する、サイドカーとして デプロイするなど）向けに、このパッケージには HTTP バイナリも 同梱されています。

VECTROS_API_KEY=ssk_live_... \
VECTROS_MCP_HTTP_PORT=8765 \
VECTROS_MCP_HTTP_BEARER_TOKEN=$(openssl rand -hex 32) \
  npx -y -p @vectros-ai/mcp-server vectros-mcp-server-http

HTTP バイナリはデフォルトではありません。npx -p <pkg> vectros-mcp-server-http を使って明示的に選択してください。引数なしの npx -y @vectros-ai/mcp-server は常に stdio サーバーを起動します。

デフォルトでは、サーバーは http://127.0.0.1:8765/mcp で リッスンします。ベアラートークンは省略できますが、localhost の 範囲を超えてデプロイする場合は強く推奨されます。トークンがないと、 ポートにアクセスできる人は誰でも、あなたの認証情報を使って Vectros を 呼び出せます。

ヘルスプローブは GET /healthz で利用できます（常に認証不要で、 k8s の readiness チェックに対応しています）。

現在の制限事項：サーバーはプロセスごとに 1 つの上流認証情報を使用します （起動時に解決されたキー）。受信した Authorization ヘッダーによる リクエストごとの認証情報オーバーライドは、今後の機能強化として予定されています。 現時点では、必要な認証情報の境界ごとにサーバーを 1 つデプロイしてください。

プログラムからの使用（上級者向け）

ほとんどの利用者は上記の CLI 形式を使います。独自の Node プロセスに サーバーを組み込む必要がある場合：

import { VectrosMCPServer, createStdioTransport } from '@vectros-ai/mcp-server';

const server = new VectrosMCPServer({
  apiKey: process.env.VECTROS_API_KEY!,
  tools: ['hybrid_search', 'rag_ask'],
  resources: ['schemas'],     // opt-in resource filter; default = all
  validateOnStart: true,      // default — set false to skip startup ping
});
await server.connect(createStdioTransport());

このサーバーが意図的に公開していないもの

これはバックログではなく、意図的な判断です。MCP サーバーは、自律的な呼び出し元に提供するツールの窓口です。そのため、API が提供する機能が自動的にツールになるわけではありません。エージェントに提供する機能は、それぞれ採用に値する理由が必要です。

境界となるのはデータプレーンです。レコード、ドキュメント、フォルダー、検索はすべてここで利用できます。権限を付与または管理する機能は含まれません。また、データモデルを定義する設計時レイヤーも含まれません。

• 保存済みスクリプト（/v1/scripts — push、list、fetch、delete）。保存済みスクリプトはデータではなくコードです。スクリプトの作成は設計時の作業であり、スキーマの変更をここではなく CLI で行うのと同じ理由です。後から自分の認証情報で実行されるコードを書き込めるエージェントは、レコードを書き込めるエージェントとは別のものです。
• 同期スクリプト実行（POST /v1/scripts/execute、scripts:x スコープ）。2つの中では公開に近い機能ですが、範囲の問題ではなく運用上の理由から除外しています。scripts:x:<name> 権限は、スクリプトごとに意図的に細かく限定されており、通常のスコープ付きキーでも保持できます。エージェントがうまく対処できないのは、失敗時の状況です。実行結果を確定できない場合、書き込みがコミットされたかどうかが不明なまま 500 EXECUTION_OUTCOME_UNKNOWN が返されます。呼び出し元は再試行しても解決できず、結果を確認しに行く必要があります。また、正しく再試行するには、試行間で同じ Idempotency-Key を再利用する必要がありますが、ツール呼び出しには自然な再試行識別子がありません。そのため、タイムアウト後にエージェントが再度呼び出すと、スクリプトが気付かれないまま2回目に実行されてしまいます。これら2つの問題に適切に対処して公開するには、薄いラッパーではなく、意図的な設計が必要です。それまでは、API、SDK、CLI など、スクリプトを適切に処理できる呼び出し元から実行してください。
• トリガールール（/v1/triggers）。ルールの宣言は権限を付与します。ルールの scopes／roleIds は有効であり、他の権限付与機能と同様に、宣言時にはスコープ単調性のチェックが行われます。権限の付与はエージェントが行う操作ではありません。
• トリガー失敗履歴（GET /v1/trigger-failures）と使用状況／課金（GET /v1/usage）。どちらも読み取り専用ですが、データプレーンではなく運用に関する情報です。コンテンツの内容ではなく、自動化やアカウントの状況を示します。これは、エージェントがタスクの途中で使うツールではなく、人が確認する開発者ポータルまたは CLI で確認する情報です。
• ID、アクセス権、認証情報の管理 — ユーザー、アクセスプロファイル、ロール、アプリコンテキスト、発行者の登録、スコープ付きキーの発行。リリース以来変更はありません。ID の CRUD をエージェント用ツールの窓口に含めないのは意図的な設計です。lookup_principal は識別子を ID に解決するだけで、それ以外の処理は行いません。
• コンプライアンス関連の操作（消去、エクスポート）。同じ理由です。

これらの機能をエージェントに提供すべきだと思われる場合は、ぜひお知らせください。境界は意図をもって定めていますが、理由があれば見直すことができます。

このサーバーが（まだ）対応していないこと

• プロンプト機能はありません — /rag と /ingest_pdf のスラッシュコマンドテンプレートは、今後のリリースで追加されます。（プロビジョニング — bootstrap コマンド — は、別パッケージの @vectros-ai/cli にあります。）
• HTTP トランスポートは、1つのプロセスにつき1テナントです — リクエストごとに受信する Authorization ヘッダーで認証情報を上書きする機能は、v1.0 以降の改善項目です。
• Python 実装はありません — TS のみです。Python ユーザーは、任意のプロジェクトからこのサーバーを npx で実行できます。
• rag_ask と document_ask はネイティブのストリーミングに対応していません — ツールが応答する前に、回答全体が集約されます。処理中の遅延は進捗通知でカバーします。ネイティブの MCP 仕様に準拠したストリーミングは、仕様が安定した段階で追加されます。

このサーバーは、安定版 1.0 リリースに向けて、1.0 より前の開発段階にあります。

レート制限

ツール呼び出しには、他の API クライアントと同じ分単位のレート制限が適用されます。レート制限ガイドでは、どのリクエストがカウントされるかを説明しています。レート制限による 429 が発生すると、ツールは HTTP 429 および errorCode: RATE_LIMITED とともにエラーを返すため、エージェントは無作為に再試行するのではなく、ペースを調整して再試行できます。rag_ask と document_ask は、errorCode: BALANCE_BUSY を伴う 429（前払い残高が他の同時リクエストによって一時的に処理中です。レート制限でも残高不足でもないため、追加チャージせず、しばらくしてから再試行してください）、または errorCode: BALANCE_UNAVAILABLE を伴う 503（残高処理が一時的な障害によって中断されました。こちらも残高不足ではないため、しばらくしてから再試行してください）を返す場合もあります。402 は、残高不足（INSUFFICIENT_BALANCE）またはプランの使用上限到達（SUBSCRIPTION_LIMIT_EXCEEDED）を意味します。providerAlias を指定した呼び出しで errorCode のない 503 が発生した場合、プラットフォームが保存済みのプロバイダーキーを開けません。しばらくしてから再試行し、解消しない場合は開発者ポータルでキーを再入力してください。ツールが返すのはメッセージ、errorCode、requestId であり、Retry-After ヘッダーは含まれません。このガイドにはプランごとの制限も記載されています。

ソースからビルドする

git clone https://github.com/vectros-ai/vectros-mcp-server
cd vectros-mcp-server
npm install
npm run build
npm test

npm install は、設定済みの npm レジストリから @vectros-ai/sdk を取得します。

npm run build は tsup を実行し、dist/ に ESM/CJS の両形式の出力を生成します。SDK はビルドにバンドルされるため（tsup.config.ts を参照）、公開される npm パッケージは自己完結しており、利用者の環境で .npmrc の設定なしに動作します。

セキュリティと信頼性

Vectros は、顧客ごとのフェイルクローズ方式の分離と、最小権限のスコープ付きキーを適用し、改ざんを検知できる監査記録とバージョン履歴を備えています。顧客向けの各種機能は、広範な敵対的セキュリティレビューを通じて強化されています。境界を明示した信頼性に関する全体像は、コンプライアンスと信頼性に関するガイドをご覧ください。

ツールの出力は信頼できない、API から提供されたコンテンツです。 ここにある各ツールは、ドキュメントのテキスト、検索結果、エラーメッセージなど、お客様自身のテナントのデータを MCP レスポンス内のプレーンテキストとして返します。このサーバーはそのテキストをサニタイズ、エスケープ、事前レンダリングせず、いずれのツールも評価または実行しません。ツールの出力は、エージェントが外部ソースから取得した他のデータと同じように、クライアント側で安全にレンダリングしてください。eval したり、事前にサニタイズされているものとして信頼したりしないでください。

ライセンス

Apache-2.0。LICENSE ファイルをご覧ください。