indykite-mcp-server

IndyKite MCP Server

The IndyKite MCP server exposes IndyKite's authorization (AuthZEN/KBAC) and graph-data (ContX IQ) capabilities to AI agents through the Model Context Protocol. It speaks JSON-RPC over HTTP POST and uses the standard MCP session model (initialize → Mcp-Session-Id → subsequent calls).

Two regional endpoints exist:

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

The full URL for one project is <MCP_REGIONAL_URL>/mcp/v1/<project_gid>.

When to use

Activate this skill when the user:

• needs to call the IndyKite MCP server (initialize a session, list tools/resources, or call AuthZEN/CIQ tools);
• is configuring an MCP server for a project (POST /configs/v1/mcp-servers) and needs the field set;
• is debugging a 401 that returned .well-known/oauth-protected-resource metadata - almost always a missing or invalid Authorization: Bearer token;
• is wiring an LLM client (Claude Code, Cursor, Goose, the MCP Go SDK, etc.) into the IndyKite MCP and needs the request shape;
• is choosing between authzen_evaluate, authzen_evaluations, authzen_search_resource, authzen_search_action, and ciq_execute.

Do not activate this skill when the user:

• is asking about the IndyKite Agent Gateway (use the indykite-agent-gateway skill - IAG protects A2A agents, not MCP);
• is calling AuthZEN or ContX IQ over their direct REST APIs (no MCP session involved) - different endpoints, different auth shape;
• is asking about the MCP specification itself rather than the IndyKite implementation.

Prerequisites

The MCP server will reject requests for a project until all of the following exist:

• An IndyKite project with an Application, AppAgent, and AppAgent credentials (the AppAgent token is what goes into X-IK-ClientKey).
• A Token Introspect configuration on the project - used to validate inbound user Bearer tokens.
• An MCP server configuration (POST /configs/v1/mcp-servers) that binds the runtime endpoint to the AppAgent and Token Introspect, and declares scopes_supported. Without this configuration, requests for the project are rejected. See references/configuration.md.
• The project's GID (used in the URL path).
• Captured data and policies: KBAC and/or CIQ policies and Knowledge Queries, depending on which tools the agent will call.

If any of these are missing, stop and tell the user - fixing them first is much cheaper than debugging an opaque MCP rejection.

Steps

1. Resolve the URL and credentials

Build the full MCP URL: <MCP_URL>/mcp/v1/<project_gid> where <MCP_URL> is https://eu.mcp.indykite.com or https://us.mcp.indykite.com. Get two values into shell variables:

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

Both layers are required on every call after initialize. See references/architecture.md for the rationale (one identifies the application, the other identifies the user as the AuthZEN subject).

2. Initialize the session

Send an initialize request and capture the Mcp-Session-Id response header. This is the only call that does not need a session id, but it does need both auth headers.

curl -s -i -X POST "$MCP_URL/mcp/v1/$PROJECT_GID" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $BEARER_TOKEN" \
  -H "X-IK-ClientKey: $API_KEY" \
  -d '{
        "jsonrpc": "2.0",
        "id": 1,
        "method": "initialize",
        "params": {
          "protocolVersion": "2025-11-25",
          "capabilities": {},
          "clientInfo": {"name": "curl", "version": "1.0"}
        }
      }'

Save the Mcp-Session-Id header value into SESSION_ID. The helper scripts/init-session.sh does exactly this and prints the session id on stdout.

3. Confirm initialization

Send the notifications/initialized JSON-RPC notification with the session id. This signals the server that the client is ready to issue tool/resource calls.

curl -s -X POST "$MCP_URL/mcp/v1/$PROJECT_GID" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $BEARER_TOKEN" \
  -H "X-IK-ClientKey: $API_KEY" \
  -H "Mcp-Session-Id: $SESSION_ID" \
  -d '{
        "jsonrpc": "2.0",
        "id": 2,
        "method": "notifications/initialized",
        "params": {
          "protocolVersion": "2025-11-25",
          "capabilities": {},
          "clientInfo": {"name": "curl", "version": "1.0"}
        }
      }'

4. Discover tools and resources (optional but recommended)

Before calling tools, ask the server what's available. Three useful methods:

• resources/list - what resources the MCP server exposes.
• tools/list - what tools the agent may call (the canonical set is in references/tools.md, but list it to verify what this deployment exposes).
• resources/read with uri: "indykite://knowledge-queries/" - agent-friendly descriptions of every CIQ Knowledge Query, including the parameters each one expects.

The third one is especially important before any ciq_execute call: it tells the agent which id to pass and what input_params shape the query expects.

5. Call AuthZEN tools

For authorization decisions, pick the right tool for the question:

Question	Tool
"Can subject X do action Y on resource Z?"	authzen_evaluate
"Run several of those checks at once"	authzen_evaluations
"Which resources of type T can subject X do Y on?"	authzen_search_resource
"Which actions can subject X do on resource Z?"	authzen_search_action

Each tool is invoked through the MCP tools/call method with name and arguments. Schemas and one-call examples are in references/tools.md. One non-obvious convention: when the subject is the authenticated caller, subject_id is the sub claim of the Bearer token, not a separately-supplied user identifier.

6. Call CIQ tools

ciq_execute runs a Knowledge Query against the IndyKite Graph (read or write). Two arguments:

• id - GID or name of the Knowledge Query to run.
• input_params - the partial parameters from the Knowledge Query and its policy; the exact set is documented in the query's description.

Always discover queries first via resources/read on indykite://knowledge-queries/ so the agent passes the right parameters.

7. Read, interpret, and audit responses

JSON-RPC responses come back with id matching the request, result on success, or error on failure. For AuthZEN, the meaningful payload is the decision plus any reason; for CIQ, it is the rows the query returned. Service-side errors (configuration broken, scopes missing) usually surface as JSON-RPC error objects, while transport problems (auth, connectivity) come back as HTTP 4xx/5xx before JSON-RPC even runs - see references/troubleshooting.md.

Outcome

When this skill has been applied successfully:

• An MCP server configuration exists for the project and enabled is true.
• The agent has API_KEY (AppAgent token) and BEARER_TOKEN (user OAuth access token) in scope, and knows which goes in which header.
• An initialize call returns a usable Mcp-Session-Id.
• tools/list and resources/read on indykite://knowledge-queries/ enumerate what the agent can call.
• AuthZEN decisions and CIQ query results come back over JSON-RPC and the agent uses them in its workflow.

Files in this skill

• references/architecture.md - protocol and session model, two-layer auth, RFC 9728 401 behavior.
• references/configuration.md - POST /configs/v1/mcp-servers field reference and example payload.
• references/tools.md - schemas and examples for every AuthZEN and CIQ tool.
• references/troubleshooting.md - symptom-to-cause map.
• scripts/init-session.sh - Bash helper that initializes a session and prints the resulting Mcp-Session-Id. Requires MCP_URL, PROJECT_GID, API_KEY, BEARER_TOKEN in the environment, and curl + awk on PATH.

Agent-specific notes

This skill uses generic markdown instructions and works across all agents listed in the README. It assumes the agent can issue HTTP requests (Bash + curl, an HTTP MCP client, or an SDK such as the MCP Go SDK). No Claude Code hooks, Cursor @-mentions, or Copilot workspace context are required.

References

• How to use the MCP server (IndyKite developer hub)
• Model Context Protocol specification
• MCP Go SDK
• POST /mcp-servers API reference
• POST /token-introspects API reference
• POST /application-agent-credentials API reference
• RFC 9728 - Protected Resource Metadata