TestOptim

TestOptim MCP サーバー

Claude Code、Cursor、VS Code などの MCP クライアントをTestOptimに接続すると、AI アシスタントでウェブアプリの QA テストを実行し、見つかった問題を確認できます。

「プロジェクトで QA テスト一式を実行して、重大な問題を表示してください。」

サーバーは TestOptim がホストしているため、インストールや起動は不要です。このリポジトリには、セットアップ手順、すぐにコピーできるクライアント設定、および MCP レジストリにサーバーを登録するserver.jsonが含まれています。

• エンドポイント： https://api.testoptim.com/api/mcp
• トランスポート： Streamable HTTP（ステートレス、POST のみ）
• 認証： Authorization: Bearer topt_... で送信する TestOptim API キー

目次

• 始める前に
• API キーを作成する
• クライアントを接続する
• ツール
• プロンプトの例
• セキュリティ
• 制限とエラー
• トラブルシューティング

始める前に

• テストケースを少なくとも1つ生成済みのプロジェクトがある TestOptim アカウント。テストケースを生成するを参照してください。
• API キーを作成するための、組織内のオーナーまたは管理者のロール。
• MCP 経由で開始した実行には、アプリから開始した実行と同様に、プランのテスト実行回数が使用されます。実行はキーを作成したユーザーに紐づけられます。

API キーを作成する

1. TestOptim で設定を開き、API キーを選択してから、新しいトークンを選択します。
2. Claude Code - laptop のように、わかりやすい名前を付けます。
3. プロジェクトへのアクセスで、すべてのプロジェクトまたは単一のプロジェクトを選択します。単一のプロジェクトを選択すると、キーが漏洩した場合にアクセスできる範囲を限定できます。
4. 必要な権限だけを有効にします（各ツールに必要な権限はツールを参照してください）。
5. トークンをコピーします。トークンは topt_ で始まり、一度だけ表示されます。

その後、クライアントの起動元となるシェルでエクスポートし、設定ファイルに保存されないようにします。

export TESTOPTIM_TOKEN="topt_..."

スクリーンショット付きの詳しいガイドは、API キーを使って CI から TestOptim のテストを実行するをご覧ください。

代わりに GitHub Actions ワークフローからテストを実行する場合は、TestOptim Run Testsを使用してください。

クライアントを接続する

各設定例はexamples/にもあります。

Claude Code

claude mcp add --transport http testoptim https://api.testoptim.com/api/mcp \
  --header "Authorization: Bearer ${TESTOPTIM_TOKEN}"

この設定では、トークンがローカルの Claude Code 設定に保存されます。すべてのプロジェクトで使用するには、--scope user を追加します。

トークンを共有せずにチームでサーバーを共有するには、プロジェクトの .mcp.json をコミットします。Claude Code は各ユーザーの環境から ${TESTOPTIM_TOKEN} を展開します（examples/claude-code.mcp.json）。

{
  "mcpServers": {
    "testoptim": {
      "type": "http",
      "url": "https://api.testoptim.com/api/mcp",
      "headers": {
        "Authorization": "Bearer ${TESTOPTIM_TOKEN}"
      }
    }
  }
}

Cursor

~/.cursor/mcp.json またはプロジェクト内の .cursor/mcp.json に追加します（examples/cursor.mcp.json）。

{
  "mcpServers": {
    "testoptim": {
      "url": "https://api.testoptim.com/api/mcp",
      "headers": {
        "Authorization": "Bearer ${env:TESTOPTIM_TOKEN}"
      }
    }
  }
}

Cursor はシェルまたはシステム環境から TESTOPTIM_TOKEN を読み取ります。リモートサーバーでは envFile はサポートされていません。

VS Code

ワークスペース内の .vscode/mcp.json に追加するか、各ワークスペースでMCP: Open User Configurationを実行します（examples/vscode.mcp.json）。VS Code はサーバーの初回起動時にキーの入力を求め、安全に保存します。

{
  "inputs": [
    {
      "type": "promptString",
      "id": "testoptim-token",
      "description": "TestOptim API key (starts with topt_)",
      "password": true
    }
  ],
  "servers": {
    "testoptim": {
      "type": "http",
      "url": "https://api.testoptim.com/api/mcp",
      "headers": {
        "Authorization": "Bearer ${input:testoptim-token}"
      }
    }
  }
}

Windsurf

MCP 設定ファイルに追加します（Cascade の MCP 設定から開きます）。リモートサーバーでは serverUrl を使用します（examples/windsurf.mcp_config.json）。

{
  "mcpServers": {
    "testoptim": {
      "serverUrl": "https://api.testoptim.com/api/mcp",
      "headers": {
        "Authorization": "Bearer ${env:TESTOPTIM_TOKEN}"
      }
    }
  }
}

Claude（claude.ai および Claude Desktop）

TestOptim をカスタムコネクターとして追加します。

1. カスタマイズ > コネクター を開き、+ 追加、次に カスタムコネクターを追加 を選択します。
2. TestOptim という名前を付け、サーバー URL に https://api.testoptim.com/api/mcp を入力します。
3. 認証 で サインインしない を選択します。
4. リクエストヘッダー で、Authorization を追加し、値に Bearer topt_...（ご自身のキー）を入力します。
5. 追加 を選択します。

Team プランと Enterprise プランでは、オーナーが 組織の設定 > コネクター から追加します。また、コネクターを使う全員が、1 つのキーを共有します。1 つのプロジェクトに制限したキーを使用し、すべてのメンバーがテストの実行を開始できる必要がない限り、tests:run は含めないでください。Claude のリサーチモードでは、事前の確認なしにコネクターツールを呼び出せるため、共有キーの書き込み権限をオフにしておく理由がもう 1 つあります。後でキーを変更するには、コネクターを削除して、もう一度追加します。

