Connecting to the Model Context Protocol (MCP) Server

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.

This allows an AI to directly query, create, update, and manage your digital twin graph in a structured and validated way.

Endpoint and Connection

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.

Endpoint URL:

https://mcp.graph.konnektr.io/mcp?resource_id={your-resource-id}

{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).

Authentication

The MCP server uses OAuth 2.1 with Dynamic Client Registration, as described in the official MCP documentation.

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.

Connecting with `npx mcp-remote`

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.

Client Configuration Example (Claude Desktop)

Here is an example of how to configure a compatible MCP client, such as Claude Desktop:

{
  "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.

Claude CLI Configuration

To add the Konnektr Graph MCP server to your Claude CLI, use the following command:

claude mcp add konnektr --transport http https://mcp.graph.konnektr.io/mcp?resource_id=your-resource-id

This command sets up the connection named konnektr using HTTP transport to the specified MCP endpoint.

Gemini CLI Configuration

For Gemini CLI, you can add the MCP server with a similar command:

gemini mcp add konnektr --transport http https://mcp.graph.konnektr.io/mcp?resource_id=your-resource-id

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.

Model Context Protocol (MCP) Server