Introduction

Build agentic graph queries that evolve step-by-step without rebuilding from scratch. HelixDB’s MCP endpoints provide a stateful, incremental query session via a connection_id, so each call extends the same traversal. This allows agents to chain and build complex traversal and filter queries over time while being able to view intermediate results. Stream results with mcp/next or batch with mcp/collect. You can also dynamically pass lists created at runtime, toggle AND/OR property groups, and filter by temporary traversals. Run multiple traversals in concurrently and asynchronously using multiple connection IDs by initializing each traversal with its own connection_id to keep them separate and easy to manage.

MCP Tools

These tools are used to manage the MCP connection and interact with the MCP endpoints.

Initialization `init`

Endpoint `"mcp/init"`

Creates a new MCP connection, which is a blank traversal. The request for this endpoint is empty ({}). Response Format

"<connection-id>"

Iterate Results `next`

Endpoint `"mcp/next"`

Returns the next item in the MCP traversal results. Request Format

{
    "connection_id": "<connection-id>"
}

connection_id

string

required

Connection ID of the MCP connection

Response Format

{<node-edge-data>}

Collect Results `collect`

Endpoint `"mcp/collect"`

Collects all the results from the MCP traversal. Request Format

{
    "connection_id": "<connection-id>", 
    "range": {"start": <start-index>, "end": <end-index>}, 
    "drop" : <true-false>
}

connection_id

string

required

Connection ID of the MCP connection

range

json

Range of results to collect (default: {"start": 0, "end": -1})

drop

boolean

Resets the traversal after collecting results (default: true)

Response Format

[
    {<node-edge-data>},
    ...
]

Reset Connection `reset`

Endpoint `"mcp/reset"`

Resets the MCP connection with the given connection ID to a blank traversal. Request Format

{"connection_id": "<connection-id>"}

connection_id

string

required

Connection ID of the MCP connection

Response Format

"<connection-id>"

Schema Context `schema_resource`

Endpoint `"mcp/schema_resource"`

Returns the schema and query information of the database for LLM context. Request Format

{"connection_id": "<connection-id>"}

connection_id

string

required

Connection ID of the MCP connection

Response Format

{
    "schema": {
        "nodes": [
            {
                "name": "<node-name>",
                "properties": {
                    "<property-name>": "<property-type>",
                    ...
                }
            },
            ...
        ],
        "vectors": [
            {
                "name": "<vector-name>",
                "properties": {
                    "<property-name>": "<property-type>",
                    ...
                }
            },
            ...
        ],
        "edges": [
            {
                "name": "<edge-name>",
                "properties": {
                    "<property-name>": "<property-type>",
                    ...
                }
            },
            ...
        ]
    },
    "queries": [
        {
            "name": "<query-name>",
            "parameters": {
                "<parameter-name>": "<parameter-type>",
                ...
            },
            "returns": [
                "<return-variable-name>",
                ...
            ]
        }
    ]
}

MCP Traversals

These tools are used to dynamically traverse the graph and retrieve nodes and edges. However, they do not return the results of the traversal.

Retrieve Nodes `n_from_type`

Endpoint `"mcp/n_from_type"`

Retrieves all nodes of a given type. Request Format

{"connection_id": "<connection-id>", "data": {"node_type": "<node-type>"}}

connection_id

string

required

Connection ID of the MCP connection

node_type

string

required

The label of node to retrieve (name in schema)

Retrieve Edges `e_from_type`

Endpoint `"mcp/e_from_type"`

Retrieves all edges of a given type. Request Format

{"connection_id": "<connection-id>", "data": {"edge_type": "<edge-type>"}}

connection_id

string

required

Connection ID of the MCP connection

edge_type

string

required

The label of edge to retrieve (name in schema)

Out `out_step`

Endpoint `"mcp/out_step"`

Traverses out from current nodes or vectors in the traversal with the given edge type to nodes or vectors. Assumes that the current state of the traversal is a collection of nodes or vectors that is the source of the given edge type and label. Request Format

