Claude Media
SourcegraphのMCPをClaude Codeに接続する手順
Claude CodeMCPClaude連携チュートリアル

SourcegraphのMCPをClaude Codeに接続する手順

SourcegraphのMCPサーバーをClaude Codeにclaude mcp addで繋ぐ手順です。3つのエンドポイントの違い、OAuthとアクセストークンの使い分け、権限の絞り方も扱います。

読了目安 約11分

SourcegraphのMCP(Model Context Protocol)サーバーは、自社のSourcegraphインスタンスにある大規模なコードベースの検索・参照・履歴調査を、Claude Codeから呼べるようにします。ローカルにクローンしていないリポジトリも対象にできるのが特徴です。

提供はEnterpriseプランの機能です。接続コマンドは1行で済みますが、つまずきやすい点が3つあります。

  • エンドポイントが3種類あり、既定のURLではDeep Searchを新規に始められない
  • 認証がOAuth(動的クライアント登録)・事前登録クライアント・アクセストークンの3通りある
  • アクセストークンを.mcp.jsonに書くときの環境変数の置き方

接続はclaude mcp addの1行から

Claude CodeはHTTP型のリモートMCPサーバーを--transport httpで追加します。Sourcegraphの例では、次のコマンドを実行します。sourcegraph.example.comは自社インスタンスのURLに置き換えます。

claude mcp add --transport http sourcegraph \
  https://sourcegraph.example.com/.api/mcp

SourcegraphはOAuthの動的クライアント登録に対応しているため、クライアントIDを事前に発行する必要はありません。流れは次の3段です。

手順

OAuthで接続するまでの流れ

  1. 1

    サーバーを登録する

    claude mcp add --transport httpでエンドポイントを指定します。

  2. 2

    /mcpで認証する

    セッション内で/mcpを開き、sourcegraphの認証を選びます。ブラウザが開きます。

  3. 3

    ツール数を確認する

    認証後は/mcpの一覧にツール数が出ます。0件なら、後述のエンドポイントの選び方を見直します。

シェルから認証を済ませたいときはclaude mcp login sourcegraphも使えます。非対話モード(claude -p)にはOAuthの画面がないため、先に対話セッションかこのコマンドで認証を済ませておく必要があります。

エンドポイントは3つ — どのURLを選ぶか

サーバーはパスごとに公開するツールの範囲が違います。ツール数が多いほどコンテキストを食うので、必要な範囲で最小のURLを選びます。

エンドポイント範囲
/.api/mcp範囲検索・リポジトリ・履歴の中核ツールとDeep Searchの読み取り
/.api/mcp/all範囲全ツール
/.api/mcp/deepsearch範囲Deep Searchエージェントのツールのみ

既定の/.api/mcpには落とし穴があります。deepsearch_readで既存のDeep Searchの会話は読めますが、deepsearchで新しい会話を作れません。Claudeに調査そのものを任せたいなら、/.api/mcp/allか/.api/mcp/deepsearchを登録します。

一方、コードの定義や参照を辿るツールは/.api/mcp/allにしか含まれません。リファクタリングの影響範囲を追う用途ならallが必要です。

くらべる

どのエンドポイントで始めるか

中核だけ

/.api/mcp

code_finder・keyword_search・read_file・commit_searchなど。コンテキストを節約したい日常の調査向けです。

全部入り

/.api/mcp/all

上に加えてgo_to_definition・find_references・compare_revisions・nls_searchなど。

/.api/mcpでは、code_finderが使えないか無効化されているときの代替としてnls_searchが出ます。

主要ツールと使いどころ

ツール名はSourcegraph側の定義どおりにClaudeへ見えます。Claude Code上の呼び出し名はmcp__sourcegraph__<ツール名>の形になります。

  • list_repos: リポジトリ名の部分一致で絞り込む。limitの既定は50
  • keyword_search: repo:・file:・rev:・count:の絞り込みを使う厳密なキーワード検索
  • code_finder: タスクを渡すと内部で検索を回し、該当ファイルと行範囲を返す
  • read_file: 行範囲とリビジョンを指定して読む。128KBを超えるファイルは先頭200行で打ち切られる
  • commit_search・diff_search: コミットメッセージや差分内容を横断検索
  • evaluator: 検索結果の集計をサンドボックス内のLuaスクリプトで行う

code_finderの使用量はインスタンスの契約枠で計測されます。枠を使い切るとツールがエラーを返します。対象リポジトリを名指しして頼むと精度が上がります。

会話

code_finderへの頼み方

  1. 後輩

    「ショップのエラー処理を探して」と頼んだら、結果が散らかりました。

  2. 先輩

    code_finderは知っているリポジトリの中を探すツールです。「github.com/example/shopで、HTTPエラー応答を組み立てている箇所を探して」のようにリポジトリと成功条件を書きます。

リポジトリが分からないときは、先にlist_reposで特定させるのが定石です。続けてlist_refsで有効なブランチやタグを調べてからread_fileへ進める流れが、Sourcegraphの案内する組み合わせです。

認証 — OAuthかアクセストークンか

Claude CodeではOAuthの動的クライアント登録(DCR)が使えます。SourcegraphはDCRを既定で有効にしており、登録されたクライアントはmcpスコープに限定されます。管理者がクライアントを事前承認する運用の組織では、DCRを無効にして事前登録クライアントを使います。

