Vantage MCP Server

概要

Vantage MCP サーバーは、Vantage リソースの一覧表示、クエリ、作成を行うツールを提供します。ツールは /src/tools で定義されています。ツール一覧、プロンプトの例、製品の詳細については、Vantage MCP ドキュメントをご覧ください。

このリポジトリでは、次の 2 つのデプロイモードに対応しています。

モード	適した用途
ホスト型（リモート）MCP — Vantage が管理する https://mcp.vantage.sh/mcp	ほとんどのユーザーやチーム。OAuth サインインを使用し、ローカルでサーバーを起動する必要はありません。
セルフホスト（ローカル）MCP — npx -y vantage-mcp-server またはこのリポジトリ経由の stdio	API トークン認証、エアギャップ環境、またはこのコードベースへのコントリビュートに適しています。

特別な理由がない限り、ホスト型 MCP から始めてください。

セットアップ手順

全般

ホスト型 MCP サーバーは、OAuth 2.1 を使用した Streamable HTTP を使用します。クライアントを接続すると、ブラウザーウィンドウが開き、console.vantage.sh で使用しているものと同じアカウントで Vantage にサインインするよう求められます。

サーバー URL： https://mcp.vantage.sh/mcp

旧 SSE 接続： /sse エンドポイントは非推奨となっており、移行期間の 60 日間は引き続き利用できます。この期間は 2026 年 11 月 30 日に終了し、その時点で旧 SSE エンドポイントは廃止されます。クライアントで https://mcp.vantage.sh/sse を使用している場合は、サーバー URL を https://mcp.vantage.sh/mcp に更新し、トランスポートの選択を求められたら Streamable HTTP を選択してから、再接続してください。求められた場合はサインインしてください。接続時に非推奨の警告が表示されるクライアントもあれば、表示されないクライアントもあります。

リモート MCP にネイティブ対応しているクライアントは、この URL に直接接続できます。stdio のみに対応しているクライアントでは、mcp-remote ブリッジを使用してください（下記のVisual Studio Codeを参照）。

API トークン認証： クライアントやスクリプトは、サービス トークンを含む Vantage API トークンを送信することで、OAuth を使わずにホスト型エンドポイントで認証できます。

Authorization: Bearer <your_vantage_api_token>

Core は各ツール呼び出しのたびにトークンとその権限を検証します。読み取りには read スコープが必要です。変更には、対応する書き込み権限が必要です。無効または失効したトークンでも MCP の初期化はできますが、ツール呼び出しでは Core の認可エラーが返されます。

Claude Code

claude mcp add --transport http vantage https://mcp.vantage.sh/mcp

その後、Claude Code のセッションで /mcp を実行し、OAuth フローを完了してください。

Codex

codex mcp add vantage --url https://mcp.vantage.sh/mcp

Codex で認証を求められた場合は、codex mcp login vantage を実行してください。

Cursor

推奨されるインストール方法は、Vantage の公式プラグインです。Cursor のチャットパネルで次を実行してください。

/add-plugin vantage

手動で設定する場合（たとえば .cursor/mcp.json をリポジトリにコミットする場合）は、次のようにします。

{
  "mcpServers": {
    "VantageMCP": {
      "url": "https://mcp.vantage.sh/mcp"
    }
  }
}

Cursor Settings → Tools & MCP → New MCP Server を開いて mcp.json を編集するか、プロジェクトのルートに .cursor/mcp.json を作成してください。

Claude

Claude.ai（Team / Enterprise）： Settings → Connectors → Add custom connector を選択し、https://mcp.vantage.sh/mcp を入力します。

Claude Desktop： Settings → Connectors を選択し、同じ URL を指定してカスタムコネクターを追加します。

Goose

1. Extensions → Add custom extension
2. Type： Streamable HTTP
3. Endpoint： https://mcp.vantage.sh/mcp

Goose の接続時に OAuth フローを完了してください。

Visual Studio Code

{
  "mcpServers": {
    "vantage": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.vantage.sh/mcp"]
    }
  }
}

または、コマンドパレットで MCP: Add Server → Command (stdio) を選び、次を入力します。

npx -y mcp-remote https://mcp.vantage.sh/mcp

Windsurf

Cascade → MCP servers → Add custom server で、次を追加します。

{
  "mcpServers": {
    "vantage": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.vantage.sh/mcp"]
    }
  }
}

Zed

Zed の設定に次を追加します。

{
  "context_servers": {
    "vantage": {
      "source": "custom",
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.vantage.sh/mcp"],
      "env": {}
    }
  }
}

その他のクライアント

stdio のみをサポートする MCP クライアントでは、次を使用します。

• コマンド： npx
• 引数： -y mcp-remote https://mcp.vantage.sh/mcp

その他のクライアントについては、MCP クライアント一覧および Vantage MCP ドキュメントをご覧ください（Vantage アプリ経由の ChatGPT を含みます）。

認証する

クライアントの設定後、再起動が必要な場合があります。Vantage OAuth のブラウザーウィンドウが開くので、サインインして Allow Access をクリックします。アクセスはいつでも Vantage Settings → API Access Tokens → MCP Server Token から取り消せます。

