Claude Code ガイド

Appearance

原文（日本語に翻訳） ​

コールバックポートがすでに使用中の場合にMCP OAuth認証がハングする問題を修正

原文（英語） ​

Fixed MCP OAuth authentication hanging when the callback port is already in use

概要 ​

MCP（Model Context Protocol）サーバーのOAuth認証プロセス中に、コールバック用のポートが別のプロセスによって既に使用されていた場合に認証処理がハング（無限待機）する問題が修正されました。修正後は、ポートが使用中の場合に適切なエラーメッセージが表示され、ユーザーが状況を把握して対処できるようになります。

基本的な使い方 ​

このバグ修正はユーザー操作不要で自動的に適用されます。MCP OAuth認証を使用している場合、ポート競合が発生した際に明確なエラーが表示されるようになります。

bash
# MCP サーバーの設定例
claude mcp add my-server --oauth

実践例 ​

ポート競合の確認と対処 ​

修正前はハングしていた状況で、修正後は明確なエラーが表示されます：

bash
# ポートの使用状況を確認
lsof -i :8080  # よく使われるOAuthコールバックポート
netstat -an | grep LISTEN | grep 808

# 使用中のプロセスを確認
lsof -ti:8080 | xargs kill -9  # 競合プロセスを終了（注意して実行）

MCP OAuth設定の確認 ​

bash
# 現在のMCP設定を確認
claude mcp list

# 特定のMCPサーバーの詳細を確認
claude mcp get my-server

OAuth認証フローの再実行 ​

ポート競合を解消した後：

bash
# MCPサーバーへの再認証
claude mcp auth my-server

# または設定をリセットして再設定
claude mcp remove my-server
claude mcp add my-server --oauth

開発環境でのポート管理 ​

複数のMCPサーバーを使用する場合のポート競合回避：

json
// .claude/mcp-settings.json
{
  "servers": {
    "server1": {
      "oauth": {
        "callbackPort": 8081
      }
    },
    "server2": {
      "oauth": {
        "callbackPort": 8082
      }
    }
  }
}

注意点 ​

  • このバグはOAuth認証を使用するMCPサーバーにのみ影響していました
  • 修正前にハングが発生した場合は、Ctrl+Cでプロセスを中断してポート競合を解消してください
  • CI/CD環境では特にポート競合が起きやすいため、適切なポート管理が重要です
  • VPN接続やDockerコンテナ使用時もポート競合が発生することがあります

関連情報 ​