MCPサーバーを構築する

このレッスンで学ぶこと

• ローカル（stdio）MCPサーバーを本格的な構成オプション込みで構築する手順
• リモート（HTTP）MCPサーバーの認証パターン（Bearerトークン、OAuth、事前設定済みクライアント）
• 環境変数・シークレットを安全に扱うための設計原則
• .mcp.jsonで複数サーバーを管理し、チームに展開するための構成パターン

前提条件

• Lesson 1「MCPの基礎」を修了していること（クライアント/サーバーモデル、stdio/HTTPの違いを理解している前提で進めます）
• GitHubアカウントなど、最低1つの外部サービスのアカウントがあると実践しやすくなります

実践レシピのMCPサーバーをローカル環境で設定するでは、Playwright MCPサーバーを例にした基本手順を扱いました。このレッスンでは、それを土台に実務で使うレベルの構成——複数サーバーの同時管理、認証パターンの使い分け、シークレットの安全な受け渡し——まで踏み込みます。

ローカル（stdio）サーバーの本格構築

スコープを意識して追加する

claude mcp addはデフォルトでlocalスコープ（自分専用・現在のプロジェクトのみ）に登録されます。実務では、用途に応じて3つのスコープを使い分けます。

# チームで共有するサーバーをproject scopeで追加
claude mcp add --transport http github --scope project \
  https://api.githubcopilot.com/mcp/ \
  --header "Authorization: Bearer ${GITHUB_TOKEN}"
 
# 個人的に全プロジェクトで使うサーバーをuser scopeで追加
claude mcp add --scope user playwright -- npx -y @playwright/mcp@latest

CLAUDE_PROJECT_DIRでプロジェクト相対パスを解決する

stdioサーバーには、起動時にCLAUDE_PROJECT_DIRという環境変数が自動的に設定されます。サーバー側のコードでprocess.env.CLAUDE_PROJECT_DIR（Node.js）やos.environ["CLAUDE_PROJECT_DIR"]（Python）を参照すれば、Claude Codeの実行時のカレントディレクトリに依存せず、プロジェクトルートを起点としたパス解決ができます。

.mcp.jsonのcommandやargsの中でこの変数を使う場合は、Claude Code自体の環境にはこの変数が設定されないため、デフォルト値を併記しておくのが安全です。

{
  "mcpServers": {
    "local-script": {
      "type": "stdio",
      "command": "node",
      "args": ["${CLAUDE_PROJECT_DIR:-.}/scripts/mcp-server.js"]
    }
  }
}

リモート（HTTP）サーバーの認証設定

パターン1: 静的トークンをヘッダーで渡す

個人アクセストークン（PAT）方式のサービスでは、--headerでAuthorizationヘッダーを直接指定します。

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

トークンをコマンドにベタ書きせず、シェルの環境変数を展開する形にしておくと、コマンド履歴にトークンの値そのものが残りません。

パターン2: OAuth 2.0によるブラウザ認証

GitHub・Slack・Sentryなど多くのSaaS連携は、OAuthフローによる認証をサポートしています。Claude Codeは401または403応答を受け取ると、そのサーバーを「認証が必要」として/mcpパネルにフラグを立てます。

claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

/mcp

claude mcp login sentry

パターン3: 事前設定済みOAuthクライアント

一部のサーバーは動的クライアント登録に対応しておらず、事前にOAuthアプリを登録してクライアントIDを払い出す必要があります。その場合は--client-id・--client-secret・--callback-portを組み合わせます。

claude mcp add --transport http my-server \
  --client-id YOUR_CLIENT_ID --client-secret --callback-port 8080 \
  https://mcp.example.com/mcp

--client-secretはマスクされた入力を求めるプロンプトになるため、シェル履歴にシークレットが残りません。

環境変数・シークレット管理のベストプラクティス

.mcp.jsonでの変数展開

.mcp.jsonは${VAR}構文での環境変数展開をサポートしています。これにより、設定ファイル自体はチームで共有しつつ、各メンバーのマシン固有の値（APIキーなど）は環境変数側に分離できます。

{
  "mcpServers": {
    "database": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@bytebase/dbhub", "--dsn", "${DATABASE_URL}"]
    },
    "api-server": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": {
        "Authorization": "Bearer ${API_KEY}"
      }
    }
  }
}

