MCP Server: Initialize Sessions and Execute Tools via HTTP

This example demonstrates the IndyKite MCP Server for AI/LLM integration:

What is MCP?

Model Context Protocol - a standard for exposing tools and resources to AI models (Claude, GPT, etc.).

IndyKite MCP Server provides:

1. Resources - List and read knowledge queries available in your project

2. Tools - Execute authorization operations:

- authzen_evaluate: Check if subject can perform action on resource

- ciq_execute: Run ContX IQ queries with parameters

Workflow:

1. Initialize session with MCP server

2. List available resources (knowledge queries)

3. List available tools (authzen_evaluate, ciq_execute)

4. Execute tools with parameters

This enables AI agents to make authorization decisions using IndyKite.

Use case

Scenario: An AI assistant needs to check user permissions and retrieve authorized data.

MCP Integration flow:

1. AI agent connects to IndyKite MCP Server

2. Initializes session -> receives capabilities and session ID

3. Lists tools -> discovers authzen_evaluate and ciq_execute

4. User asks: "Can I drive the company car?"

5. AI calls authzen_evaluate tool with:

- subject: {type: "Person", id: "user-123"}

- action: {name: "drive"}

- resource: {type: "Car", id: "car-456"}

6. MCP evaluates against KBAC policy

7. Returns: {decision: true} -> AI responds "Yes, you can drive the car"

For data retrieval:

1. User asks: "What payment methods do I have?"

2. AI calls ciq_execute tool with knowledge query ID

3. MCP runs ContX IQ query with user's authorization context

4. Returns payment method data

5. AI presents results to user

Requirements

Prerequisites:

- ServiceAccount credentials: For creating policies and queries (Bearer token)

- AppAgent credentials: For MCP server authentication (X-IK-ClientKey)

- User access token: JWT for the subject performing authorization checks

MCP Server endpoint:

- URL: https://eu.mcp.indykite.com/mcp/v1/{project_gid}

- Protocol: JSON-RPC 2.0 over HTTP POST

Required configurations:

- KBAC Policy: Defines authorization rules (e.g., who can drive cars)

- ContX IQ Policy and Query: Defines data access rules and queries

Steps

Step 1: Ingest Graph Data

- Authentication: AppAgent credential (X-IK-ClientKey header)

- Action: POST nodes (Person, Car) and relationships (DRIVES)

- Note: Replace bearer-token-sub with actual user's token subject claim

- Result: Graph ready for authorization queries

Step 2: Create ContX IQ Policy

- Authentication: ServiceAccount credential (Bearer token)

- Action: POST policy for data access through MCP

- Result: Policy ID returned

Step 3: Create ContX IQ Knowledge Query

- Authentication: ServiceAccount credential (Bearer token)

- Action: POST query with descriptive name and parameters

- Important: Include detailed description for AI agent understanding

- Result: Query ID available via MCP resources

Step 4: Create KBAC Policy

- Authentication: ServiceAccount credential (Bearer token)

- Action: POST authZEN policy (e.g., Person can DRIVE Car if DRIVES relationship exists)

- Result: Policy ID returned, available via authzen_evaluate tool

Step 5: Use MCP Server

- Initialize session: Send "initialize" JSON-RPC request

- List resources: "resources/list" returns available knowledge queries

- List tools: "tools/list" returns authzen_evaluate and ciq_execute

- Execute authzen_evaluate: Check authorization with subject/action/resource

- Execute ciq_execute: Run knowledge query with parameters

Step 1

Capture the nodes needed for this use case (replace bearer-token-sub with actual Bearer token sub).

POST https://eu.api.indykite.com/capture/v1/nodes/Json

