Antigravity MCP 接続エラー完全トラブルシューティングガイド

Antigravity で MCP（Model Context Protocol）を利用する際、接続エラーに直面することは珍しくありません。ここで接続に関する主要なトラブルの原因特定と解決方法を、段階的に解説します。

MCP接続の基本的な仕組み

MCP は、AI と外部ツール（GitHub、Figma、カスタムサーバー等）を接続するプロトコルです。Antigravity では、複数の MCP サーバーを同時に管理し、エージェントが必要に応じてそれらの機能を呼び出します。

接続の流れ：

MCP サーバーが起動（Node.js プロセス）
Antigravity がそのサーバーに接続を試行
JSON-RPC 通信で初期化メッセージを交換
エージェントがサーバーの機能を利用可能に

この流れで障害が発生すると、一連の接続エラーが生じます。

MCPサーバーが起動しない場合の対処法

1. Node.js バージョンの確認

MCP サーバーの多くは Node.js 16 以上を必要とします。Antigravity Builder で「Server Failed to Start」というエラーが表示された場合、まずは Node.js のバージョンを確認してください。

# Node.js バージョン確認
node --version
 
# 推奨バージョン: v18 以上
# v16 の場合は npm-upgrade を検討

古いバージョンの場合：

Node.js 公式サイトから最新版をダウンロード
Antigravity を再起動（Cmd+Q で完全終了後、再実行）
MCP サーバーの再接続を試行

2. 設定ファイル（JSON）の書式エラー

MCP サーバーは、~/.antigravity/mcp_servers.json または mcp.json で定義されます。JSON の書式エラーはサーバー起動を即座に中断します。

// ✅ 正しい形式の例
{
  "servers": {
    "github": {
      "command": "node",
      "args": ["~/.antigravity/mcp-github/index.js"],
      "env": {
        "GITHUB_TOKEN": "YOUR_GITHUB_TOKEN"
      }
    }
  }
}
 
// ❌ よくあるエラー
// - 末尾のカンマ: "args": ["..."],  ← カンマがあるとNG
// - シングルクォーテーション使用: 'command' ← ダブルクォーテーション必須
// - 環境変数未設定: GITHUB_TOKEN を設定せずにサーバー起動

デバッグ手順:

テキストエディタで mcp.json を開く
オンラインの JSON バリデーター（例: jsonlint.com）にコピー & ペースト
エラーメッセージに従って修正
Antigravity を再起動

3. ポート競合の問題

複数の MCP サーバーが同じポートを使用しようとすると、接続に失敗します。特に、ローカル環境で複数プロジェクトを同時に開いている場合に発生しやすい問題です。

# ポート使用状況の確認（macOS/Linux）
lsof -i :3000
 
# Windows の場合
netstat -ano | findstr :3000
 
# 出力例: 別プロセスがポート3000を使用している場合
# node    12345  user   20u  IPv4  0x...  0t0  TCP *:3000 (LISTEN)

解決方法:

不要なプロセスを終了：kill -9 <PID>
または、別のポートを使用するよう MCP 設定を変更
Antigravity 設定で MCP サーバーのポート番号を明示的に指定

MCPBuilderでの接続エラー

Antigravity Builder インターフェース上で「Connection Failed」と表示される場合：

接続タイムアウト（30秒以上待機）: MCP サーバーの起動が遅延しています。サーバーのスペック確認、または初期化処理の見直し
認証エラー: API キーやトークンが無効。次のセクション「認証関連のトラブル」を参照
バージョン不一致: Builder が古いバージョンの MCP プロトコルに対応していない場合、Antigravity 自体をアップデート

認証関連のトラブル

APIキーの有効期限確認

GitHub、Figma、Google などの外部 API を利用する場合、トークンの有効期限が過ぎている可能性があります。

GitHub Personal Access Token: 2年で自動失効
Figma API Token: 有効期限あり（2年以上持続する場合もある）
Google OAuth Token: リフレッシュトークンの有効期限は6ヶ月

確認と再発行:

認証プロバイダ（GitHub Settings → Developer settings など）でトークンを確認
有効期限を確認し、期限切れの場合は再発行
mcp.json の env.{TOKEN_NAME} を新しい値に更新
Antigravity を再起動

環境変数の設定漏れ

mcp.json で "env" フィールドを指定していても、実際の値が設定されていない場合があります。

// ❌ 環境変数の値が定義されていない
{
  "env": {
    "GITHUB_TOKEN": ""  // 空文字列
  }
}
 
// ✅ 正しい設定
{
  "env": {
    "GITHUB_TOKEN": "ghp_..."  // 実際のトークンを設定
  }
}

環境変数をシェルで一度に設定している場合は、Antigravity を起動する前にシェルで確認：

echo $GITHUB_TOKEN
echo $FIGMA_TOKEN

