基本設定ガイド

Hatago MCP Hubの設定ファイル（hatago.config.json）を作成し、カスタマイズする方法を説明します。

📝 設定ファイルの作成

自動生成（推奨）

対話型コマンドで簡単に作成：

npx @himorishige/hatago-mcp-hub init

プロンプトに従って選択するだけで、適切な設定ファイルが生成されます。

手動作成

hatago.config.jsonを作成：

{
  "$schema": "https://raw.githubusercontent.com/himorishige/hatago-hub/main/schemas/config.schema.json",
  "version": 1,
  "logLevel": "info",
  "mcpServers": {
    // サーバー設定をここに追加
  }
}

🏗️ 基本構造

設定ファイルは以下の要素で構成されています：

{
  "$schema": "...", // JSON Schema（自動補完用）
  "version": 1, // 設定フォーマットバージョン
  "logLevel": "info", // ログレベル
  "mcpServers": {
    // MCPサーバーの定義
    "server-id": {
      // サーバーID（任意の名前）
      // サーバー設定
    }
  }
}

ヒント

VS Codeを使用している場合、$schemaフィールドにより自動補完とバリデーションが有効になります。

🚀 サーバータイプ別の設定

ローカルサーバー

ローカルマシンで実行するMCPサーバー：

{
  "mcpServers": {
    "my-local-server": {
      "command": "node",
      "args": ["./my-server.js"],
      "env": {
        "NODE_ENV": "production"
      },
      "cwd": "./servers"
    }
  }
}

NPXサーバー

npmパッケージとして公開されているMCPサーバー：

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
      "env": {
        "LOG_LEVEL": "debug"
      }
    }
  }
}

注意

-yフラグは、npmパッケージを自動的にダウンロードするために必要です。

リモートサーバー

HTTPまたはSSE経由で接続するサーバー：

{
  "mcpServers": {
    "remote-api": {
      "url": "https://api.example.com/mcp",
      "type": "http",
      "headers": {
        "Authorization": "Bearer ${API_TOKEN}"
      }
    },
    "deepwiki": {
      "url": "https://mcp.deepwiki.com/sse",
      "type": "sse"
    }
  }
}

🔑 環境変数の使用

基本的な展開

環境変数は${VAR}形式で参照できます：

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

デフォルト値の指定

環境変数が未定義の場合のデフォルト値：

{
  "env": {
    "API_URL": "${API_URL:-https://api.example.com}",
    "LOG_LEVEL": "${LOG_LEVEL:-info}",
    "TIMEOUT": "${TIMEOUT_MS:-30000}"
  }
}

必須変数

"${GITHUB_TOKEN}"

未定義の場合はエラー

オプション変数

"${PORT:-3000}"

未定義なら3000を使用

🏷️ タグベースの管理

サーバーをグループ化して管理：

{
  "mcpServers": {
    "dev-tools": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "."],
      "tags": ["development", "local"]
    },
    "prod-api": {
      "url": "https://api.production.com/mcp",
      "tags": ["production", "remote"]
    },
    "shared-db": {
      "command": "mcp-postgres",
      "tags": ["development", "production", "database"]
    }
  }
}

起動時にタグで絞り込み：

# 開発環境のサーバーのみ起動
hatago serve --tags development

# 複数タグ（OR条件）
hatago serve --tags development,local

📚 実用的な設定例

開発環境の設定

フルスタック開発環境の例

{
  "$schema": "https://raw.githubusercontent.com/himorishige/hatago-hub/main/schemas/config.schema.json",
  "version": 1,
  "logLevel": "debug",
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "."],
      "tags": ["essential", "dev"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      },
      "tags": ["vcs", "dev"]
    },
    "database": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "DATABASE_URL": "${DATABASE_URL:-postgresql://localhost/dev}"
      },
      "tags": ["database", "dev"]
    },
    "memory": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"],
      "tags": ["cache", "dev"]
    }
  }
}

チーム共有設定

チーム開発用の設定

{
  "version": 1,
  "logLevel": "${LOG_LEVEL:-info}",
  "mcpServers": {
    "shared-docs": {
      "url": "${TEAM_DOCS_URL}",
      "type": "http",
      "headers": {
        "X-Team-ID": "${TEAM_ID}",
        "Authorization": "Bearer ${TEAM_TOKEN}"
      },
      "tags": ["team", "documentation"]
    },
    "project-fs": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "${PROJECT_ROOT:-.}"],
      "tags": ["team", "essential"]
    },
    "ci-tools": {
      "url": "${CI_MCP_ENDPOINT:-https://ci.example.com/mcp}",
      "type": "sse",
      "disabled": "${DISABLE_CI:-false}",
      "tags": ["team", "ci"]
    }
  }
}

🔧 設定のベストプラクティス

1. 明確なサーバーID

   ✅ "github-api", "local-filesystem", "prod-database"
   ❌ "server1", "srv", "test"

2. 環境変数にデフォルト値

   {
     "DATABASE_URL": "${DATABASE_URL:-postgresql://localhost/dev}"
   }

3. タグで整理

   {
     "tags": ["環境", "用途", "重要度"]
   }

4. 不要なサーバーは無効化

   {
     "disabled": true
   }

5. ログレベルは環境ごとに

   {
     "logLevel": "${LOG_LEVEL:-info}"
   }

⚙️ 設定の検証

構文チェック

# JSONの妥当性確認
cat hatago.config.json | jq .

# スキーマバリデーション（VS Code）
# $schemaフィールドで自動的に検証

設定のテスト

# 詳細ログで確認（Ctrl+C で停止）
hatago serve --stdio --config ./hatago.config.json --verbose

🔄 ホットリロード

設定ファイルの変更を自動的に反映：

hatago serve --watch

変更が検出されると：

1. 新しい設定を読み込み
2. サーバーを再接続
3. クライアントに通知

ヒント

開発中は--watchフラグを常に使用することをお勧めします。

📖 関連ドキュメント

設定の継承

複数の設定ファイルを組み合わせる

リモートサーバー

HTTPやSSEサーバーとの接続

タグフィルタリング

環境ごとのサーバー管理

設定リファレンス

すべての設定オプション

---

ノート

完全な設定オプションについては、設定リファレンスをご覧ください。