indykite-mcp-server

IndyKite MCP サーバー

IndyKite MCP サーバーを使うと、AI エージェントは、専用の REST 呼び出しを行わずに、Model Context Protocol を通じて「このサブジェクトは Y に対して X を実行できるか？」という認可判断（AuthZEN/KBAC）を行ったり、IndyKite Graph（ContX IQ）の読み書きを行ったりできます。HTTP POST 上の JSON-RPC を使用します。このスキルではステートレスプロトコル（リビジョン 2026-07-28 以降）を使用します。initialize/initialized のハンドシェイクや Mcp-Session-Id は不要で、すべてのリクエストは自己完結しており、params._meta 内のプロトコルメタデータと標準の MCP ヘッダーを含みます。それ以前のリビジョン（例：2025-11-25）ではセッションハンドシェイクを使用します。この従来方式の概要は references/architecture.md を参照してください。

リージョン別のエンドポイントが 2 つあります。

• EU：https://eu.mcp.indykite.com
• US：https://us.mcp.indykite.com

プロジェクトごとの完全な URL は <MCP_REGIONAL_URL>/mcp/v1/<project_gid> です。

使用する場面

ユーザーが次のことを行う場合に、このスキルを有効にしてください。

• IndyKite MCP サーバーを呼び出す必要がある（機能の確認、ツールやリソースの一覧表示、AuthZEN/CIQ ツールの呼び出しなど）。
• プロジェクト用の MCP サーバーを設定する（POST /configs/v1/mcp-servers）ため、設定するフィールドを確認する必要がある。
• .well-known/oauth-protected-resource のメタデータを返す 401 をデバッグしている。ほとんどの場合、Authorization: Bearer トークンがない、期限切れ、または誤った対象に紐付けられています。
• LLM クライアント（Claude Code、Cursor、Goose、MCP Go SDK など）を IndyKite MCP に接続するため、リクエストの形式を確認する必要がある。
• authzen_evaluate、authzen_evaluations、authzen_search_resource、authzen_search_action、ciq_execute のどれを使うか選んでいる。

ユーザーが次のことを行う場合は、このスキルを有効にしないでください。

• IndyKite Agent Gateway について質問している（indykite-agent-gateway スキルを使用してください。IAG は、ゲートウェイの背後にある A2A エージェントまたは MCP サーバーを保護する別の製品です）。
• 直接 REST API を使って AuthZEN または ContX IQ を呼び出している（MCP は関与しません）。エンドポイントと認証方式が異なります。
• IndyKite の実装ではなく、MCP 仕様そのものについて質問している。

前提条件

次のすべてが揃うまで、MCP サーバーはプロジェクトへのリクエストを拒否します。

• Application と、api_permissions に Authorization（authzen_* ツール）および ContXIQ（ciq_execute）を含む AppAgent を備えた IndyKite プロジェクト。サーバーはこの AppAgent を使用して、実行時に IndyKite API を呼び出します。AppAgent は MCP サーバー設定の app_agent_id からサーバー側で解決されるため、クライアントが AppAgent トークンを送信する必要はありません。
• プロジェクト上の Token Introspect 設定。受信したユーザーの Bearer トークンの検証に使用します。
• 実行時エンドポイントを AppAgent（app_agent_id）および Token Introspect に紐付け、scopes_supported を宣言する MCP サーバー設定（POST /configs/v1/mcp-servers）。この設定がないと、プロジェクトへのリクエストは拒否されます。references/configuration.md を参照してください。
• プロジェクトの GID（URL パスで使用）。
• 取り込み済みのデータとポリシー：エージェントが呼び出すツールに応じて、KBAC および／または CIQ ポリシーと Knowledge Query。

不足しているものがある場合は、いったん作業を止めてユーザーに伝えてください。先に不足分を整えるほうが、原因の分かりにくい MCP 拒否をデバッグするよりもはるかに簡単です。

ステートレスなリクエスト形式