その他のクライアント

カスタムヘッダー付きの Streamable HTTP をサポートするクライアントであれば、どれでも使用できます。https://api.testoptim.com/api/mcp を指定し、すべてのリクエストに Authorization: Bearer <your key> を送信してください。サーバーはステートレスです。セッション ID は発行せず、GET と DELETE には 405 を返します。

ツール

サーバーには、キーの権限で許可されているツールのみが一覧表示されるため、読み取り専用のキーでは start_test_run は表示されません。

ツール	権限	機能	引数
list_projects	projects:read	キーでアクセスできるプロジェクトを一覧表示し、他のツールで必要になるプロジェクト ID を確認します。	なし
start_test_run	tests:run	テスト実行を開始し、実行 ID を返します。変更したページまたはフローのみを再テストするには changedAreas を渡します。テストスイート全体を実行するには、省略します。実行には数分かかります。	projectId、changedAreas（例：["/checkout", "/cart"]、任意）
get_test_run	tests:read	実行のステータス（pending、running、completed、failed）、進捗、現在のステップ、重大度別の問題数を表示します。	testRunId
stop_test_run	tests:run	実行中のテストを停止します。以降のテストケースは実行されず、課金もされません。停止した実行は failed として報告されます。	testRunId
list_issues	issues:read	プロジェクトの問題を、ID、タイトル、重大度、カテゴリ、ステータスの要約として一覧表示します。特定の実行で見つかった問題のみを表示するには、testRunId を渡します。	projectId、severity（critical、high、medium、low のいずれか。任意）、testRunId（任意）、limit（1～100、既定値は 20）
get_issue	issues:read	1 件の問題の詳細（説明、再現手順、期待される動作と実際の動作、ページ URL、スクリーンショット）を取得します。	issueId
start_exploration	knowledge:explore	プロジェクトのアプリを探索し、TestOptim に新しいページや変更されたページ、フローを学習させます。プランのページ利用枠を消費し、実行中の探索があれば置き換えます。探索 ID を返します。	projectId
get_exploration	projects:read	探索のステータスと進捗を表示し、終了後には記録されたページ、フロー、エンティティの数も表示します。waiting_otp_ready または waiting_otp は、TestOptim アプリでログイン用のワンタイムコードを入力する必要があることを示します。	explorationId

結果は JSON テキストで返され、TestOptim API と同じフィールド名が使用されます。

プロンプトの例

• 「アクセスできる TestOptim のプロジェクトを教えてください。」
• 「checkout プロジェクトで QA スイートを実行し、完了したら教えてください。」
• 「プロジェクトの重大および高の問題を一覧表示してから、最初の問題の再現手順を表示してください。」
• 「サインアップフォームを変更しました。テストを実行し、失敗があれば問題を開いてコードを修正してください。」
• 「/checkout を変更しました。TestOptim でその部分だけを再テストし、重大な問題があれば修正してください。」
• 「設定ページを追加しました。TestOptim がそのページを認識できるよう、アプリをもう一度探索してください。」
• 「開始したテスト実行を停止してください。間違ったプロジェクトで実行しています。」

セキュリティ

• 最小権限。 クライアントごと、マシンごとに個別のキーを作成し、1 つのプロジェクトと必要な権限のみに制限してください。tests:run のないキーでは、実行を開始または停止できません。
• プロジェクト限定キーは、他のプロジェクトでは拒否されます。また、ツールに他の組織のデータが表示されることはありません。
• コミットするファイルにキーを含めないでください。 上記の環境変数または入力プロンプトの方法を使用してください。キーは topt_ で始まるため、ログやリポジトリで簡単に検索できます。
• キーが漏えいした場合やデバイスを紛失した場合は、Settings > API keys でキーを失効させてください。キーは直ちに使用できなくなります。
• tests:run を持つアシスタントは、プランのテスト実行回数を消費する実行を開始できます。ほとんどのクライアントでは、ツールを呼び出す前に確認を求められます。その確認は有効にしておいてください。

制限とエラー

• クライアントの IP アドレスごとに毎分 120 リクエストです。TestOptim REST API と共有されます。
• 1 つのプロジェクトで同時に実行できるジョブは 1 つです。同じプロジェクトで別のジョブが進行中に実行を開始すると拒否されるため、ジョブの完了を待ってから再試行してください。
• アプリの Run all と同様に、実行は残りのテスト実行回数に合わせて調整されます。すべてのテストスイートが必要な場合は、実行の totalCases を確認してください。

トラブルシューティング

症状	原因
401 Missing API token	Authorization ヘッダーが届いていません。クライアントを起動するシェルで環境変数が設定されていることを確認し、クライアントを再起動してください。
401 Invalid API token	キーが間違っているか、失効済み、または有効期限切れです。新しいキーを作成してください。
予期しているツールが見つからない	キーにそのツールの権限がありません。その権限を持つキーを作成してください。
This token is restricted to a different project	キーは 1 つのプロジェクトに限定されています。そのプロジェクトの ID、またはすべてのプロジェクトに使えるキーを使用してください。
405 Method not allowed	GET または DELETE が送信されました。サーバーが受け付けるのは POST のみです。Streamable HTTP に対応したクライアントを使用してください。

コントリビューション

クライアント設定が古くなっていることに気づいた場合や、別のクライアント用の設定を追加したい場合は、CONTRIBUTING.md をご覧ください。アカウントや TestOptim サービス自体に関する問題は、代わりに TestOptim サポートまでお問い合わせください。

ライセンス

MIT