{
  "nodes": [
    {
      "external_id": "bearer-token-sub",
      "is_identity": true,
      "type": "Person",
      "properties": [
        {
          "type": "email",
          "value": "alice@email.com"
        },
        {
          "type": "given_name",
          "value": "Alice"
        },
        {
          "type": "last_name",
          "value": "Smith"
        }
      ]
    },
    {
      "external_id": "knightrider",
      "type": "Person",
      "is_identity": true,
      "properties": [
        {
          "type": "email",
          "value": "knightrider@demo.com"
        },
        {
          "type": "name",
          "value": "Michael Knight"
        }
      ]
    },
    {
      "external_id": "satchmo",
      "type": "Person",
      "is_identity": true,
      "properties": [
        {
          "type": "email",
          "value": "satchmo@demo.com"
        },
        {
          "type": "name",
          "value": "Louis Armstrong"
        }
      ]
    },
    {
      "external_id": "karel",
      "type": "Person",
      "is_identity": true,
      "properties": [
        {
          "type": "email",
          "value": "karel@demo.com"
        },
        {
          "type": "name",
          "value": "Karel Plihal"
        }
      ]
    },
    {
      "external_id": "kitt",
      "type": "Car",
      "is_identity": false,
      "properties": [
        {
          "type": "manufacturer",
          "value": "pontiac"
        },
        {
          "type": "model",
          "value": "Firebird"
        }
      ]
    },
    {
      "external_id": "cadillacv16",
      "type": "Car",
      "is_identity": false,
      "properties": [
        {
          "type": "manufacturer",
          "value": "Cadillac"
        },
        {
          "type": "model",
          "value": "V-16"
        }
      ]
    },
    {
      "external_id": "harmonika",
      "type": "Bus",
      "is_identity": false,
      "properties": [
        {
          "type": "manufacturer",
          "value": "Ikarus"
        },
        {
          "type": "model",
          "value": "280"
        }
      ]
    },
    {
      "external_id": "listek",
      "type": "Ticket",
      "is_identity": false
    },
    {
      "external_id": "airbook-xyz",
      "type": "Laptop",
      "is_identity": false
    },
    {
      "external_id": "ole",
      "is_identity": true,
      "type": "Person",
      "properties": [
        {
          "type": "email",
          "value": "ole@yahoo.co.uk"
        },
        {
          "type": "given_name",
          "value": "ole"
        },
        {
          "type": "last_name",
          "value": "einar"
        }
      ]
    },
    {
      "external_id": "cb2563",
      "type": "PaymentMethod",
      "properties": [
        {
          "type": "payment_name",
          "value": "Credit Card Parking"
        },
        {
          "type": "preference",
          "value": "Pay as you go"
        }
      ]
    },
    {
      "external_id": "carOle",
      "type": "Vehicle",
      "properties": [
        {
          "type": "category",
          "value": "Car"
        },
        {
          "type": "is_active",
          "value": true
        },
        {
          "type": "vin",
          "value": "pcfjnm78"
        }
      ]
    },
    {
      "external_id": "licenseOle",
      "type": "LicenseNumber",
      "properties": [
        {
          "type": "status",
          "value": "Active"
        },
        {
          "type": "number",
          "value": "AL98745",
          "metadata": {
            "assurance_level": 3,
            "source": "BRREG"
          }
        }
      ]
    },
    {
      "external_id": "licenseAlice",
      "type": "LicenseNumber",
      "properties": [
        {
          "type": "status",
          "value": "Active"
        },
        {
          "type": "number",
          "value": "BTYUMN",
          "metadata": {
            "assurance_level": 3,
            "source": "BRREG"
          }
        }
      ]
    },
    {
      "external_id": "loyalty1",
      "type": "Loyalty",
      "properties": [
        {
          "type": "name",
          "value": "Parking Loyalty Plan"
        }
      ]
    },
    {
      "external_id": "consent1",
      "type": "ConsentPayment",
      "properties": [
        {
          "type": "name",
          "value": "Consent Parking"
        }
      ]
    },
    {
      "external_id": "companyParking",
      "type": "Company",
      "properties": [
        {
          "type": "name",
          "value": "City Parking Inc"
        }
      ]
    },
    {
      "external_id": "applicationParking",
      "type": "Application",
      "properties": [
        {
          "type": "name",
          "value": "City Mall Parking"
        }
      ]
    }
  ]
}

