公式MCPで横断と深さは両立しない。代理店トークンとロケーショントークンの対照実験

GoHighLevelの公式MCPは、Claudeにつなげる口です。「1回の認証で、すべてのサブアカウントを触れる」という話を聞いて、試した方も多いと思います。

私たちは、代理店用のトークンとロケーション（サブアカウント）用のトークンの両方で、公式MCPの2026年8月末の姿を実測しました。結論は、「横断」と「深さ」は同時に持てない、というものです。

接続の形

接続先は、Claude向けの専用の口です。使えるツールは4つでした。

• search_operations：操作を検索する
• describe_operation：操作の詳細を見る
• execute_operation：操作を実行する
• list_locations：ロケーションを列挙する

実行の際、locationId は2か所に要ります。execute_operation の引数と、params の中の両方です。片方だけだと、期待したアカウントに届きません。

対照した結果

2種類のトークンを、2つの深さで当てて比べました。

• 代理店トークンで、任意のサブアカウントの基本情報を読む：成功。横断はできる
• 代理店トークンで、そのタグの一覧を読む：401。深くは行けない
• ロケーショントークンで、自分のタグの一覧を読む：成功。深く行ける
• ロケーショントークンで、別のサブアカウントの基本情報を読む：403。横断はできない

横断のトークンは深く行けず、深いトークンは横断できません。両方を持つトークンは、存在しませんでした。1本の鍵で全部やろうとすると、どちらかで詰まります。

実際に起きたこと

代理店トークンの1本で、86のサブアカウントを列挙できました。そのうち3つの基本情報が読め、1つは、自前の台帳に「トークン未発行」と書いてあったアカウントです。鍵を足さずに読めました。

ところが、同じ鍵で、タグ、カスタム値、カスタムフィールド、重複コンタクトの検出、カレンダー、パイプライン、ブログ、ワークフローを読むと、すべて401でした。内容は「このトークンは、このスコープを許可されていない」です。

「全部できる」と書くと外す

私たちが気づいたのは、「全アカウントへ1回の認証」を、成立か不成立かの二択で報告すると外れることです。経路と権限で、割れています。

経路は、通っています。権限は、深い層で開いていません。公式の説明にも、代理店全体への接続は「順次展開中」とあり、単一のサブアカウントだけが選べる接続では、この選択肢が有効になっていないことがある、と書かれています。

残りのピースは、代理店の単位でのOAuthのインストールです。伝え聞いた「全ロケーションに触れる」を前提に手順を組むと、深い層で止まります。

着手前の1回の確認

深い層を触る仕事では、着手の前に、タグの一覧を1回だけ読んでみます。401なら、代理店のOAuthが未完了です。その先を組むのは、やめます。この確認は数秒で済み、組んだあとで壊れる損を避けられます。

公式の説明と実物の食い違い4点

実物を叩いて、公式の説明と違う点を4つ見つけました。

• ツールの数：説明は6つだが、実際の一覧には4つしか出ない
• 検索の絞り込み：説明は、許可された操作だけに絞られるとあるが、削除の操作も普通に一覧へ出る。遮断は、実行時の401だけ
• スコープの表：旧来の口と新しい口のメタデータは、154個で完全に一致し、差がない。新しい口が広いのは、操作の一覧の話
• ロケーションの列挙：トークン接続では500で返る。ツールは見えるのに、中身がない

2点目は大切です。検索結果に出ているからといって、使えるとは限りません。使えるかどうかは、実行して、401が返るかで決まります。

運用上の指針

この結果を踏まえて、私たちは次のように決めました。

• 横断が目的の仕事は、代理店トークンで、基本情報の読み取りまでに限る
• 深い読み書きは、そのアカウントのロケーショントークンで行う
• 新しい仕事の最初に、1回だけ深い層を読み、401なら計画を縮める

「見えている」と「使える」は別、という点をClaude Codeにも最初に伝えておくと、同じところで詰まりません。

再測定でも、壁は同じだった

数日あけて、もう一度同じ試験を流しました。結果は、変わりませんでした。列挙できるサブアカウントは87に増えていましたが、深い層の401と、横断のできないロケーショントークンの403は、そのままでした。

代理店のOAuthのインストールが、公式に完了するまでは、この壁は動きません。再測定は、壁が動いていないことを確かめる作業で、短時間で済みます。仕事の計画を立てる前に、1回だけ流しておくことをお勧めします。

次に読む

公式MCPの外側にも、電話の応対の設定という口があります。日本ではまだ使えない部分を含めて、画面で1本作ってAPIで写す型は、電話の応対の記事にまとめました。