このスキルのすべてのリクエストには同じ枠組みを使用し、変更されるのは method とそのペイロードだけです。

本文には、params._meta オブジェクトを含めます。

"_meta": {
  "io.modelcontextprotocol/protocolVersion": "2026-07-28",
  "io.modelcontextprotocol/clientCapabilities": {},
  "io.modelcontextprotocol/clientInfo": {"name": "curl", "version": "1.0"}
}

protocolVersion キーは必須です。これがないリクエストはレガシーなセッションベースのリクエストとして扱われ、404 session not found が返されます。clientCapabilities も必須です（指定するものがない場合は {}）。clientInfo は任意です。

ヘッダーには、以下を指定します。

ヘッダー	値
Authorization: Bearer <token>	ユーザーの OAuth アクセストークン。唯一の認証ヘッダーです（トークンサービスモードのエージェントゲートウェイでは、下記のとおり X-IK-Token が追加される場合があります）。
Content-Type	application/json
Accept	application/json, text/event-stream。レスポンスは SSE ストリームで届く場合があります。
Mcp-Protocol-Version	2026-07-28
Mcp-Method	本文の JSON-RPC method と一致する必要があります。一致しない場合、または指定されていない場合は拒否されます。
Mcp-Name	tools/call（ツール名）、resources/read（リソース URI）、prompts/get（プロンプト名）で必須です。本文の値と一致する必要があります。

セッションは作成されず、Mcp-Session-Id ヘッダーも返されません。混在バージョンのクライアントが 2026-07-28 の _meta とともに古い Mcp-Session-Id を送信した場合は、_meta が優先され、ヘッダーは無視されます。

ヘルパー scripts/mcp-call.sh は、任意のメソッドについてこれらすべてを組み立てます。

手順

1. URL と認証情報を解決する

MCP URL 全体を構成します。<MCP_URL>/mcp/v1/<project_gid> の形式で、<MCP_URL> は https://eu.mcp.indykite.com または https://us.mcp.indykite.com です。値をシェル変数に設定します。

export BEARER_TOKEN="<user-OAuth-access-token>"   # → Authorization: Bearer
export MCP_URL="https://us.mcp.indykite.com"
export PROJECT_GID="<your-project-gid>"

すべての呼び出しで、唯一の認証ヘッダーとして Authorization: Bearer ヘッダーを使用します。サーバーが実行時に IndyKite API を呼び出すために使用する AppAgent は、MCP サーバー設定の app_agent_id からサーバー側で解決されます。クライアントが X-IK-ClientKey AppAgent トークンを送信する必要はなくなりました。その理由については references/architecture.md を参照してください（Bearer トークンは、AuthZEN サブジェクトとしてユーザーを識別します）。

追加できるものが 1 つあります。トークンサービスモードの IndyKite エージェントゲートウェイ経由でルーティングされる呼び出し元は、変更していない Bearer トークンに加えて X-IK-Token: <delegation-token>（プレフィックスなし）も送信します。サーバーはこれを Bearer トークンと同様に検証し、同じ sub を要求します。また、すべての authzen_* および ciq_execute 呼び出しに転送し、ポリシーはその act チェーンを $ik_token として読み取ります。要件を満たさない委任トークンは、何も転送される前に 400 invalid_request で拒否されます。詳細は references/architecture.md を参照してください。発行方法については indykite-agent-gateway スキルを参照してください。

2. server/discover でサーバーを確認する（任意ですが推奨）

ステートレスプロトコルでは、サーバーの機能と対応するプロトコルリビジョンを返す server/discover メソッドが追加されています。まずこれを使い、エンドポイントが 2026-07-28 に対応していることを確認してください。