{
    "connection_id": "<connection-id>",
    "data": {"edge_type": "<edge-type>", "edge_label": "<edge-label>"}
}

connection_id

string

required

Connection ID of the MCP connection

edge_type

string

required

The target entity (node or vec)

edge_label

string

required

The label of edge to traverse out (name in schema)

OutE `out_e_step`

Endpoint `"mcp/out_e_step"`

Traverses out from current edges to their target nodes or vectors. Assumes that the current state of the traversal is a collection of edges with the target of the given edge label. Request Format

{"connection_id": "<connection-id>", "data": {"edge_label": "<edge-label>"}}

connection_id

string

required

Connection ID of the MCP connection

edge_label

string

required

The label of edge to traverse out (name in schema)

In `in_step`

Endpoint `"mcp/in_step"`

Traverses into the current nodes or vectors in the traversal with the given edge type to nodes or vectors. Assumes that the current state of the traversal is a collection of nodes or vectors that is the target of the given edge type and label. Request Format

{
    "connection_id": "<connection-id>", 
    "data": {"edge_type": "<edge-type>", "edge_label": "<edge-label>"}
}

connection_id

string

required

Connection ID of the MCP connection

edge_type

string

required

The source entity (node or vec)

edge_label

string

required

The label of edge to traverse into (name in schema)

InE `in_e_step`

Endpoint `"mcp/in_e_step"`

Traverses into the current edges to their source nodes or vectors. Assumes that the current state of the traversal is a collection of edges with the source of the given edge label. Request Format

{"connection_id": "<connection-id>", "data": {"edge_label": "<edge-label>"}}

connection_id

string

required

Connection ID of the MCP connection

edge_label

string

required

The label of edge to traverse into (name in schema)

MCP Filter Tool

Filter `filter_items`

Endpoint `"mcp/filter_items"`

Filters the current state of the traversal. Request Format

{
    "connection_id": "<connection-id>", 
    "data": {"filter": <filters>}
}

Where filters is a list of filters to apply to the current state of the traversal. The format of the filters is as follows:

// Filter layer
{
    "properties" : [
        <property-filters>,
        ...
    ],
    "filter_traversals" : [
        <traversal-filters>,
        ...
    ]
}

Property Filter

The property filter is used to filter the current state of the traversal by the properties of the entity. The outer list is the OR operation and the inner list is the AND operation.

// OR layer
"properties" : [
    // AND layer
    [
        // Filters
        {"key": "<property-name>", "operator": "<operator>", "value": "<property-value>"},
        ...
    ],
    ...
]

key

string

required

The name of the property to filter on

operator

string

required

The operator to use for the filter

value

string | [string]

required

The value to filter on

Operators

Operator	Description	Operator	Description
`==`	equals	`!=`	not equals
`>`	greater than	`>=`	greater than or equal to
`<`	less than	`<=`	less than or equal to

List to value and value to list comparisons will use the OR operator for each element in the list.
List to list comparisons will also use the OR operator for each element in each list.This allows for using contains and not_contains operators by using the == and != operator with a list of values.

Traversal Filter

The traversal filter is used to filter the current state of the traversal by the results of a traversal. It doesn’t actually change the state of the current traversal, it just temporarily traverses and checks the results of the traversal. You can have nested filters in the inner filter layer, which can include property and traversal filters with the same structure. The traversal filter only has an AND operation.

// AND layer
"filter_traversals" : [
    {
        // Traversal tool name
        "tool_name" : "<tool-name>",
        // Traversal tool args
        "args" : {
            "<parameter-name>" : "<parameter-value>",
            ...,
            // Inner filter layer
            "filter" : {
                "properties" : [
                    <property-filters>,
                    ...
                ],
                "filter_traversals" : [
                    <traversal-filters>,
                    ...
                ]
            }
        }
    },
    ...
]

MCP Aggregation Tools

Group `group_by`