Step 2

Capture the relationships needed for this use case (replace bearer-token-sub with actual Bearer token sub).

POST https://eu.api.indykite.com/capture/v1/relationships/Json

{
  "relationships": [
    {
      "source": {
        "external_id": "knightrider",
        "type": "Person"
      },
      "target": {
        "external_id": "kitt",
        "type": "Car"
      },
      "type": "DRIVES"
    },
    {
      "source": {
        "external_id": "satchmo",
        "type": "Person"
      },
      "target": {
        "external_id": "cadillacv16",
        "type": "Car"
      },
      "type": "DRIVES"
    },
    {
      "source": {
        "external_id": "karel",
        "type": "Person"
      },
      "target": {
        "external_id": "listek",
        "type": "Ticket"
      },
      "type": "HAS"
    },
    {
      "source": {
        "external_id": "listek",
        "type": "Ticket"
      },
      "target": {
        "external_id": "harmonika",
        "type": "Bus"
      },
      "type": "FOR"
    },
    {
      "source": {
        "external_id": "karel",
        "type": "Person"
      },
      "target": {
        "external_id": "airbook-xyz",
        "type": "Laptop"
      },
      "type": "OWNS"
    },
    {
      "source": {
        "external_id": "bearer-token-sub",
        "type": "Person"
      },
      "target": {
        "external_id": "airbook-xyz",
        "type": "Laptop"
      },
      "type": "OWNS"
    },
    {
      "source": {
        "external_id": "knightrider",
        "type": "Person"
      },
      "target": {
        "external_id": "kitt",
        "type": "Car"
      },
      "type": "OWNS"
    },
    {
      "source": {
        "external_id": "bearer-token-sub",
        "type": "Person"
      },
      "target": {
        "external_id": "cadillacv16",
        "type": "Car"
      },
      "type": "DRIVES"
    },
    {
      "source": {
        "external_id": "ole",
        "type": "Person"
      },
      "target": {
        "external_id": "cb2563",
        "type": "PaymentMethod"
      },
      "type": "HAS"
    },
    {
      "source": {
        "external_id": "ole",
        "type": "Person"
      },
      "target": {
        "external_id": "carOle",
        "type": "Car"
      },
      "type": "OWNS"
    },
    {
      "source": {
        "external_id": "ole",
        "type": "Person"
      },
      "target": {
        "external_id": "loyalty1",
        "type": "Loyalty"
      },
      "type": "IS_MEMBER"
    },
    {
      "source": {
        "external_id": "bearer-token-sub",
        "type": "Person"
      },
      "target": {
        "external_id": "loyalty1",
        "type": "Loyalty"
      },
      "type": "IS_MEMBER"
    },
    {
      "source": {
        "external_id": "ole",
        "type": "Person"
      },
      "target": {
        "external_id": "consent1",
        "type": "ConsentPayment"
      },
      "type": "GRANTED"
    },
    {
      "source": {
        "external_id": "carOle",
        "type": "Car"
      },
      "target": {
        "external_id": "licenseOle",
        "type": "LicenseNumber"
      },
      "type": "HAS"
    },
    {
      "source": {
        "external_id": "consent1",
        "type": "ConsentPayment"
      },
      "target": {
        "external_id": "cb2563",
        "type": "PaymentMethod"
      },
      "type": "GRANTED"
    },
    {
      "source": {
        "external_id": "companyParking",
        "type": "Company"
      },
      "target": {
        "external_id": "applicationParking",
        "type": "Application"
      },
      "type": "OWNS"
    },
    {
      "source": {
        "external_id": "applicationParking",
        "type": "Application"
      },
      "target": {
        "external_id": "consent1",
        "type": "ConsentPayment"
      },
      "type": "USES"
    },
    {
      "source": {
        "external_id": "bearer-token-sub",
        "type": "Person"
      },
      "target": {
        "external_id": "cb8521",
        "type": "PaymentMethod"
      },
      "type": "HAS"
    },
    {
      "source": {
        "external_id": "bearer-token-sub",
        "type": "Person"
      },
      "target": {
        "external_id": "carAlice",
        "type": "Car"
      },
      "type": "OWNS"
    },
    {
      "source": {
        "external_id": "bearer-token-sub",
        "type": "Person"
      },
      "target": {
        "external_id": "consent1",
        "type": "ConsentPayment"
      },
      "type": "GRANTED"
    },
    {
      "source": {
        "external_id": "carAlice",
        "type": "Car"
      },
      "target": {
        "external_id": "licenseAlice",
        "type": "LicenseNumber"
      },
      "type": "HAS"
    },
    {
      "source": {
        "external_id": "consent1",
        "type": "ConsentPayment"
      },
      "target": {
        "external_id": "cb8521",
        "type": "PaymentMethod"
      },
      "type": "GRANTED"
    }
  ]
}

