Claude Code でリモート MCP サーバーに OAuth ログインする手順:/mcp と claude mcp login

Sentry や Linear、Notion のようなホスト型の MCP サーバーは、URL を登録しただけでは使えません。ブラウザでのサインインが要ります。claude mcp list に ! Needs authentication と出るのがその状態です。

結論として、claude mcp add --transport http <名前> <URL> で追加したあと、セッション内で /mcp を開いてサーバーを選び Authenticate を実行するか、シェルから claude mcp login <名前> を実行します。トークンは安全に保存され、自動で更新されます。

この記事はシリーズの一部です。サーバーの追加方法全体は Claude Code に MCP サーバーを追加する方法 を参照してください。

サーバーを追加して /mcp でサインインする

まず HTTP トランスポートでサーバーを登録します。公式ドキュメントは Sentry を例にしています。

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

追加した直後は claude mcp list に ! Needs authentication と表示されます。これは想定どおりで、次のサインインで解消します。

セッションを開始して /mcp を実行し、一覧から対象のサーバーを選んで Enter を押し、Authenticate を選びます。ブラウザがサービスのログイン画面を開くので、そこで接続を承認します。Claude Code 側の表示が connected に変われば完了です。

Claude Code は、サーバーが 401 Unauthorized または 403 Forbidden を返したときに「認証が必要」と判定します。起動時にも、サインインが必要なサーバーがある旨の通知が出ます(この通知は v2.1.193 以降です)。

コマンドラインからサインインする

セッションを開かずにサインインしたい場合は claude mcp login を使います。

claude mcp login sentry

保存済みの認証情報を消すには claude mcp logout <名前> です。

SSH 越しの作業や、ディスプレイサーバーのない Linux では、このコマンドはローカルにブラウザがないことを検出し、ブラウザを開く代わりに認可 URL を表示します。手元の端末でその URL を開き、認証後にアドレスバーのリダイレクト URL 全体をプロンプトに貼り戻します。貼り付けの手順に対話端末が必要なので、ssh -t で接続してください。ブラウザがあっても URL 表示に固定したい場合は --no-browser を付けます。

claude mcp login sentry --no-browser

claude -p や Agent SDK の非対話実行には /mcp パネルがないため、Claude Code は OAuth フローを実行できません。v2.1.196 以降は、ツール検索が有効な場合にかぎり「そのサーバーのツールは認可されるまで使えない」と Claude に伝えられます。サインイン自体は対話セッションの /mcp か claude mcp login で済ませておく必要があります。

事前登録した OAuth 情報を使う

サーバーが動的クライアント登録に対応していないと、「Incompatible auth server: does not support dynamic client registration」のようなエラーが出ます。この場合はサービスの開発者ポータルで OAuth アプリを登録し、その情報を渡します。

リダイレクト URI を登録する必要があるサーバーでは、ポートを 1 つ決めて http://localhost:PORT/callback の形式で登録し、同じポートを --callback-port に指定します。既定では Claude Code が空いているポートをランダムに選ぶため、固定しないと一致しません。

フラグ / キー	役割
--callback-port <ポート>	コールバックのポートを固定する。単独でも使える
--client-id <ID>	登録した OAuth アプリのクライアント ID
--client-secret	クライアントシークレットを伏せ字で入力させる
MCP_CLIENT_SECRET	環境変数でシークレットを渡し、対話入力を省く

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

JSON で書く場合は oauth オブジェクトを使います。シークレットは JSON には入れず、--client-secret フラグで別に渡します。

claude mcp add-json my-server \
  '{"type":"http","url":"https://mcp.example.com/mcp","oauth":{"clientId":"your-client-id","callbackPort":8080}}' \
  --client-secret

oauth には、リクエストするスコープを固定する scopes(RFC 6749 の形式に合わせた空白区切りの 1 つの文字列)と、メタデータの探索先を指定する authServerMetadataUrl も書けます。

{
  "mcpServers": {
    "slack": {
      "type": "http",
      "url": "https://mcp.slack.com/mcp",
      "oauth": {
        "scopes": "channels:read chat:write search:read"
      }
    }
  }
}

oauth.scopes は authServerMetadataUrl よりも、/.well-known で見つかるスコープよりも優先されます。認可サーバーが offline_access を公表している場合は、ブラウザでの再サインインなしにトークンを更新できるよう、Claude Code がそれを追加します。

スコープごとの設定ファイルの違いは claude mcp add の --scope local / project / user の違い に、静的なトークンをヘッダーで渡す方法は .mcp.json で環境変数からトークンを渡す書き方 にまとめています。

サインインが切れたとき・失敗したとき

すでにサインイン済みのサーバーへのリクエストが 401 を返した場合、Claude Code は保存済みトークンを更新し、再接続してリクエストを 1 回だけ再試行します。/mcp で「要認証」と表示されるのは、その再試行も失敗したときだけです。

リフレッシュトークン自体が拒否された場合は、/mcp を案内する通知がすぐに出ます。/mcp を開き、そのサーバーの Re-authenticate を選んでサインインし直してください。

症状	対処
ブラウザが自動で開かない	表示された URL をコピーして手動で開く
認証後にリダイレクトが接続エラーになる	アドレスバーのコールバック URL 全体を、Claude Code に出る URL プロンプトに貼り付ける
Authorization ヘッダーを設定したサーバーが 401・403	OAuth には切り替わらず接続失敗として報告される。トークンの有効性を確認するか、ヘッダーを外して OAuth を使う
権限が足りないと言われる(403 insufficient_scope)	サーバーが求めるスコープが oauth.scopes に無ければ追加し、/mcp から再度サインインする

最後の項目は間違えやすい点です。Claude Code は固定した oauth.scopes をそのまま要求するため、足りないスコープを追加せずにサインインし直しても、取得できるトークンにはそのスコープが含まれません。

なお、OAuth のアクセストークンとリフレッシュトークンがディスク上のどのパスに保存されるかは、公式ドキュメントでは確認できませんでした。ドキュメントには「安全に保存され、自動で更新される」とあり、クライアントシークレットについてのみ「macOS のキーチェーンか認証情報ファイル」と書かれています。

まとめ

• claude mcp add --transport http <名前> <URL> で追加し、/mcp の Authenticate かシェルの claude mcp login <名前> でサインインする
• claude mcp logout <名前> と /mcp の「Clear authentication」で認証を取り消せる
• ブラウザのない環境では claude mcp login --no-browser で URL を表示し、リダイレクト URL を貼り戻す
• 動的クライアント登録に非対応なら --client-id と --callback-port、必要なら --client-secret を使う
• トークンが拒否されたら /mcp の Re-authenticate。スコープ不足は oauth.scopes に足してからサインインし直す