方式向くケース
OAuth(DCR)向くケースクライアントがOAuth対応で、自動登録を許す組織
事前登録クライアント向くケース管理者がクライアントを事前承認する組織
アクセストークン向くケースクライアントがOAuthに対応しない場合

チームで.mcp.jsonを共有し、トークンで接続させたいときは、トークン自体は書かず環境変数にします。

{
  "mcpServers": {
    "sourcegraph": {
      "type": "http",
      "url": "https://sourcegraph.example.com/.api/mcp",
      "headers": {
        "Authorization": "token ${SOURCEGRAPH_ACCESS_TOKEN}"
      }
    }
  }
}

${VAR}の展開は.mcp.jsonのheadersでも使えます。ただしANTHROPIC_AUTH_TOKENのようなClaude Codeや各クラウドの認証情報にあたる変数は、リモートサーバーのheadersでは空として読まれます。SOURCEGRAPH_ACCESS_TOKENはこの対象に当たらないため展開されます。

CLIで同じ設定を自分のプロジェクトだけに入れるなら、次のように書きます。

claude mcp add --transport http sourcegraph \
  https://sourcegraph.example.com/.api/mcp \
  --header "Authorization: token $SOURCEGRAPH_ACCESS_TOKEN"

同じ名前で複数のスコープに登録すると、ローカルスコープがプロジェクトスコープより優先されます。.mcp.jsonのサーバーは、初回に承認を求められます。

Authorizationヘッダーを設定したサーバーが401や403を返したとき、Claude CodeはOAuthへ切り替えず接続失敗として扱います。トークンの期限切れやスコープ不足を先に疑います。

権限とデータの範囲を絞る

MCPのアクセスはリポジトリ権限とは別の層で制御されます。ただしMCP経由でも、読めるのはそのユーザーが既にアクセスできるリポジトリだけです。

管理者が使える絞り込みは3つあります。

  • mcp.enabled: MCPエンドポイントの有効・無効(既定はtrue)。falseだと/.api/mcp配下は404になる
  • mcp.tools.disabled: ツール名の配列で個別に無効化。deepsearchやcode_finderを外せる
  • RBAC: ユーザーがMCP#ACCESS権限を持つ必要がある。既定では組み込みのUserロールに付与されている

利用者側の絞り込みは、Claude Codeの権限ルールで行えます。検索系だけ自動承認し、他はそのまま確認を求める構成にできます。

{
  "permissions": {
    "allow": [
      "mcp__sourcegraph__keyword_search",
      "mcp__sourcegraph__read_file",
      "mcp__sourcegraph__list_repos"
    ]
  }
}

サーバー名でmcp__sourcegraph__*と書けば全ツールを一括で許可でき、サーバー名だけのmcp__sourcegraphでも同じ範囲に当たります。広く許可する前に、使うエンドポイントのツールを確認します。

つまずいたとき

切り分け

接続できないときの切り分け

  1. Q/mcpの一覧にsourcegraphは出るか?
    答えがいいえ

    claude mcp listで登録の有無と、同名の定義が別スコープに重複していないかを確認します。

    答えがはい
  2. QOAuth認証でinvalid_scopeになるか?
    答えがいいえ

    要求するスコープをmcpに固定します。Claude Codeの--transport httpはDCRでmcpスコープが自動登録されるため、通常は起きません。

    答えがはい
  3. Q403 forbiddenが返るか?
    答えがいいえ

    トークンにmcpスコープがあるか、ユーザーにMCP#ACCESS権限があるかを確認します。MCPが無効なら403ではなく404です。

    答えがはい

それでもつながらない

/.auth/idp/oauth/registerが404なら、DCRが無効です。管理者に事前登録クライアントを依頼します。

失敗の理由はコマンドでも読めます。claude mcp listは✘ Failed to connectの行にHTTPステータスやサーバーが返したエラー文を添え、claude mcp get sourcegraphは同じ内容をIssue:の行に出します。404ならMCPの無効化かURLのパス違い、403ならトークンのスコープかMCP#ACCESS権限、というように、先ほどの切り分けと対応づけて読めます。このステータス詳細の表示はClaude Code v2.1.219以降です。

OAuthのアクセストークンは1時間で失効し、リフレッシュトークンは1回しか使えません。独自のクライアントを作る場合は、更新のたびに新しいリフレッシュトークンを保存する必要があります。Claude Codeでは/mcpのRe-authenticateで入り直せます。

接続自体の失敗は、/mcp reconnect allで一括再接続できます。OAuth接続で別のサービスにつまずいたときの見方は、GitHub MCPのOAuth接続エラーの切り分けが参考になります。

大きな出力と運用の注意

Claude CodeはMCPツールの出力が1万トークンを超えると警告し、既定では2万5千トークンで切ります。検索結果が長いときはMAX_MCP_OUTPUT_TOKENSで上限を変えられますが、Sourcegraph側にも結果数の上限と、after・beforeのカーソルによるページ送りがあります。まず検索条件を絞るのが先です。

検索系のMCPサーバーは、同じ接続の手順で他のサービスも扱えます。TavilyのようなWeb検索は外部の情報、Sourcegraphは自社コードの情報を渡す役割分担です。静的解析の指摘まで必要なら、SonarQubeのMCPサーバーを併用する選択肢があります。

この記事を共有:XはてブLinkedIn

関連する記事

Claude Code をもっと見る →