Endpoint `"mcp/group_by"`

Groups the current state of the traversal by the given properties. It returns a list of unique property combinations and their count. Request Format

{
    "connection_id": "<connection-id>", 
    "properties": ["<property-name>", ...]
}

connection_id

string

required

Connection ID of the MCP connection

properties

[string]

required

The properties to group by

Response Format

[
    {<property-name>: <property-value>, ... , "count": <count>},
    ...
]

Aggregate `aggregate_by`

Endpoint `"mcp/aggregate_by"`

Aggregates the current state of the traversal by the given properties. It returns a list of groups of jsons each with a count and data as a list of items in that group. Request Format

{
    "connection_id": "<connection-id>", 
    "properties": ["<property-name>", ...]
}

connection_id

string

required

Connection ID of the MCP connection

properties

[string]

required

The properties to aggregate by

Response Format

[
    {
        "count": <count>,
        "data": [
            {<node-edge-data>},
            ...
        ]
    },
    ...
]

Order `order_by`

Endpoint `"mcp/order_by"`

Orders the current state of the traversal by a given property in ascending or descending order. Request Format

{
    "connection_id": "<connection-id>", 
    "data": {"properties": "<property-name>", "order": "<asc-desc>"}
}

connection_id

string

required

Connection ID of the MCP connection

properties

string

required

The property to order by

order

string

required

The order to use for the property (asc or desc)

Response Format

{<first-item>}

MCP Search Tools

SearchV `search_vector`

Endpoint `"mcp/search_vector"`

Searches for vectors by their vector representation with the given vector. It returns the top k results with a minimum score of min_score. Additionally, you can continue the traversal from the search results by using the traversal tools. Request Format

{
    "connection_id": "<connection-id>", 
    "data": {
        "vector": <array-of-floats>, "k": <limit>, "min_score": <min-score>
    }
}

connection_id

string

required

Connection ID of the MCP connection

vector

[F64]

required

The vector to search for

I64

required

The number of results to return

min_score

F64

The minimum score to return (default: 0.0)

Response Format

[
    {<vector-data>},
    ...
]

SearchV Text `search_vector_text`

Endpoint `"mcp/search_vector_text"`

Searches for vectors by their vector representation with given text. It uses the embedding inside the database to embed the text and then does HNSW search for the vector. It returns the top 5 results of the vectors with the label. Request Format

{
    "connection_id": "<connection-id>", 
    "data": {
        "query": "<text>", "label": "<vector-label>"
    }
}

connection_id

string

required

Connection ID of the MCP connection

query

string

required

The text to search for

label

string

required

The label of the vectors to search for (name in schema)

Response Format

[
    {<vector-data>},
    ...
]

Search BM25 `search_keyword`

Endpoint `"mcp/search_keyword"`

Searches for nodes of the given label by their keyword representation using BM25. Request Format

{
    "connection_id": "<connection-id>", 
    "data": {
        "query": "<text>", "label": "<label>", "limit": <limit>
    }
}

connection_id

string

required

Connection ID of the MCP connection

query

string

required

The text to search for

label

string

required

The label of the node, edge, or vector to search for (name in schema)

limit

I64

required

The number of results to return

Response Format

[
    {<node-data>},
    ...
]

Knowledge Graph Examples

In this example, we will be using the Python SDK to interact with the MCP endpoints on a local instance of HelixDB. We will use a knowledge graph with the schema below, which has a triplet node to represent a fact and an entity node to represent the subject and object of the triplet. We will also have an embedding of the triplet’s summary defined as a vector node. Schema.hx

N::Triplet {
    INDEX uuid: String,
    summary: String,
    predicate: String,
    value: String,
    created_at: Date DEFAULT NOW
}

E::Triplet_to_Embedding {
    From: Triplet,
    To: Triplet_Embedding,
    Properties: {
    }
}

V::Triplet_Embedding {
    embedding: [F64]
}