curl -s -i -X POST "$MCP_URL/mcp/v1/$PROJECT_GID" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer $BEARER_TOKEN" \
  -H "Mcp-Protocol-Version: 2026-07-28" \
  -H "Mcp-Method: server/discover" \
  -d '{
        "jsonrpc": "2.0",
        "id": 1,
        "method": "server/discover",
        "params": {
          "_meta": {
            "io.modelcontextprotocol/protocolVersion": "2026-07-28",
            "io.modelcontextprotocol/clientCapabilities": {},
            "io.modelcontextprotocol/clientInfo": {"name": "curl", "version": "1.0"}
          }
        }
      }'

レスポンスは 200 で、result.supportedVersions（例：["2026-07-28", "2024-11-05", …]）、result.capabilities、サーバーの指示が含まれます。Mcp-Session-Id ヘッダーはありません。または、scripts/mcp-call.sh server/discover を実行してください。

3. ツールとリソースを確認する

ツールを呼び出す前に、サーバーに利用可能なものを確認します。便利な方法は3つあります（それぞれ、_metaとヘッダーは同じで、Mcp-Methodを変更する自己完結型のPOSTです）。

• tools/list - エージェントが呼び出せるツールです（標準のセットはreferences/tools.mdにありますが、このデプロイ環境で公開されているものを確認するために一覧を取得してください）。
• resources/list - MCP サーバーが公開しているリソースです。
• uri: "indykite://knowledge-queries/"を指定したresources/read（Mcp-Nameヘッダーにも指定します） - すべてのCIQ Knowledge Queryについて、エージェントが利用しやすい説明と、それぞれが想定するパラメーターを確認できます。

3つ目の方法は、ciq_executeを呼び出す前に特に重要です。エージェントに渡すべきidと、クエリが想定するinput_paramsの形式を確認できます。

scripts/mcp-call.sh tools/list
scripts/mcp-call.sh resources/read 'indykite://knowledge-queries/'

4. AuthZEN ツールを呼び出す

認可の判定では、質問に応じて適切なツールを選びます。

質問	ツール
「サブジェクトXはリソースZに対してアクションYを実行できますか？」	authzen_evaluate
「これらのチェックをまとめて実行する」	authzen_evaluations
「サブジェクトXがアクションYを実行できる、タイプTのリソースはどれですか？」	authzen_search_resource
「サブジェクトXがリソースZに対して実行できるアクションはどれですか？」	authzen_search_action

各ツールは、_metaの隣にあるparams内のnameとargumentsとともに、MCPのtools/callメソッドを使って呼び出します。また、Mcp-Method: tools/callとMcp-Name: <tool name>のヘッダーも指定します。スキーマと1回の呼び出しの例はreferences/tools.mdにあります。注意が必要な規則が1つあります。サブジェクトが認証済みの呼び出し元である場合、subject_idには別途指定したユーザー識別子ではなく、Bearerトークンのsubクレームを指定します。

scripts/mcp-call.sh tools/call authzen_evaluate \
  '{"subject_type":"Person","subject_id":"alice","resource_type":"Car","resource_id":"cadillacv16","action_name":"CAN_DRIVE"}'

5. CIQ ツールを呼び出す

ciq_executeは、IndyKite Graphに対してKnowledge Queryを実行します（読み取りまたは書き込み）。主な引数は2つで、ページネーション用にオプションの引数が2つあります。

• id - 実行するKnowledge QueryのGIDまたは名前です。
• input_params - Knowledge Queryとそのポリシーで定義されたパラメーターの一部です。正確なセットはクエリの説明に記載されています。
• page_size - オプションです。1ページあたりの行数で、デフォルトは100、最大は1000です（それより大きい値を指定すると検証エラーpage_size exceeds maximum of 1000になります）。
• page_token - オプションです。1から始まるページ番号です（1または省略した場合は最初のページ、2は次のページです）。結果にはトークンが含まれないため、値を増やしながら、page_sizeより短いページが返された時点で停止します。

エージェントが正しいパラメーターを渡せるよう、必ず最初にindykite://knowledge-queries/を指定したresources/readでクエリを確認してください。

6. レスポンスを読み取り、解釈し、監査する