Step 2

Create a CIQ Policy which designates the Subject node, the cypher and the nodes allowed to be read.

POST https://eu.api.indykite.com/configs/v1/authorization-policiesJson

{
  "project_id": "your_project_gid",
  "description": "description of policy",
  "display_name": "policy name",
  "name": "policy-name",
  "policy": "{\"policy\":{\"meta\":{\"policy_version\":\"1.0-ciq\"},\"subject\":{\"type\":\"Person\"},\"condition\":{\"cypher\":\"MATCH (subject:Person) MATCH (app:Application)-[:USES]->(consentpayment:ConsentPayment)<-[:GRANTED]-(subject)-[:HAS]->(paymentmethod:PaymentMethod) MATCH (subject)-[:IS_MEMBER]->(loyalty:Loyalty) MATCH (subject)-[:OWNS]->(car:Car)-[:HAS]->(ln:LicenseNumber)\",\"filter\":[{\"operator\":\"AND\",\"operands\":[{\"attribute\":\"subject.external_id\",\"operator\":\"=\",\"value\":\"$subject_external_id\"},{\"attribute\":\"subject.property.email\",\"operator\":\"=\",\"value\":\"$subject_email\"}]}]},\"allowed_reads\":{\"nodes\":[\"ln.*\",\"app.*\",\"paymentmethod.external_id\"]}}}",
  "status": "ACTIVE",
  "tags": []
}

Step 3

Create a CIQ Query in the context of the policy. In the description, give all the necessary information an agent would need to know to call the ciq_execute tool.

POST https://eu.api.indykite.com/configs/v1/knowledge-queriesJson

{
  "project_id": "your_project_gid",
  "description": "Call tool 'ciq_execute' with arguments : id: \"<this query's id>\", input_params: {subject_external_id: (required) must match Bearer token 'sub', subject_email: (required), license: (required) car license plate}. Auth: Bearer token required, token subject = subject_external_id. Returns: payment_method_external_id",
  "display_name": "knowledge query name",
  "name": "knowledge-query-name",
  "policy_id": "your_policy_gid",
  "query": "{\"nodes\":[\"paymentmethod.external_id\"],\"filter\":{\"attribute\":\"ln.property.number\",\"operator\":\"=\",\"value\":\"$license\"}}",
  "status": "ACTIVE"
}

Step 4

Create a KBAC Policy which designates the conditions to drive a car.

POST https://eu.api.indykite.com/configs/v1/authorization-policiesJson

{
  "project_id": "your_project_gid",
  "description": "description of policy",
  "display_name": "policy name",
  "name": "policy-name",
  "policy": "{\"meta\":{\"policy_version\":\"2.0-kbac\"},\"subject\":{\"type\":\"Person\"},\"actions\":[\"CAN_DRIVE\"],\"resource\":{\"type\":\"Car\"},\"condition\":{\"cypher\":\"MATCH (subject:Person)-[:DRIVES]->(resource:Car)\"}}",
  "status": "ACTIVE",
  "tags": []
}