E::Triplet_to_Subject {
    From: Triplet,
    To: Entity,
    Properties: {
    }
}

E::Triplet_to_Object {
    From: Triplet,
    To: Entity,
    Properties: {
    }
}

N::Entity {
    INDEX uuid: String,
    name: String,
    entity_type: String,
    description: String,
    created_at: Date DEFAULT NOW
}

Python SDK

from helix import Client
client = Client(local=True, port=6969)

Click here for more information about the Python SDK.

1. Filter properties by a list of values.

We will filter the entities with the names “John” or “Jane”.

# Initialize the connection
connection_id = client.query('mcp/init', {})[0]

# Get all entities
client.query('mcp/n_from_type', {'connection_id': connection_id, 'data': {'node_type': 'Entity'}})

# Filter entities by the name "John" or "Jane"
client.query('mcp/filter_items', {
    'connection_id': connection_id, 
    'data': {'filter': {
        'properties': [
            [
                {'key': 'name', 'operator': '==', 'value': ['John', 'Jane']}
            ]
        ]
    }}
})

# Collect the entities
entities = client.query('mcp/collect', {'connection_id': connection_id})[0]

2. Filter multiple properties by a list of values.

We will filter the entities with the names “John” or “Jane” and the created_at property between 2025-01-01 and 2025-01-31.

# Initialize the connection
connection_id = client.query('mcp/init', {})[0]

# Get all entities
client.query('mcp/n_from_type', {'connection_id': connection_id, 'data': {'node_type': 'Entity'}})

# Filter entities by the name "John" or "Jane" and the created_at property between 2025-01-01 and 2025-01-31
client.query('mcp/filter_items', {
    'connection_id': connection_id, 
    'data': {'filter': {
        'properties': [
            [
                # AND layer
                {'key': 'name', 'operator': '==', 'value': ['John', 'Jane']},
                {'key': 'created_at', 'operator': '>=', 'value': "2025-01-01T00:00:00+00:00"},
                {'key': 'created_at', 'operator': '<=', 'value': "2025-01-31T23:59:59+00:00"}
            ]
        ]
    }}
})

3. Filter properties by multiple lists of values.

We will filter by date range of the created_at property from January to March or June to September.

# Initialize the connection
connection_id = client.query('mcp/init', {})[0]

# Get all entities
client.query('mcp/n_from_type', {'connection_id': connection_id, 'data': {'node_type': 'Entity'}})

# Filter entities by the created_at property between January and March or June and September
client.query('mcp/filter_items', {
    'connection_id': connection_id, 
    'data': {'filter': {
        'properties': [
            # OR layer
            [
                # AND layer
                {'key': 'created_at', 'operator': '>=', 'value': "2025-01-01T00:00:00+00:00"},
                {'key': 'created_at', 'operator': '<=', 'value': "2025-03-31T23:59:59+00:00"}
            ],
            [
                # AND layer
                {'key': 'created_at', 'operator': '>=', 'value': "2025-06-01T00:00:00+00:00"},
                {'key': 'created_at', 'operator': '<=', 'value': "2025-09-30T23:59:59+00:00"}
            ]
        ]
    }}
})

# Collect the entities
entities = client.query('mcp/collect', {'connection_id': connection_id})[0]

3. Filter by traversal result properties.

We will filter the triplets connected to the subject name “John”.
This example has 2 answers:

# Initialize the connection
connection_id = client.query('mcp/init', {})[0]

# Get all entities
client.query('mcp/n_from_type', {'connection_id': connection_id, 'data': {'node_type': 'Entity'}})

# Filter entities by the name "John"
client.query('mcp/filter_items', {
    'connection_id': connection_id, 
    'data': {'filter': {
        'properties': [
            [
                {'key': 'name', 'operator': '==', 'value': 'John'}
            ]
        ]
    }}
})

# Get all triplets connected to the entities
# (traverses the In of the edge to triplet nodes connected to the entities)
client.query('mcp/in_step', {"connection_id": connection_id, "data": {"edge_type": "Triplet_to_Subject", "edge_label": "node"}})

