Neo4j

Neo4j

Graph database platform for connected data

​
Overview

Neo4j is a powerful graph database that excels at managing highly connected data and complex relationships. This guide will walk you through connecting your Hypermode agent to Neo4j.

​
Prerequisites

Before connecting Neo4j to Hypermode, you’ll need:
  1. A Neo4j account
  2. A Neo4j instance (we’ll use Neo4j Sandbox for this guide)
  3. A Hypermode workspace

​
Setting up Neo4j

​
Step 1: Create a Neo4j Sandbox

First, you need to go to https://sandbox.neo4j.com/ and create an account. When you get to making a database, select a blank sandbox. Create blank sandbox
Neo4j Sandbox provides free temporary instances perfect for testing. For production use, consider Neo4j Aura or a self-hosted instance.

​
Step 2: Get your connection details

Once created (it may take a moment), you can navigate to the HTTP tab and grab the URL. Note you will have to modify this to use the Neo4j HTTP v2 endpoint:
  • Remove /db/neo4j/tx/commit
  • Replace it with /db/neo4j/query/v2
For example:
  • Original: http://52.54.53.148:7474/db/neo4j/tx/commit
  • Modified: http://52.54.53.148:7474/db/neo4j/query/v2
http tab

​
Step 3: Get authentication credentials

Save this URL and then move to the connection details to grab the username and password. Connection details Now we’ve got the URL, username, and password we can create a new agent in Hypermode.

​
Creating your Neo4j agent

​
Step 1: Create a new agent

From the Hypermode interface, create a new agent:
  1. Click the agent dropdown menu
  2. Select “Create new Agent”
Navigate to create agent

​
Step 2: Configure agent settings

Use these recommended settings for your Neo4j agent:
  • Agent Name: GraphExplorer
  • Agent Title: Neo4j Graph Analysis Agent
  • Description: Analyzes graph relationships and patterns in Neo4j
  • Instructions: You have a connection to a Neo4j graph database. You can create nodes with any labels and properties, create relationships of any type, and run Cypher queries. Neo4j is schemaless, so you can dynamically add data without predefined structures.
  • Model: GPT-4.1
Create agent modal

​
Step 3: View your agent profile

Once created, navigate to your agent’s settings page: Agent profile

​
Connecting to Neo4j

​
Step 1: Add the Neo4j connection

Navigate to the Connections tab and add Neo4j:
  1. Click “Add connection”
  2. Search for “Neo4j” in the available connections
Add Neo4j connection

​
Step 2: Configure credentials

Enter your Neo4j credentials:
  • URL: Your modified HTTP v2 endpoint (http://52.54.53.148:7474/db/neo4j/query/v2)
  • Username: Your Neo4j username (usually neo4j)
  • Password: Your Neo4j password
Neo4j connection modal
Ensure you’re using the HTTP v2 endpoint format. The connection will fail with the default transaction endpoint.

​
Understanding Neo4j’s schemaless nature

Unlike traditional databases, Neo4j doesn’t require you to define schemas upfront. This means:
  • Flexible node creation: Add nodes with any labels and properties on the fly
  • Dynamic relationships: Create relationships of any type between nodes
  • Evolving data models: Your graph structure can grow and change organically
  • No migrations needed: Add new node types or properties without schema updates
This flexibility makes Neo4j perfect for:
  • Exploratory data analysis
  • Rapidly evolving data models
  • Complex, heterogeneous datasets
  • Real-world relationship modeling

​
Example graph model

Here’s a simple example of how nodes and relationships work in Neo4j: Neo4j Graph Model This model shows:
  • Nodes: Person, Company, and Product (represented as circles)
  • Relationships: WORKS_AT, MAKER_OF, BY_COMPANY (represented as arrows)
  • Each node can have properties (like name, age, price)
  • Relationships can also have properties (like since, role)

​
Testing the connection

​
Test 1: Create your first nodes

Start a new thread with your agent and create some nodes dynamically: 
Create nodes for this scenario:
- A Person named "Alice" who is 28 years old
- A Company named "TechCorp" founded in 2020
- A Product named "GraphApp" with a price of $99
Create nodes result

​
Test 2: Create relationships

Now connect your nodes based on our model: 
Create these relationships:
- Alice WORKS_AT TechCorp (since 2021)
- Alice is MAKER_OF GraphApp
- GraphApp is BY_COMPANY TechCorp
Create relationships result

​
Test 3: Visualize in Neo4j Browser

After your agent creates the data, switch to Neo4j Browser to see the results:
  1. Click the “Open” button in your Neo4j Sandbox
  2. Run the visualization query:
   MATCH (n) RETURN n
graph in browser

​
Test 4: Query your graph

Back in your agent thread, use Cypher to explore your data: 
Run a Cypher query to find all products made by people who work at TechCorp, showing the full relationship path.
Query result

​
Example: Building a dynamic knowledge graph

Here’s how to leverage Neo4j’s schemaless nature to build a flexible knowledge graph: 
Let's expand our graph with more data:
1. Add another Person "Bob" who also works at TechCorp
2. Add a new Company "StartupInc"
3. Add Products "DataTool" and "AIAssistant"
4. Create relationships showing Bob made DataTool, and StartupInc made AIAssistant
5. Add a COMPETES_WITH relationship between the two companies
Your agent can dynamically add:
  • New node types as you discover them
  • Properties specific to each entity
  • Relationships that make sense in context
  • No need to predefine any structure!

​
What you can do

With your Neo4j connection and its three core tools, your agent can:
  • Create Node: Dynamically add entities with any labels and properties
  • Create Relationship: Connect nodes with typed relationships and properties
  • Run Cypher Query: Perform complex graph operations including:
    • Pattern matching and traversal
    • Aggregations and analytics
    • Graph algorithms
    • Data updates and deletions
    • Schema-free exploration

​
Troubleshooting

​
Common issues

​
Connection refused error

  • Verify you’re using the HTTP v2 endpoint format
  • Check if your sandbox is still active (they expire after 3 days)
  • Ensure the URL includes the correct port (usually 7474)

​
Authentication failed

  • Confirm username and password are correct
  • Sandbox passwords are auto-generated - copy carefully
  • Try resetting the password in the sandbox console

​
Tool execution errors

  • Check the MCP Neo4j documentation for correct parameter formats
  • Ensure node IDs exist before creating relationships
  • Verify Cypher syntax in your queries

​
Learn more