indykite-mcp-server

IndyKite MCP 服务

IndyKite MCP 服务让 AI Agent 能直接通过模型上下文协议做出授权决策——“此主体能否对 Y 执行 X？”（AuthZEN/KBAC）——并读取或写入 IndyKite Graph（ContX IQ），无需编写定制的 REST 调用。它使用 HTTP POST 上的 JSON-RPC。此技能使用无状态协议（修订版 2026-07-28 及更高版本）：无需 initialize/initialized 握手，也无需 Mcp-Session-Id——每个请求都独立完整，并在 params._meta 中携带协议元数据及标准 MCP 标头。较早的修订版（例如 2025-11-25）使用会话握手；references/architecture.md 概述了这种旧式用法。

有两个区域端点：

• 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 Agent 或 MCP 服务，这是另一款产品）；
• 正在通过 AuthZEN 或 ContX IQ 的直接 REST API调用它们（不涉及 MCP）——端点和身份验证格式都不同；
• 询问的是 MCP 规范本身，而非 IndyKite 的实现。

前提条件

在以下条件全部满足之前，MCP 服务会拒绝针对某个项目的请求：

• IndyKite 项目中存在 Application 和 AppAgent，且其 api_permissions 包含 Authorization（用于 authzen_* 工具）和 ContXIQ（用于 ciq_execute）。服务会在运行时使用此 AppAgent 调用 IndyKite API，并根据 MCP 服务配置中的 app_agent_id 在服务端解析——客户端不再发送 AppAgent 令牌。
• 项目上配置了 Token Introspect，用于验证传入的用户 Bearer 令牌。
• MCP 服务配置（POST /configs/v1/mcp-servers），用于将运行时端点绑定到 AppAgent（app_agent_id）和 Token Introspect，并声明 scopes_supported。没有此配置，针对该项目的请求会被拒绝。请参阅 references/configuration.md。
• 项目的 GID（用于 URL 路径）。
• 已采集的数据和策略：根据 Agent 将调用的工具，准备 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 访问令牌——唯一的身份验证请求头（Token Service 模式下的 Agent Gateway 可能会添加 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。将这些值存入 shell 变量：

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 主体）。

此外还可以选择添加一项：通过 Token Service 模式下的 IndyKite Agent Gateway 路由的调用方，也会携带 X-IK-Token: <delegation-token>（不带前缀），与原样保留的 Bearer 令牌一起发送。服务器会像验证 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. 发现工具和资源

调用工具前，先询问服务端有哪些可用项。以下三种方法都很实用（每种都是独立的 POST，使用相同的 _meta 和请求头，只需更改 Mcp-Method）：

• tools/list - 列出 Agent 可以调用的工具（规范列表见 references/tools.md，但请实际列出，以确认当前部署开放了哪些工具）。
• resources/list - 列出 MCP 服务开放的资源。
• resources/read，并传入 uri: "indykite://knowledge-queries/"（同时作为 Mcp-Name 请求头发送）- 提供每个 CIQ Knowledge Query 的 Agent 友好说明，包括每个查询所需的参数。

第三种方法在调用任何 ciq_execute 前尤为重要：它会告诉 Agent 应传入哪个 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 可以对哪些类型为 T 的资源执行 Y？”	authzen_search_resource
“主体 X 可以对资源 Z 执行哪些操作？”	authzen_search_action

每个工具都通过 MCP tools/call 方法调用：在 params 中，将 name 和 arguments 与 _meta 并列传入，并设置 Mcp-Method: tools/call 和 Mcp-Name: <tool name> 请求头。架构和单次调用示例见 references/tools.md。有一个不太明显的约定：当主体是已认证的调用者时，subject_id 是 Bearer token 中的 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（读取或写入）。它有两个主要参数和两个可选的分页参数：

• id - 要运行的 Knowledge Query 的 GID 或名称。
• input_params - Knowledge Query 及其策略要求的部分参数；准确的参数集合见该查询的说明。
• page_size - 可选，每页行数，默认为 100，最多为 1000（更大的值会触发校验错误：page_size exceeds maximum of 1000）。
• page_token - 可选，从 1 开始的页码（1 或省略表示第一页，2 表示下一页）；结果不会返回令牌，因此应递增页码，并在首次遇到少于 page_size 行的页面时停止。

务必先通过对 indykite://knowledge-queries/ 执行 resources/read 来发现查询，以便 Agent 传入正确的参数。

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 对象的形式返回；若服务器不支持某个协议修订版，则会返回 400，错误代码为 -32022，并指出 requested 和 supported 版本；传输问题（身份验证、连接）则会在 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。
• Agent 的作用域中包含 BEARER_TOKEN（用户 OAuth 访问令牌），并将其作为唯一的 Authorization: Bearer 身份验证请求头发送。
• server/discover 在 result.supportedVersions 中返回 2026-07-28，且任何响应中都不会出现 Mcp-Session-Id 请求头。
• tools/list 和 resources/read 在 indykite://knowledge-queries/ 上列出 Agent 可以调用的内容。
• AuthZEN 决策和 CIQ 查询结果通过 JSON-RPC 返回，且 Agent 会在其工作流中使用这些结果。

此技能中的文件

• references/architecture.md - 协议方式（无状态的 2026-07-28 与旧版会话）、使用单个 Bearer 令牌进行身份验证并在服务端解析 AppAgent，以及 RFC 9728 401 行为。
• references/configuration.md - POST /configs/v1/mcp-servers 字段参考和示例负载。
• references/tools.md - 每个 AuthZEN 和 CIQ 工具的架构与示例。
• references/troubleshooting.md - 症状与原因对照表。
• scripts/mcp-call.sh - 用于发起一次无状态 MCP 调用的 Bash 辅助脚本（为任何方法构建 _meta 对象和 MCP 请求头）。要求环境中设置 MCP_URL、PROJECT_GID、BEARER_TOKEN，且 PATH 中包含 curl。

Agent 专属说明

此技能使用通用 Markdown 指令，适用于 README 中列出的所有 Agent。它假设 Agent 可以发送 HTTP 请求（通过 Bash + curl、HTTP MCP 客户端或 SDK，例如 MCP Go SDK）。无需 Claude Code hooks、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 - 受保护资源元数据