# Collect the triplets
triplets = client.query('mcp/collect', {'connection_id': connection_id})[0]

# Initialize the connection
connection_id = client.query('mcp/init', {})[0]

# Get all triplets
client.query('mcp/n_from_type', {'connection_id': connection_id, 'data': {'node_type': 'Triplet'}})

# Filter triplets with the subject name "John"
client.query('mcp/filter_items', {
    'connection_id': connection_id, 
    'data': {'filter': {
        'filter_traversals': [
            # Traverse out from the triplet nodes to the subject nodes
            {
                'tool_name': 'out_step',
                'args': {
                    'edge_type': 'Triplet_to_Subject',
                    'edge_label': 'node'
                },
                # Filter the subject nodes by the name "John"
                'filters': {
                    'properties': [
                        [
                            {'key': 'name', 'operator': '==', 'value': 'John'}
                        ]
                    ]
                }
            }
        ]
    }}
})

# Collect the triplets
triplets = client.query('mcp/collect', {'connection_id': connection_id})[0]

4. Filter by multiple traversal results.

We will filter the triplets connected to the subject name “John” and the object name “Jane”.

# Initialize the connection
connection_id = client.query('mcp/init', {})[0]

# Get all triplets
client.query('mcp/n_from_type', {'connection_id': connection_id, 'data': {'node_type': 'Triplet'}})

# Filter the triplets by the subject name "John" and the object name "Jane"
client.query('mcp/filter_items', {'connection_id': connection_id, 'data': {'filter': {
    'filter_traversals': [
        # AND layer
        # Traverse out from the triplet nodes to the subject nodes
        {
            'tool_name': 'out_step',
            'args': {
                'edge_type': 'Triplet_to_Subject',
                'edge_label': 'node'
            },
            # Filter the subject nodes by the name "John"
            'filters': {
                'properties': [
                    [
                        {'key': 'name', 'operator': '==', 'value': 'John'}
                    ]
                ]
            }
        },
        # Traverse out from the triplet nodes to the object nodes
        {
            'tool_name': 'out_step',
            'args': {
                'edge_type': 'Triplet_to_Object',
                'edge_label': 'node',
                # Filter the object nodes by the name "Jane"
                'filters': {
                    'properties': [
                        [
                            {'key': 'name', 'operator': '==', 'value': 'Jane'}
                        ]
                    ]
                }
            }
        }
    ]
}}})

# Collect the triplets
triplets = client.query('mcp/collect', {'connection_id': connection_id})[0]

5. Collecting intermediate results.

We will get all triplets and their embeddings in one MCP connection.

# Initialize the connection
connection_id = client.query('mcp/init', {})[0]

# Get all triplets
client.query('mcp/n_from_type', {'connection_id': connection_id, 'data': {'node_type': 'Triplet'}})

# Collect without resetting
triplets = client.query('mcp/collect', {'connection_id': connection_id, "drop": False})[0]

# Traverse out from the triplets to the embeddings
client.query('mcp/out_step', {'connection_id': connection_id, 'data': {'edge_type': 'Triplet_to_Embedding', 'edge_label': 'vec'}})

# Collect the embeddings
embeddings = client.query('mcp/collect', {'connection_id': connection_id})[0]

6. Search by vector.

We will search for the top 10 triplets that are most similar to an example embedding of [0.1, 0.2, 0.3, 0.4, 0.5] with a minimum score of 0.7.

# Initialize the connection
connection_id = client.query('mcp/init', {})[0]

# Get all triplets
client.query('mcp/n_from_type', {'connection_id': connection_id, 'data': {'node_type': 'Triplet'}})

# Traverse to embeddings
client.query('mcp/out_step', {'connection_id': connection_id, 'data': {'edge_type': 'Triplet_to_Embedding', 'edge_label': 'vec'}})