${VAR:-default}の形式でデフォルト値を指定できるため、変数が未設定でも動作させたいケースとそうでないケースを使い分けられます。必須の値（APIキー等）はデフォルトを与えず、未設定時にエラーで気づけるようにしておくのが安全です。

守るべき3原則

データベース接続のように、誤操作の被害が大きい接続先では、読み取り専用ユーザーを使うことも徹底しましょう。

# 本番DBへの接続は読み取り専用ユーザーで
claude mcp add --transport stdio database -- \
  npx -y @bytebase/dbhub \
  --dsn "${DATABASE_URL}"

# チームメンバーは各自の環境でシークレットを設定
export DATABASE_URL="postgresql://readonly_user:password@db.example.com:5432/app"
export GITHUB_TOKEN="ghp_xxxxx"

複数MCPサーバーの管理: .mcp.jsonの構成パターン

実務では複数のMCPサーバーを同時に使うことが普通になります。.mcp.jsonに複数のエントリをまとめておくことで、プロジェクトを開いた瞬間にチーム全員が同じツールセットを使える状態を作れます。

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": {
        "Authorization": "Bearer ${GITHUB_TOKEN}"
      }
    },
    "database": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@bytebase/dbhub", "--dsn", "${DATABASE_URL}"]
    },
    "playwright": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"]
    },
    "internal-docs": {
      "type": "http",
      "url": "https://mcp.internal.example.com",
      "headersHelper": "${CLAUDE_PROJECT_DIR:-.}/scripts/get-auth-headers.sh"
    }
  }
}

最後のinternal-docsの例のように、OAuthでも静的トークンでもない独自の認証方式（社内SSO等）を使うサーバーには、headersHelperでヘッダー生成コマンドを指定できます。Claude Codeは接続のたびにこのコマンドを実行し、その標準出力（JSON）をヘッダーとしてマージします。

{
  "mcpServers": {
    "internal-api": {
      "type": "http",
      "url": "https://mcp.internal.example.com",
      "headersHelper": "echo '{\"Authorization\": \"Bearer '\"$(get-token)\"'\"}'"
    }
  }
}

スコープが重複した場合の優先順位

同じ名前のサーバーが複数のスコープで定義されている場合、Claude Codeは以下の優先順位で1つだけを採用します（フィールドのマージは行われません）。

graph LR
    A["local scope"] -->|最優先| Z["採用される定義"]
    B["project scope"] -.->|localがなければ| Z
    C["user scope"] -.->|project/localがなければ| Z
    D["プラグイン提供"] -.->|それ以外がなければ| Z
 
    style A fill:#e8f4fd,stroke:#1a73e8
    style Z fill:#fff3e0,stroke:#e65100

動作確認とチームへの展開

claude mcp list

/mcp

git add .mcp.json
git commit -m "MCPサーバー構成を追加"

よくある質問

Q. .mcp.jsonを編集してもセッション内に反映されません

Claude Codeはセッション開始時に.mcp.jsonを読み込みます。ファイルを編集した後は、セッションを再起動してください。それでも反映されない場合は/mcpで解析エラーが出ていないか確認します。

Q. 一度拒否したプロジェクトスコープのサーバーを再承認させたい

claude mcp reset-project-choicesで、プロジェクト単位の承認状態をリセットできます。

まとめ

• ローカルサーバーはlocal/project/userのスコープを用途に応じて選び、CLAUDE_PROJECT_DIRでプロジェクト相対パスを解決する
• リモートサーバーの認証は「静的トークン → OAuth → 事前設定済みクライアント」の優先順位で検討するとスムーズ
• シークレットは.mcp.jsonに直書きせず${VAR}展開で分離し、コミット前に必ず混入チェックを行う
• 複数サーバーは.mcp.jsonに集約し、スコープの優先順位（local > project > user > プラグイン）を理解しておく

次のステップ

既存のMCPサーバーを構築・運用できるようになったら、次は「自分たちのドメインに合わせたMCPサーバーを作る」段階に進みます。Lesson 3では、カスタムMCPツールの設計から実装、テスト・デバッグまでを扱います。