MCP Server Guide

Overview

Kartograph provides an MCP (Model Context Protocol) server at /query/mcp that enables AI agents to query the knowledge graph using openCypher and discover the graph schema.

Connection

Provided that you have started the Kartograph development server, the Kartograph MCP server can be registered with Claude Code:

claude mcp add --transport http kartograph http://localhost:8000/query/mcp

Resources

Resources provide read-only access to graph schema information.

schema://ontology

Complete graph ontology with all type definitions.

Returns:

{
  "type_definitions": [
    {
      "label": "person",
      "entity_type": "node",
      "description": "A person entity representing an individual",
      "required_properties": ["name"],
      "optional_properties": ["email", "role"]
    }
  ],
  "count": 1
}

schema://nodes/labels

List of all node type labels.

Returns:

{
  "labels": ["person", "project", "repository"],
  "count": 3
}

schema://edges/labels

List of all edge type labels.

Returns:

{
  "labels": ["knows", "depends_on", "contributes_to"],
  "count": 3
}

schema://nodes/{label}

Detailed schema for a specific node type.

Example: schema://nodes/person

Returns:

{
  "label": "person",
  "entity_type": "node",
  "description": "A person entity",
  "example_file_path": "people/alice.md",
  "required_properties": ["name"],
  "optional_properties": ["email", "role"]
}

schema://edges/{label}

Detailed schema for a specific edge type.

Example: schema://edges/knows

Returns:

{
  "label": "knows",
  "entity_type": "edge",
  "description": "Professional relationship",
  "required_properties": ["since"],
  "optional_properties": []
}

Tools

query_graph

Execute read-only Cypher queries against the knowledge graph.

Parameters:

• cypher (string, required) - Cypher query to execute
• timeout_seconds (int, default: 30, max: 60) - Query timeout
• max_rows (int, default: 1000, max: 10000) - Maximum results

Apache AGE Single-Column Requirement

Due to limitations with how Apache AGE handles Cypher queries, all queries must be written to return a single column. Multiple values can be returned by using map syntax to return a single column that contains multiple values:

// Single value
MATCH (p:Person) RETURN p

// Multiple values - use map
MATCH (a:Person)-[r:KNOWS]->(b:Person)
RETURN {source: a, relationship: r, target: b}

Example Request:

{
  "cypher": "MATCH (p:Person) RETURN p LIMIT 5",
  "timeout_seconds": 30,
  "max_rows": 100
}

Success Response:

{
  "success": true,
  "rows": [
    {"node": {"id": "person:abc123", "label": "Person", "properties": {"name": "Alice"}}}
  ],
  "row_count": 1,
  "truncated": false,
  "execution_time_ms": 42.5
}

Error Response:

{
  "success": false,
  "error_type": "forbidden",
  "message": "Query must be read-only. Found forbidden keyword: CREATE"
}

Workflow

1. Use schema://nodes/labels and schema://edges/labels to discover available types
2. Use schema://nodes/{label} or schema://edges/{label} to understand type properties
3. Write Cypher queries using query_graph tool based on the schema