konnektr-io · nikoraes · Jan 4, 2026 · Jan 4, 2026
diff --git a/content/docs/graph/concepts/event-routing.mdx b/content/docs/graph/concepts/event-routing.mdx
@@ -216,7 +216,7 @@ Full CloudEvents 1.0 format with complete event details. Use for real-time monit
 ```json
 {
   "specversion": "1.0",
-  "type": "Konnektr.DigitalTwins.Twin.Update",
+  "type": "Konnektr.Graph.Twin.Update",
   "source": "https://my-instance.api.graph.konnektr.io",
   "id": "550e8400-e29b-41d4-a716-446655440000",
   "time": "2025-01-20T10:30:00Z",
@@ -236,7 +236,7 @@ Full CloudEvents 1.0 format with complete event details. Use for real-time monit
 | Attribute | Description |
 |-----------|-------------|
 | `specversion` | CloudEvents version (always "1.0") |
-| `type` | Event type (e.g., `Konnektr.DigitalTwins.Twin.Update`) |
+| `type` | Event type (e.g., `Konnektr.Graph.Twin.Update`) |
 | `source` | URI of the Konnektr Graph instance |
 | `id` | Unique event identifier (UUID) |
 | `time` | ISO 8601 timestamp when event occurred |

diff --git a/content/docs/graph/concepts/mcp-server.mdx b/content/docs/graph/concepts/mcp-server.mdx
@@ -1,135 +1,99 @@
 ---
-title: MCP Server
-icon: Server
+title: Model Context Protocol (MCP) Server
+icon: Cpu
 ---
 
-The AgeDigitalTwins MCP Server allows LLMs to interact with a semantic graph memory based on Azure Digital Twins (DTDL) and Apache AGE (PostgreSQL). This enables building "self-healing" AI memory systems that enforce data schema and support hybrid vector search.
+# Connecting to the Model Context Protocol (MCP) Server
 
-## Authentication & Authorization
+The Model Context Protocol (MCP) provides a standardized way for AI models and agents to interact with external tools and services. Konnektr Graph includes a built-in MCP server that exposes the Digital Twin capabilities as a set of tools that an AI agent can use.
 
-The MCP Server uses OAuth 2.1 with JWT Bearer tokens for authentication and policy-based authorization for access control.
+This allows an AI to directly query, create, update, and manage your digital twin graph in a structured and validated way.
 
-### Requirements
+## Endpoint and Connection
 
-To access the MCP server, clients must provide:
+The shared MCP server is a single endpoint for all Konnektr Graph instances. You specify which graph instance you want to connect to by using the `resource_id` query parameter.
 
-1. **OAuth Scope**: `mcp:tools` - Required by the MCP OAuth 2.1 specification (RFC 9728)
-2. **Permission**: `mcp/*` - Application-level permission to access MCP tools
-
-### How It Works
-
-```
-Request with JWT Token
-  ↓
-1. JWT Authentication - Validates token from Auth0
-  ↓
-2. OAuth Scope Check - Verifies "mcp:tools" scope (MCP-specific)
-  ↓
-3. Permission Check - Verifies "mcp/*" permission (policy-based)
-  ↓
-4. Tool Execution
+**Endpoint URL:**
 ```
-
-For detailed information about the authorization architecture, see [Authorization Architecture](/docs/advanced-topics/authorization-architecture).
-
-### Configuration
-
-```json
-{
-  "Authentication": {
-    "Enabled": true,
-    "Authority": "https://auth.konnektr.io",
-    "Audience": "https://graph.konnektr.io",
-    "Issuer": "https://auth.konnektr.io/"
-  },
-  "Authorization": {
-    "Enabled": true,
-    "Provider": "Claims",
-    "PermissionsClaimName": "permissions",
-    "RequiredScopes": ["mcp:tools"],
-    "ScopesSupported": ["mcp:tools", "mcp:resources"]
-  }
-}
+https://mcp.graph.konnektr.io/mcp?resource_id={your-resource-id}
 ```
 
-### OAuth Discovery
+- **`{your-resource-id}`**: The unique identifier for your Konnektr Graph instance.
+- **Transport**: The server supports `http_stream` (also known as Server-Sent Events or SSE).
 
-The server implements RFC 9728 (Protected Resource Metadata) at `/.well-known/oauth-protected-resource` for OAuth client discovery.
+## Authentication
 
-## Features
+The MCP server uses **OAuth 2.1 with Dynamic Client Registration**, as described in the [official MCP documentation](https://modelcontextprotocol.io/docs/tutorials/security/authorization).
 
-### 1. Model Management
-The server provides tools to understand the semantic data model:
-- `GetModels`: Returns a lightweight summary of available models (ID and Display Name). Use this to explore the domain.
-- `GetModel`: Returns the **fully flattened** DTDL definition of a specific model. This includes all inherited properties, relationships, and components from base models, giving the LLM a complete view of the schema without needing to traverse the inheritance hierarchy manually.
-- `SearchModels`: Performs a hybrid search (semantic vector + lexical keyword) to find relevant models.
-- `CreateModels`: Allows creating new DTDL models.
-- `UpdateModelEmbedding`: Updates the vector embedding for a model to enable semantic search.
+This is a secure, user-friendly approach that **does not require you to manually manage `client_id` or `client_secret`**. When your MCP client connects for the first time, it will be guided through a one-time browser-based authorization flow to grant access.
 
-### 2. Cypher Query Generation
-The server is designed to help LLMs generate optimized Cypher queries for Apache AGE.
-- **Nodes**: Digital Twins always have the `:Twin` label. Models have the `:Model` label.
-- **Inheritance**: To query twins of a specific model *and* its sub-types, use the optimized pattern:
-  ```cypher
-  MATCH (m1:Model {id: 'dtmi:example:TargetModel;1'})<-[:_extends*0..]-(m2:Model)
-  WITH collect(m2.id) AS model_ids
-  MATCH (t:Twin)
-  WHERE t.`$metadata`.`$model` IN model_ids
-  RETURN t
-  ```
-- **Validation**: The system enforces DTDL schema validation on all writes (`CreateOrReplaceDigitalTwin`, `UpdateDigitalTwin`), ensuring data integrity.
+## Connecting with `npx mcp-remote`
 
-### 3. Vector / Hybrid Search
-The system supports semantic search using `pgvector`.
-- **Definition**: Vector properties are defined in DTDL as `Array<Double>` with a semantic description (e.g., "embedding").
-- **Search Tool**: Use the `HybridMemorySearch` tool to perform similarity searches combined with metadata filtering.
-- **Manual Query**: 
-  ```cypher
-  MATCH (t:Twin)
-  WHERE t.`$metadata`.`$model` = 'dtmi:example:MyModel;1'
-  RETURN t
-  ORDER BY l2_distance(t.embedding, [0.1, 0.2, ...]::vector) ASC
-  LIMIT 5
-  ```
+For MCP clients that do not natively support remote HTTP endpoints or the OAuth 2.1 flow (e.g., some versions of Claude Desktop), you can use the `mcp-remote` tool to create a secure local proxy.
 
-### 4. Graph Exploration
-- `ExploreGraphNeighborhood`: Quickly retrieve the subgraph surrounding a specific twin to understand context.
+### Client Configuration Example (Claude Desktop)
 
-## Hosted MCP Server
+Here is an example of how to configure a compatible MCP client, such as Claude Desktop:
 
-Konnektr Graph provides a fully managed, hosted MCP server for every "Standard" tier instance.
-
-- **URL Format**: `https://{resource-id}.mcp.graph.konnektr.io`
-- **Authentication**: Uses the same OAuth 2.1 credentials and JWT tokens as the Konnektr API.
-- **Transport**: Supports both `http` and `sse` (Server-Sent Events) for real-time streaming.
-- **Demo Instance**: A public demo is available at `demo.mcp.graph.konnektr.io` for testing without authentication.
-
-For a step-by-step tutorial on building AI-driven memory systems, see the [How to Build a Business Twin with MCP](/docs/how-to-guides/mcp-server-business-twin) guide.
-
-## Usage Guide for Agents
+```json
+{
+  "mcpServers": {
+    "konnektr": {
+      "command": "npx",
+      "args": ["-y", "mcp-remote", "https://mcp.graph.konnektr.io/mcp?resource_id=your-resource-id"]
+    }
+  }
+}
+```
+The client only needs to know the URL and that the authentication type is `oauth2`. The rest is handled automatically.
 
-### Prerequisites
+### Claude CLI Configuration
 
-Before using the MCP server, ensure you have:
-- Valid OAuth 2.1 JWT token from Auth0
-- `mcp:tools` scope in your token
-- `mcp/*` permission in your token claims
+To add the Konnektr Graph MCP server to your Claude CLI, use the following command:
 
-### Workflow
+```bash
+claude mcp add konnektr --transport http https://mcp.graph.konnektr.io/mcp?resource_id=your-resource-id
+```
 
-1. **Understand the Domain**: Call `GetModels` to see what types of entities exist.
-2. **Inspect Schema**: Call `GetModel(modelId)` to understand the properties and relationships of a specific type.
-3. **Search**: 
-   - Use `HybridMemorySearch` if you have a vector or need semantic similarity.
-   - Use `ExploreGraphNeighborhood` to walk the graph.
-   - For complex queries, generate Cypher using the `GenerateQueryPrompt` guidance.
+This command sets up the connection named `konnektr` using HTTP transport to the specified MCP endpoint.
 
-### Error Handling
 
-The server returns standard OAuth 2.1 error responses:
+### Gemini CLI Configuration
+For Gemini CLI, you can add the MCP server with a similar command:
 
-- **401 Unauthorized**: Missing or invalid JWT token
-- **403 Forbidden (insufficient_scope)**: Missing required OAuth scope
-- **403 Forbidden**: Missing required permission
+```bash
+gemini mcp add konnektr --transport http https://mcp.graph.konnektr.io/mcp?resource_id=your-resource-id
+```
 
-All responses include the `/.well-known/oauth-protected-resource` URL for client configuration discovery.
+## Available Tools
+
+When an AI agent connects to the MCP server, it gains access to a suite of tools to interact with the digital twin graph.
+
+### Model Management
+- **`create_model`**: Creates a new DTDL model.
+- **`delete_model`**: Deletes a DTDL model.
+- **`get_model`**: Retrieves the full definition of a single DTDL model.
+- **`list_models`**: Lists all DTDL models in the graph.
+- **`search_models`**: Searches for DTDL models.
+
+### Digital Twin Management
+- **`create_or_replace_digital_twin`**: Creates or replaces a digital twin.
+- **`delete_digital_twin`**: Deletes a digital twin.
+- **`get_digital_twin`**: Retrieves a digital twin by its ID.
+- **`update_digital_twin`**: Updates a twin's properties using a JSON Patch.
+- **`search_digital_twins`**: Performs a semantic search for twins.
+
+### Relationship Management
+- **`create_or_replace_relationship`**: Creates or replaces a relationship between two twins.
+- **`delete_relationship`**: Deletes a relationship.
+- **`get_relationship`**: Retrieves a specific relationship.
+- **`list_relationships`**: Lists all outgoing relationships from a twin.
+- **`update_relationship`**: Updates a relationship's properties using a JSON Patch.
+
+### Querying
+- **`query_digital_twins`**: Executes a Cypher query against the graph.
+
+## See Also
+- [How-to Guide: Build a Business Twin with MCP](/how-to-guides/mcp-server-business-twin)
+- [Digital Twins Definition Language (DTDL)](/concepts/dtdl)
+- [Querying the Graph](/concepts/querying)
diff --git a/content/docs/graph/concepts/meta.json b/content/docs/graph/concepts/meta.json
@@ -4,11 +4,11 @@
     "description": "Core concepts and fundamental understanding of Konnektr Graph",
     "pages": [
         "dtdl",
+        "mcp-server",
         "querying",
         "validation",
         "event-routing",
         "telemetry",
-        "components",
-        "mcp-server"
+        "components"
     ]
 }
diff --git a/content/docs/graph/how-to-guides/mcp-server-business-twin.mdx b/content/docs/graph/how-to-guides/mcp-server-business-twin.mdx
@@ -13,49 +13,45 @@ In this example, we will model a **Smart Equipment System**, tracking **Employee
 
 ## Prerequisites
 
-* **Konnektr Graph Standard Instance**: The MCP server is available on "Standard" and higher tiers.
-* **API Credentials**: You'll need a Client ID and Secret from the [Konnektr Control Plane](https://ktrlplane.konnektr.io).
-* **An MCP Client**: Claude Desktop, Gemini, or any MCP-compliant application.
+*   A **Konnektr Graph** instance. The MCP server is available on "Standard" and higher tiers.
+*   An **MCP Client** (e.g., Claude CLI, Claude Desktop, Gemini) that supports OAuth 2.1 or the `npx` command-line tool.
 
 ---
 
 ## Part 1: Connecting to the Hosted MCP Server
 
-Every Konnektr Graph resource has its own dedicated MCP endpoint.
+Your Konnektr Graph instance is accessible via the shared, secure MCP endpoint.
 
 ### 1. Identify Your Endpoint
-Your MCP server is hosted at:
-`https://{resource-id}.mcp.graph.konnektr.io`
+The MCP server is hosted at:
+`https://mcp.graph.konnektr.io/mcp?resource_id={your-resource-id}`
+
+You must replace `{your-resource-id}` with the actual ID of your Konnektr Graph instance.
 
 ### 2. Configure Your Client
-The Hosted MCP Server uses OAuth 2.1 authentication—the same credentials you use for the Konnektr API.
+The MCP Server uses **OAuth 2.1 with Dynamic Client Registration**. You don't need to provide a `client_id` or `client_secret`. Your client will guide you through a one-time browser login to authorize access.
+
+**For Claude CLI:**
+
+```bash
+claude mcp add konnektr-graph --transport http https://mcp.graph.konnektr.io/mcp?resource_id=your-resource-id
+```
+
+**For Claude Desktop (and similar clients):**
 
-Add this to your `claude_desktop_config.json` (or equivalent client config):
+Edit your `claude_desktop_config.json` (or equivalent) with this simplified configuration:
 
 ```json
 {
   "mcpServers": {
     "konnektr": {
-      "url": "https://your-resource-id.mcp.graph.konnektr.io",
-      "transport": {
-        "type": "sse"
-      },
-      "auth": {
-        "type": "oauth2",
-        "token_url": "https://auth.konnektr.io/oauth/token",
-        "client_id": "YOUR_CLIENT_ID",
-        "client_secret": "YOUR_CLIENT_SECRET",
-        "audience": "https://graph.konnektr.io",
-        "scope": "mcp:tools"
-      }
+      "command": "npx",
+      "args": ["-y", "mcp-remote", "https://mcp.graph.konnektr.io/mcp?resource_id=your-resource-id"]
     }
   }
 }
 ```
 
-> [!TIP]
-> **Try the Demo:** You can test the platform using our public demo instance at `demo.mcp.graph.konnektr.io` which requires no authentication.
-
 ---
 
 ## Part 2: Prompt Engineering for Twins
@@ -97,9 +93,8 @@ The LLM can also perform complex analysis by writing Cypher queries. However, it
 
 ### The Query Workflow
 
-1. **Understand the Schema:** The LLM should first understand the structure of the graph by calling `get_model`.
-2. **Get the Query Rules:** The LLM should call `get_prompt(name: "GenerateQueryPrompt")`. This provides the rules for optimized Cypher on the AgeDigitalTwins platform (e.g., using `:Twin` labels and handling DTDL inheritance).
-3. **Execute:** The LLM then writes and runs the query using `query_digital_twins`.
+1. **Understand the Schema:** The LLM should first understand the structure of the graph by calling `list_models`.
+3. **Execute:** The LLM then writes and runs the query using `query_digital_twins` (the documentation for the tool includes the query rules).
 
 **User Prompt:**
 > "Who in the R&D department is holding high-performance computing assets? Search for assets mentioning 'DGX' or 'Computing'."