レスポンスはプレーンなJSON、またはSSEストリームとして届く場合があります（Accept: application/json, text/event-streamヘッダーによって後者が許可されます）。SSEの場合、JSON-RPCメッセージはイベントのdata:行に含まれます。JSON-RPCレスポンスにはリクエストのidがそのまま含まれ、成功時はresult、失敗時はerrorが含まれます。AuthZENでは、意味のあるペイロードはresult.content内のtextコンテンツ項目で、その本文にJSON形式の判定結果が含まれています。CIQでは、クエリが返した行がペイロードです。サービス側のエラー（設定の不備、スコープの不足）は通常、JSON-RPCのerrorオブジェクトとして現れます。サーバーがサポートしていないプロトコルのリビジョンが指定された場合は、エラーコード-32022とrequestedおよびsupportedのバージョンを示すエラーとともに400が返されます。トランスポートの問題（認証、接続）はJSON-RPCが実行される前にHTTP 4xx／5xxとして返されます。詳しくはreferences/troubleshooting.mdを参照してください。

レガシーのセッションベースクライアント

2026-07-28より前のプロトコルリビジョン（例：2025-11-25）では、セッションハンドシェイクを使用します：initialize → Mcp-Session-Idレスポンスヘッダーを取得 → notifications/initialized → すべての呼び出しでヘッダーを送信します。どちらの方式でも認証方法は同じで、公開されるツールとリソースも同じです。レガシー方式を使用するのは、クライアントライブラリが_metaベースのリクエストを送信できない場合に限ってください。ライフサイクルとルールについては、references/architecture.mdを参照してください。

成功条件

このスキルが正常に適用された場合：

• プロジェクト用のMCPサーバー設定が存在し（app_agent_idが設定されている）、enabledがtrueになっています。
• エージェントのスコープにBEARER_TOKEN（ユーザーのOAuthアクセストークン）があり、これを唯一のAuthorization: Bearer認証ヘッダーとして送信します。
• server/discoverは、result.supportedVersionsに2026-07-28を返し、いずれのレスポンスにもMcp-Session-Idヘッダーが含まれません。
• tools/listとindykite://knowledge-queries/のresources/readにより、エージェントが呼び出せる内容を列挙できます。
• AuthZENの判定とCIQクエリの結果がJSON-RPC経由で返され、エージェントはそれらをワークフローで使用します。

このスキルのファイル

• references/architecture.md - プロトコル方式（ステートレスな2026-07-28とレガシーセッション）、サーバー側のAppAgent解決を伴う単一Bearerトークン認証、RFC 9728の401動作。
• references/configuration.md - POST /configs/v1/mcp-serversのフィールドリファレンスとペイロードの例。
• references/tools.md - すべてのAuthZENおよびCIQツールのスキーマと使用例。
• references/troubleshooting.md - 症状と原因の対応表。
• scripts/mcp-call.sh - ステートレスなMCP呼び出しを1回実行するBashヘルパー（任意のメソッド用に_metaオブジェクトとMCPヘッダーを構築します）。環境にMCP_URL、PROJECT_GID、BEARER_TOKENが設定され、PATH上にcurlが必要です。

エージェント固有の注意事項

このスキルは汎用的なMarkdown指示を使用し、READMEに記載されたすべてのエージェントで動作します。エージェントがHTTPリクエストを実行できることを前提としています（Bashとcurl、HTTP MCPクライアント、またはMCP Go SDKなどのSDK）。Claude Codeのフック、Cursorの@メンション、Copilotのワークスペースコンテキストは必要ありません。

参考資料

• MCPサーバーの使用方法（IndyKite開発者ハブ）
• Model Context Protocol仕様
• MCP Go SDK
• POST /mcp-servers APIリファレンス
• POST /token-introspects APIリファレンス
• POST /application-agent-credentials APIリファレンス
• RFC 9728 - 保護対象リソースのメタデータ