空文字列が表示される場合、.bashrc / .zshrc で定義を追加してください。

Figma MCP・GitHub MCP での個別エラー

Figma MCP: "Invalid file permission" エラー

Figma API トークンは、特定のファイルへのアクセス権限を持たない場合があります。

解決方法:

Figma チーム設定で、トークンの権限を確認
必要に応じて、トークン再生成時に「Files」の権限を追加
MCP サーバーが複数ファイルにアクセスする場合は、全ファイルへの権限を確認

GitHub MCP: "Rate limit exceeded" エラー

GitHub API は、認証なしで時間あたり60リクエスト、認証ありで5,000リクエストの制限があります。大量の repository 操作や issue 検索を実行している場合、この制限に達する可能性があります。

対処法:

GitHub API の使用状況を確認：curl -H "Authorization: token YOUR_GITHUB_TOKEN" https://api.github.com/rate_limit
レート制限が近い場合は、数時間待機してから再試行
不要な API 呼び出しを削減する設定を検討

InForge連携時の注意点

Antigravity から InForge（アプリビルド環境）に MCP を連携させる場合、いくつかの制約があります。

ファイルシステムアクセス: InForge 内の MCP は、サンドボックス外のファイルにアクセスできない場合がある
環境変数の隔離: InForge 内では独立した環境変数空間を使用。デスクトップ版 Antigravity の設定がそのまま引き継がれない
ネットワークアクセス: 一部の企業ネットワーク環境では、InForge から外部 API へのアクセスが制限される

InForge での MCP 接続手順:

InForge のプロジェクト設定で「MCP Configuration」を開く
各 MCP サーバーの認証情報（API キーなど）を改めて入力
「Test Connection」をクリックして動作確認
エラーが表示された場合は、ネットワーク管理者にファイアウォール設定を確認してもらう

MCP接続のデバッグ手順

ステップ1: ログの確認

Antigravity は詳細なログを出力しています。デバッグモードで起動して、エラー箇所を特定します。

# デバッグモードで起動（Antigravity が CLI の場合）
ANTIGRAVITY_DEBUG=1 antigravity
 
# または、Antigravity 内部メニュー: View → Logs（デスクトップ版）

ログに以下の情報が含まれていないか確認：

MCP server startup failed
Connection timeout
Invalid credentials
ECONNREFUSED または EADDRINUSE

ステップ2: MCP サーバーの手動テスト

MCP サーバーが単体で起動可能か確認します。

# MCP サーバーが Node.js スクリプトの場合
cd ~/.antigravity/mcp-github
node index.js
 
# 成功時の出力例:
# MCP Server listening on port 3001
# Ready to accept connections
 
# エラーが表示された場合は、スタックトレースをメモ

ステップ3: 接続テストスクリプト

以下のスクリプトを実行して、MCP サーバーが正常に応答するか確認：

// test_mcp_connection.js
const net = require('net');
 
const SERVER_HOST = 'localhost';
const SERVER_PORT = 3001; // MCP サーバーのポート
 
const client = net.createConnection(SERVER_PORT, SERVER_HOST, () => {
  console.log(`✅ MCP サーバーに接続成功: ${SERVER_HOST}:${SERVER_PORT}`);
 
  // JSON-RPC 初期化メッセージを送信
  const initMessage = {
    jsonrpc: "2.0",
    id: 1,
    method: "initialize",
    params: {
      protocolVersion: "2024-11-05"
    }
  };
 
  client.write(JSON.stringify(initMessage) + '\n');
});
 
client.on('data', (data) => {
  console.log(`📨 サーバーからのレスポンス:\n${data.toString()}`);
  client.destroy();
});
 
client.on('error', (err) => {
  console.error(`❌ 接続エラー: ${err.message}`);
  console.error(`詳細: ${err.code}`);
});
 
client.setTimeout(5000, () => {
  console.error('❌ タイムアウト: サーバーが応答しません（5秒以内）');
  client.destroy();
});

実行方法：

node test_mcp_connection.js

Antigravity MCP サーバー構築ガイドでは、カスタム MCP サーバーをゼロから構築するプロセスを解説しています。

Antigravity MCP Store 活用ガイドでは、公開 MCP サーバーの検索と導入方法を紹介しています。

Figma × Antigravity フロントエンド開発ガイドでは、Figma MCP を使ったデザイン連携の実践例を掲載しています。

全体を振り返って

MCP 接続エラーの大部分は、以下のいずれかです：

Node.js バージョンの不一致
JSON 設定の書式エラー
APIキーやトークンの無効化・期限切れ
ポート競合
ネットワーク・ファイアウォール制限

ログを確認し、デバッグスクリプトで単体テストを実行することで、問題の箇所を迅速に特定できます。Antigravity と MCP の組み合わせは強力ですが、初期設定の段階での丁寧なトラブルシューティングが、その後の円滑な運用を左右します。