次のようなプロンプトを試してみてください：「Vantage で、どのワークスペースにアクセスできますか？」

---

セルフホスト（ローカル）MCP

OAuth を使わずに API キー認証が必要な場合、またはこのリポジトリを使って開発する場合は、セルフホストモードを使用します。

npm パッケージ（セルフホストにおすすめ）

インストールは不要です。公開済みパッケージを実行するように MCP クライアントを設定します。

{
  "mcpServers": {
    "Vantage": {
      "command": "npx",
      "args": ["-y", "vantage-mcp-server"],
      "env": {
        "VANTAGE_TOKEN": "<your_vantage_api_token>"
      }
    }
  }
}

Vantage コンソールでトークンを作成します。Node.js 20 以降が必要です。

このリポジトリから（コントリビューター向け）

MCP サーバー自体を開発する場合：

git clone https://github.com/vantage-sh/vantage-mcp-server
cd vantage-mcp-server
npm install

ローカルのエントリーポイントを実行するようにクライアントを設定します（<path_to_repository> と <personal_vantage_api_token> を置き換えてください）。

{
  "mcpServers": {
    "Vantage": {
      "command": "npx",
      "args": ["tsx", "<path_to_repository>/src/local.ts"],
      "env": { "VANTAGE_TOKEN": "<personal_vantage_api_token>" }
    }
  }
}

または、リポジトリにインストールされたバイナリを直接使用します。

{
  "mcpServers": {
    "Vantage": {
      "command": "<path_to_repository>/node_modules/.bin/tsx",
      "args": ["<path_to_repository>/src/local.ts"],
      "env": { "VANTAGE_TOKEN": "<personal_vantage_api_token>" }
    }
  }
}

ターミナルからテストするには、npm run local を実行します（環境に VANTAGE_TOKEN が必要です）。

---

ローカル開発

ホスト型ワーカーをローカルで開発するには：

cp .dev.vars.example .dev.vars.development
# Edit .dev.vars.development — set VANTAGE_MCP_TOKEN to your API token
npm run dev

Wrangler はワーカーを http://localhost:8787（デフォルト）で実行します。VANTAGE_MCP_TOKEN を設定すると、ローカルテストで OAuth をバイパスできます。

---

評価の実行

各ツールは、直接的なプロンプトと推論が必要なプロンプトをそれぞれ 1 つ使ってテストします。どちらの実行でも、対象ツールに加えて 4 つのダミーツールを読み込みます。その後、同じケースを複数のモデルで再実行できます。評価結果は JSON としてコミットするため、テスト一式をすべて再実行する必要はありません。GitHub Pages はこれらのファイルからレポートを再構築します。手法とワークフローの全容は evals.md をご覧ください。

新しいツールには、evals/cases/<resource>/<tool>.eval.ts にケースを用意する必要があります。作成規約については、.agents/skills/writing-evals/SKILL.md をご覧ください。

評価結果をローカルで表示する

npm run eval:site
open evals/site/index.html

モデルの API キーは不要です。公開されているレポートは https://vantage-sh.github.io/vantage-mcp-server/ にあります。

新しい評価を実行する

.env に ANTHROPIC_API_KEY および／または OPENAI_API_KEY を設定してから、次を実行します。

npm run eval -- --tool <your-tool> --model gpt-5.6-sol-high

--model は必須です（npm run eval -- --list-models を実行するとカタログが表示されます）。このコマンドは evals/results/<model>/<resource>/<tool>.json に書き込み、その他の結果ファイルには変更を加えません。新しい JSON をコミットしてください。

評価を上書きする

同じ --tool と --model を指定して再実行します。その組み合わせの JSON が置き換えられます。ツールの説明、スキーマ、またはプロンプトを変更した後に実行してください。ベースラインも更新したい場合を除き、すべてのモデルで再実行する必要はありません。

---

利用可能なスクリプト

• npm run dev — Wrangler 開発サーバーを起動
• npm run local — stdio MCP サーバーをローカルで実行
• npm run inspect — MCP インスペクターを起動
• npm run test — Vitest を実行
• npm run format / npm run lint:fix — Biome でフォーマットとリントを実行
• npm run type-check — TypeScript の型チェックを実行
• npm run cf-typegen — Cloudflare Worker の型を生成
• npm run generate-tools-index — ツールの変更後に src/tools/index.ts を再生成
• npm run generate-resources-index — リソースの変更後に src/resources/index.ts を再生成
• npm run eval — ツール選択の評価を実行（npm run eval -- --tool <name> --model gpt-5.6-sol-high）
• npm run eval:site — 保存済み JSON を統合し、evals/site/index.html に書き込み
• npm run eval:view — promptfoo のローカル結果ビューアーを開く

---

貢献ガイドライン

1. このリポジトリをフォークし、ブランチを作成します：git checkout -b feature/my-feature。
2. 変更を加えます。
3. ローカルで確認します：

   npm run format
   npm run lint:fix
   npm run type-check
   npm test -- --run
   

4. プルリクエストを送信します。

ツール、評価、またはリソースを追加する際の規約については、AGENTS.mdを参照してください。

---

ライセンス

商用および非商用のライセンスの詳細については、LICENSE.mdを参照してください。