# Search for the triplets that are most similar to an example embedding of [0.1, 0.2, 0.3, 0.4, 0.5]
client.query('mcp/search_vector', {'connection_id': connection_id, 'data': {'vector': [0.1, 0.2, 0.3, 0.4, 0.5], 'k': 10, 'min_score': 0.7}})

# Traverse to the triplets
client.query('mcp/in_step', {'connection_id': connection_id, 'data': {'edge_type': 'Triplet_to_Embedding', 'edge_label': 'node'}})

# Collect the triplets
triplets = client.query('mcp/collect', {'connection_id': connection_id})[0]

Guides

Use Cases

​Introduction

​MCP Tools

Initialization init

Endpoint "mcp/init"

Iterate Results next

Endpoint "mcp/next"

Collect Results collect

Endpoint "mcp/collect"

Reset Connection reset

Endpoint "mcp/reset"

Schema Context schema_resource

Endpoint "mcp/schema_resource"

​MCP Traversals

Retrieve Nodes n_from_type

Endpoint "mcp/n_from_type"

Retrieve Edges e_from_type

Endpoint "mcp/e_from_type"

Out out_step

Endpoint "mcp/out_step"

OutE out_e_step

Endpoint "mcp/out_e_step"

In in_step

Endpoint "mcp/in_step"

InE in_e_step

Endpoint "mcp/in_e_step"

​MCP Filter Tool

Filter filter_items

Endpoint "mcp/filter_items"

Property Filter

​Operators

Traversal Filter

​MCP Aggregation Tools

Group group_by

Endpoint "mcp/group_by"

Aggregate aggregate_by

Endpoint "mcp/aggregate_by"

Order order_by

Endpoint "mcp/order_by"

​MCP Search Tools

SearchV search_vector

Endpoint "mcp/search_vector"

SearchV Text search_vector_text

Endpoint "mcp/search_vector_text"

Search BM25 search_keyword

Endpoint "mcp/search_keyword"

​Knowledge Graph Examples

​1. Filter properties by a list of values.

​2. Filter multiple properties by a list of values.

​3. Filter properties by multiple lists of values.

​3. Filter by traversal result properties.

​4. Filter by multiple traversal results.

​5. Collecting intermediate results.

​6. Search by vector.

Introduction

MCP Tools

Initialization `init`

Endpoint `"mcp/init"`

Iterate Results `next`

Endpoint `"mcp/next"`

Collect Results `collect`

Endpoint `"mcp/collect"`

Reset Connection `reset`

Endpoint `"mcp/reset"`

Schema Context `schema_resource`

Endpoint `"mcp/schema_resource"`

MCP Traversals

Retrieve Nodes `n_from_type`

Endpoint `"mcp/n_from_type"`

Retrieve Edges `e_from_type`

Endpoint `"mcp/e_from_type"`

Out `out_step`

Endpoint `"mcp/out_step"`

OutE `out_e_step`

Endpoint `"mcp/out_e_step"`

In `in_step`

Endpoint `"mcp/in_step"`

InE `in_e_step`

Endpoint `"mcp/in_e_step"`

MCP Filter Tool

Filter `filter_items`

Endpoint `"mcp/filter_items"`

Operators

MCP Aggregation Tools

Group `group_by`

Endpoint `"mcp/group_by"`

Aggregate `aggregate_by`

Endpoint `"mcp/aggregate_by"`

Order `order_by`

Endpoint `"mcp/order_by"`

MCP Search Tools

SearchV `search_vector`

Endpoint `"mcp/search_vector"`

SearchV Text `search_vector_text`

Endpoint `"mcp/search_vector_text"`

Search BM25 `search_keyword`

Endpoint `"mcp/search_keyword"`

Knowledge Graph Examples

1. Filter properties by a list of values.

2. Filter multiple properties by a list of values.

3. Filter properties by multiple lists of values.

3. Filter by traversal result properties.

4. Filter by multiple traversal results.

5. Collecting intermediate results.

6. Search by vector.