Building Local Knowledge Graphs with Neo4j and MCP

While vector databases excel at finding independent, semantically similar text fragments, they fundamentally fail to grasp interconnected entity hierarchies (e.g., matching who reported to which team, what dependencies are tied to which service).

A graph database like Neo4j maps relationships explicitly using Nodes and Edges, making it the perfect companion for a Reasoning Agent that needs to perform root-cause analysis or organizational lookups.

Prerequisites

1. ▸A running Neo4j instance (either locally via Neo4j Desktop/Docker or cloud-hosted via Neo4j AuraDB).
2. ▸The neo4j-driver npm package installed if building a custom server.

Architecture Diagram

[Agent] --> [Neo4j MCP Server] --> [Executes Cypher Query] --> [Neo4j DB]
                                                                  |
                                              Stores Node: Person (Sarah)
                                              Stores Node: Project (Alpha)
                                              Stores Edge: (Sarah)-[:LEADS]->(Alpha)

Node/Edge Schema Setup Example

If you are exposing a custom tool to your agent, you can wrap the Neo4j driver. Here is an example of a tool that allows the agent to define a "Leadership" relationship between a person and a project dynamically:

import neo4j from 'neo4j-driver';

const driver = neo4j.driver(
  process.env.NEO4J_URI || 'bolt://',
  neo4j.auth.basic(process.env.NEO4J_USER || 'neo4j', process.env.NEO4J_PASSWORD || 'password')
);

async function addTeamRelation(leader: string, projectName: string) {
  const session = driver.session();
  try {
    await session.run(
      `MERGE (p:Person {name: $leader})
       MERGE (pr:Project {name: $projectName})
       MERGE (p)-[:LEADS]->(pr)
       RETURN p, pr`,
      { leader, projectName }
    );
  } finally {
    await session.close();
  }
}

Best Practices

• ▸Strict Schema Enforcement: LLMs are notoriously bad at writing perfect SQL or Cypher queries. Instead of giving the agent a generic "execute_cypher" tool, give it specific parameterized tools (like find_project_dependencies(projectName) or add_team_relation(person, project)) to prevent syntax errors and database corruption.
• ▸Index Heavily: Agents expect fast responses. Ensure you place indexes on commonly queried Node properties (like name or uuid).

Troubleshooting

• ▸Neo.ClientError.Security.Unauthorized: Your credentials are incorrect. Remember that the default username is usually neo4j and the database forces a password change on first login.
• ▸Timeout or Out of Memory: If the agent executes a broad query like MATCH (n) RETURN n, it will attempt to fetch the entire database. Enforce hard limits in your Cypher queries (e.g., LIMIT 50) inside the MCP tool layer.