Claude Code ガイド

Appearance

原文（日本語に翻訳） ​

未認証のclaude.ai MCPコネクターが「failed」ではなく「needs auth」として表示されるように修正し、ヘッドレス -p モードが一時的でない4xx接続エラーを再試行しないように修正しました。

原文（英語） ​

Fixed unauthorized claude.ai MCP connectors showing as 'failed' instead of 'needs auth', and headless -p mode retrying non-transient 4xx connection failures

概要 ​

claude.aiのMCPコネクターで認証が必要な場合、以前は「failed」という一般的なエラーメッセージが表示されており、ユーザーは接続の失敗原因が認証不足なのか技術的なエラーなのかを判断できませんでした。また、ヘッドレスモード（-p フラグ）では、HTTP 4xxエラー（認証エラーなど永続的なエラー）に対しても不必要に再試行を繰り返していました。この修正により、エラー状態が明確に区別され、不要な再試行も排除されます。

基本的な使い方 ​

/mcp コマンドでMCPコネクターの認証状態を確認できます。

/mcp

# 修正前の表示（わかりにくい）
# my-connector: failed

# 修正後の表示（認証が必要な場合）
# my-connector: needs auth  ← 認証が必要であることが明確

# 認証完了後
# my-connector: connected · 5 tools

実践例 ​

claude.ai MCPコネクターの認証フロー ​

# 1. /mcpで状態を確認
/mcp

# 出力例（認証が必要な場合）
# claude-ai-connector: needs auth

# 2. 認証を実行
# /mcp auth <connector-name> を実行
/mcp auth claude-ai-connector

# 3. ブラウザが開き、認証フローが開始される
# claude.aiにログインして権限を承認

# 4. 認証完了後に再確認
/mcp
# claude-ai-connector: connected · 8 tools

ヘッドレスモードでの4xxエラー処理 ​

bash
# ヘッドレスモードでMCPコネクターを使用する例
claude -p "MCPサーバーのデータを取得して分析してください"

# 修正前: 4xxエラー（401 Unauthorized, 403 Forbidden等）でも再試行を繰り返した
# → タイムアウトまで待機してパフォーマンスが低下

# 修正後: 4xxエラーは永続的なエラーとして即座に失敗を返す
# → 迅速なエラーフィードバックと効率的な動作

# 認証エラーの場合のエラーメッセージ例（修正後）
# エラー: MCP接続に失敗しました。認証が必要です（401 Unauthorized）
# 解決方法: /mcp auth <connector-name> を実行して認証してください

エラーコード別の対処方法 ​

# 4xxエラーの種類と対処方法

# 401 Unauthorized → 認証が必要
# 対処: /mcp auth <connector-name> で認証

# 403 Forbidden → 権限不足
# 対処: MCPサーバーの管理者に権限付与を依頼

# 404 Not Found → エンドポイントが存在しない
# 対処: MCPサーバーのURLを確認

# 429 Too Many Requests → レート制限
# 対処: しばらく待ってから再試行（これは一時的なエラーのため再試行される）

# 5xxエラー → サーバーエラー（一時的）
# 対処: 自動再試行が行われる

CI/CDでのヘッドレスモード活用 ​

bash
#!/bin/bash
# CI/CDパイプラインでのClaude Code活用例

# 事前に認証情報を環境変数で設定
export ANTHROPIC_API_KEY="your-api-key"

# ヘッドレスモードでコードレビューを実行
result=$(claude -p "このプルリクエストのコードをレビューしてください" 2>&1)
exit_code=$?

# 修正後: 4xxエラーは即座に失敗を返すため、タイムアウトを待たずに処理できる
if [ $exit_code -ne 0 ]; then
    echo "Claude Code実行に失敗しました: $result"
    exit 1
fi

echo "レビュー結果: $result"

注意点 ​

  • 「needs auth」状態のMCPコネクターは、認証を完了するまで利用できません。/mcp auth コマンドで認証を行ってください。
  • ヘッドレスモード（-p）での4xxエラーは永続的なエラーとして扱われ、再試行されません。5xxエラー（サーバーエラー）は引き続き再試行されます。
  • claude.ai MCPコネクターはclaude.aiのアカウントが必要です。組織のSSO設定によっては追加の認証手順が必要な場合があります。
  • 認証トークンの有効期限が切れた場合は、再度 /mcp auth で認証する必要があります。

関連情報 ​