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 any AI Agent that supports HTTP MCP servers. Here we provide detailed instructions for Claude Code and Cursor configuration.

Claude Code

Add the Kartograph MCP server to Claude Code by running this command in your terminal.

claude mcp remove kartograph # Remove any prior versions
claude mcp add \
  --transport http \
  kartograph \
  http://localhost:8000/query/mcp \
  --scope user # Allow access from any project

Kartograph supports fetching some raw data from GitHub and GitLab. If you wish to enable this functionality, you must pass in access tokens from each service when adding the MCP server.

The tokens must have read repository access.

claude mcp remove kartograph # Remove any prior versions
claude mcp add \
  --transport http \
  kartograph \
  http://localhost:8000/query/mcp \
  --header "x-github-pat: <your-pat-here>" \
  --header "x-gitlab-pat: <your-token-here>" \
  --scope user # Allow access from any project

Cursor

Open Cursor Settings

Open Cursor settings by typing Command + Shift + J Control + Shift + J , or via menu: File -> Preferences -> Cursor Settings.
Select Tools & MCP

In the Cursor Settings left sidebar, select Tools & MCP.
Open MCP Server Settings

Depending on whether you have previously added an MCP server to Cursor, either click “Add Custom MCP” or “New MCP Server” (at the bottom of the server list.)

This will open up Cursor’s mcp.json settings file. This file will either contain configuration for existing MCP servers, or an empty object like:
```
 {
   "mcpServers": {}
 }
```

Add Kartograph MCP Server Configuration

To add Kartograph’s MCP server to cursor, add the following JSON object inside the existing mcpServers object:

"kartograph": {
   "url": "http://localhost:8000/query/mcp",
   "headers": {
     "x-github-pat": "<your-pat-here>",
     "x-gitlab-pat": "<your-token-here>"
   }
 }

The full file should look something like:

 {
   "mcpServers": {
       "kartograph": {
       "url": "http://localhost:8000/query/mcp",
       "headers": {
         "x-github-pat": "<your-pat-here>",
         "x-gitlab-pat": "<your-token-here>"
       }
     }
   }
 }

Save the File

To finish adding the Kartograph MCP server to Cursor, save the mcp.json and re-open Cursor Settings -> Tools & MCP.

Here, you should see the Kartograph MCP server listed, as shown below.

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

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"
}