Kong Konnect MCPをClaude Codeにつないで構成を調べる
Kong Konnect MCPサーバーをClaude Codeに追加し、ブラウザ認証かトークンで接続して、ゲートウェイのルートやプラグイン、分析データを調べる手順と、書き込みを防ぐ権限の絞り方をまとめます。
Kong Konnect MCPサーバーをClaude Codeに追加すると、コントロールプレーン、サービス、ルート、プラグインといったKong Gatewayの構成を、ターミナルから自然文で調べられるようになります。ダッシュボードを開かずに「このルートにどのプラグインが付いているか」を聞けるのが、最初の使いどころです。
接続コマンドは1行です。この記事では、認証方式の選び方、接続の確認、ゲートウェイやルートを調べる聞き方、そして execute ツールを前提にした権限の絞り方を順に扱います。
接続に必要なものと、使える範囲
Kong Konnect MCPサーバーは、Konnectの管理APIをModel Context Protocol経由で公開するリモートサーバーです。Claude Codeから使う場合、手元にインストールするものはありません。URLを登録するだけです。
サーバーが扱う範囲は、Kongのドキュメントで次のように整理されています。
| 用途 | できること |
|---|---|
| エンティティの参照 | できることコントロールプレーン、サービス、ルート、コンシューマー、コンシューマーグループ、プラグイン、Vaultの照会 |
| APIデバッグ | できることアクティブトレーシング付きのデバッグセッションを作り、遅延の原因を調べる |
| 分析 | できること時間範囲、ステータスコード、コンシューマー、サービス、ルートで絞ったリクエストデータの照会 |
| ドキュメント検索 | できることKongのドキュメントから設定や障害対応の手順を探す |
| Dev Portal | できることページ、スニペット、Markdown Componentsの作成・編集・公開 |
読み取りだけでなく、Dev Portalの編集のような変更系の用途も同じサーバーに含まれます。この点は権限の節で効いてきます。
接続先のURLは、リージョンを問わず使える https://global.mcp.konghq.com/ が1つあります。US・EU・AU・INの各リージョン専用のURL(https://us.mcp.konghq.com/、https://eu.mcp.konghq.com/、https://au.mcp.konghq.com/、https://in.mcp.konghq.com/)も用意されています。リソースがどのリージョンにあっても、グローバルのURLで足ります。データの置き場所を固定したい組織だけが、リージョン別URLを選ぶことになります。
認証は「ブラウザ」か「トークン」か
Claude Codeからの認証方式は3つあります。選び方は、誰が使うかで決まります。
認証方式の3つの選択肢
ブラウザ認証
Claude Codeが開いたブラウザでKonnectにサインインし、アクセスを承認します。トークンを発行・保管する手間がなく、個人の調査用途に向きます。
Personal Access Token(PAT)
KonnectのトークンページでGenerate Tokenから発行し、
Authorization: Bearerヘッダーで渡します。自分が閲覧できるリソースにだけアクセスでき、問い合わせは組織のロールベースのアクセス制御とリージョンのデータ境界に従います。System Account Access Token
自動化ワークフロー向けのトークンで、サービスアカウントに紐づく定義済みの権限だけを持ちます。人が介在しないエージェントやCIで使う想定です。
手元で試すだけならブラウザ認証が最短です。チームで使い回す設定や、サブエージェントに調査を任せる構成では、権限を後から数える対象が明確なSystem Accountのトークンが扱いやすくなります。
接続する手順
ブラウザ認証での追加は、次の1行です。サーバー名は kong-konnect にしています。この名前は、後で権限ルールを書くときのキーになります。
claude mcp add --transport http kong-konnect https://global.mcp.konghq.comClaude Codeがブラウザを開くので、Konnectにサインインしてアクセスを認可します。セッションの中から認証し直すときは /mcp パネルを使い、シェルから実行するなら claude mcp login kong-konnect が使えます。
トークンで接続する場合は、--header を付けます。
claude mcp add --transport http kong-konnect \
https://global.mcp.konghq.com/ \
--header "Authorization: Bearer YOUR_KONNECT_PAT"YOUR_KONNECT_PAT は発行したトークンに置き換えます。設定ファイルを直接編集する場合は、~/.claude.json(プロジェクト単位で共有するなら .mcp.json)の mcpServers に次の形で書きます。
{
"mcpServers": {
"kong-konnect": {
"type": "http",
"url": "https://global.mcp.konghq.com/",
"headers": {
"Authorization": "Bearer YOUR_KONNECT_PAT"
}
}
}
}--scope を付けずに追加したサーバーは、追加したプロジェクトでだけ使えるローカルスコープに入ります。チームで共有する .mcp.json にトークンを直接書くとリポジトリに残るため、PATの場合はローカルスコープのままにするのが無難です。
追加後は、次のコマンドで状態を確かめます。
claude mcp listKongの手順書では、kong-konnect: https://global.mcp.konghq.com/ (HTTP) - ✓ Connected と表示されるのが接続成功の目安とされています。✘ が出た場合は、claude mcp get kong-konnect の Issue: 行にHTTPステータスやサーバーのエラー文が出ます。
ツールは3つだけ — search、get_schema、execute
Konnect MCPサーバーを入れると、ツール一覧には list_routes のような個別の操作は並びません。公開されているのは3つの汎用ツールです。
search: 「コントロールプレーン内のサービスを一覧する」のような説明から、該当するAPI操作を探すget_schema: 見つけた操作の入力スキーマを取得し、必要なパラメーターやリクエストボディの項目を知るexecute: スキーマに従った入力でAPI操作を呼ぶ
Claudeは「探す、仕様を読む、実行する」の順にツールを呼びます。操作ごとのツール定義を持たず、実行時にAPIの操作を探して呼び出しを組み立てる設計です。Claude Code側では、これらが mcp__kong-konnect__search、mcp__kong-konnect__get_schema、mcp__kong-konnect__execute という名前で扱われます。
ここで押さえておきたいのは、execute には読み取り用と書き込み用の区別がないことです。一覧の取得も、リソースの変更も、同じ入口から呼ばれます。ツール名だけでは危険度を判別できないので、権限の線引きは次の節で別に設計します。
MCPサーバーのツール定義が複雑なスキーマを持つときの扱いは、Claude CodeのMCPでルートレベルanyOf/oneOf/allOfを平坦化する仕組みで掘り下げています。
ゲートウェイとルートを調べる聞き方
接続できたら、まず構成の全体像から聞きます。例えば次のような依頼文です。
Konnectのコントロールプレーンを一覧にして、
それぞれのサービス数とルート数を表にしてcontrol plane "prod-gateway" のルートのうち、
プラグインが1つも付いていないものを挙げてorders サービスに紐づくルートと、各ルートで有効な
プラグインの種類を一覧にして。変更はしないこと最後の依頼文のように「変更はしないこと」を添えておくと、調査の意図が明確になります。ただし、これは依頼の文面であって権限ではありません。実際に変更を止めるのは、次に説明するClaude Code側の設定とトークンの権限です。
分析データの照会も、同じ流れで聞けます。時間範囲、ステータスコード、コンシューマー、サービス、ルートで絞り込めるため、次のような依頼が成り立ちます。
直近24時間で orders サービスの5xxが多いルートを、
ステータスコード別に集計して遅延の原因が分からないときは、デバッグセッションの作成を頼む使い方があります。アクティブトレーシングを伴うので、本番のトラフィックに影響しうる操作です。調査用であっても、実行前にどのコントロールプレーンのどのルートが対象かをClaudeに言わせてから承認すると、取り違えを防げます。
設定の書き方で迷ったときは、Kongのドキュメント検索も同じサーバーから使えます。KAiを有効にしている組織では、追加で KnowledgeBase ツールが加わります。このツールは問い合わせから埋め込みを作り、再ランキングモデルでドキュメント検索の結果を並べ替えます。これらのモデルはAWS Bedrock上でホストされ、データを使った学習は行われないとされています。
権限を絞る — 読むだけの構成にする
execute が書き込みも担う以上、「調べるだけ」の運用には2層の絞り込みが要ります。
1層目: トークンの権限
MCPツールのアクセス権は、認証に使ったPATやSystem Accountトークンの持ち主の権限と同じです。つまり、Claudeが何をできるかの上限は、そのトークンで決まります。調査用途なら、読み取りに必要な権限だけを持たせたSystem Accountを作り、そのトークンで接続すると、Claude Code側の設定を誤っても書き込みには届きません。
ブラウザ認証は、サインインした人の権限をそのまま引き継ぎます。管理者権限を持つアカウントで認証すると、調査用の接続でも管理者の操作が可能です。
2層目: Claude Codeの許可ルール
Claude Codeの許可ルールは、mcp__<サーバー名>__<ツール名> の形で書けます。許可ルールのワイルドカードは、mcp__<サーバー名>__ という固定の接頭辞の後ろにだけ使えます。search と get_schema は確認なしで通し、execute は毎回確認を挟む構成にすると、次のように書けます。
{
"permissions": {
"allow": [
"mcp__kong-konnect__search",
"mcp__kong-konnect__get_schema"
],
"ask": [
"mcp__kong-konnect__execute"
]
}
}.claude/settings.json(個人用なら .claude/settings.local.json)に置きます。仕様を調べるだけの search と get_schema は自動で進み、実際にAPIを呼ぶ execute の直前で止まります。承認の画面では、呼ぼうとしている操作と入力が見えるので、GETなのか変更系なのかをそこで判断します。
execute を完全に止めたいなら deny に入れる手もありますが、その場合は何も実行できず、構成の調査という本来の目的も果たせません。トークン側を読み取り専用にしたうえで、execute は ask のままにする組み合わせが現実的です。
Claude Codeの全体像から権限まわりをたどれます。同じ「読み取り範囲を絞ってから使う」考え方は、Base44のMCPサーバーをClaudeにつなぐ手順と権限の注意点でも扱っています。
つまずいたときの切り分け
Kongのよくある質問は、症状ごとに確認先を示しています。
| 症状 | 確認すること |
|---|---|
| 認証エラーが出る | 確認することPAT/SPATが有効か、組織がMCPアクセスを無効化していないか、トークンに必要な権限があるか |
| 接続できない | 確認することネットワーク接続、サーバーURLの綴り、ファイアウォールが global.mcp.konghq.com を遮断していないか |
| ツールの実行が失敗する | 確認することパラメーターの正しさ、リソースへのアクセス権、レート制限の待機、対象リソースの実在 |
Konnect MCPサーバーのアクセスは、既定で有効です。組織の管理者は、KonnectのAI Settingsから無効にでき、無効にするとその組織の誰もMCPサーバーを使えなくなります。会社のKonnect組織で接続が拒否されるときは、この設定を管理者に確認する価値があります。
使い分けの目安
Konnect MCPの強みは、構成を聞く場面です。複数のコントロールプレーンにまたがる「プラグインが付いていないルート探し」のように、画面を何度も切り替える作業を1つの依頼にまとめられます。逆に、設定をGitで管理してレビューを通している構成では、変更の経路が別にあるはずです。MCP経由の execute で直接書き換えると、その経路を迂回します。調査は execute の読み取りで行い、変更は既存のレビュー経路に戻す、という分担にしておくと運用が崩れません。
位置情報を扱うMCPなど、ほかの外部サービスとの接続例はClaude CodeにMapbox MCPを入れて地図・ルート検索を作るにあります。接続、確認、権限の絞り込みという流れは、サービスが変わっても共通です。