Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/neo4j-labs/neocarta/llms.txt

Use this file to discover all available pages before exploring further.

The Neocarta MCP server turns your Neo4j semantic layer into a set of structured retrieval tools that AI agents can call directly, over stdio, using the Model Context Protocol. Agents receive rich context about your data landscape — table schemas, column types, example values, and foreign-key references — so they can discover the right tables, build correct joins, and route queries to the right database, without guessing.

​
Installation and Starting the Server

Install the mcp extra: 
pip install "neocarta[mcp]"
Start the server using either entry point — both serve over stdio and read the same environment configuration: 
# Standalone console script
neocarta-mcp

# Or from the unified CLI (requires both cli and mcp extras)
neocarta mcp serve
neocarta-mcp is a console script installed by neocarta[mcp]. neocarta mcp serve is a subcommand of the unified CLI and requires neocarta[cli,mcp]. Both are equivalent in behavior.

​
Search Strategy Auto-Detection

The server does not require manual tool configuration. At startup it probes Neo4j for all available search indexes and the presence of BusinessTerm nodes, then registers tools accordingly.
1

Probe available indexes

The server fetches the set of node-scoped indexes in the target database and checks which labels (Table, Column, Schema, BusinessTerm) have VECTOR and FULLTEXT indexes.
2

Check for BusinessTerm nodes

In addition to the index check, the server verifies that at least one :BusinessTerm node exists in the graph — this is required to enable business-term-bridged hybrid search.
3

Register per-label tools

For each searchable label (Table, Column), the single highest-priority tool whose prerequisites are satisfied is registered. The priority order is:
PriorityStrategyPrerequisites
1 (highest)Business-term-bridged hybridLabel VECTOR + FULLTEXT indexes, businessterm_full_text_index, at least one :BusinessTerm node
2HybridLabel VECTOR + FULLTEXT indexes
3VectorLabel VECTOR index
4Full-textLabel FULLTEXT index
—None registeredNo indexes found for label
4

Register independent tools

Schema-level vector search is registered independently if the Schema VECTOR index exists. Catalog tools (list_schemas, list_tables_by_schema, get_full_metadata_schema) are always registered regardless of index state.
Catalog and full-text tools work from schema alone — no embeddings needed. Run a connector with the --embeddings flag to unlock vector and hybrid search.

​
Connecting to Claude Desktop

Add the following entry to your claude_desktop_config.json to connect Claude Desktop to the Neocarta MCP server. The uvx command fetches and runs the server in an isolated environment without a permanent installation. 
{
  "mcpServers": {
    "neocarta": {
      "command": "uvx",
      "args": [
        "--from",
        "neocarta[mcp]@0.8.0",
        "neocarta-mcp"
      ],
      "env": {
        "NEO4J_URI": "bolt://localhost:7687",
        "NEO4J_USERNAME": "neo4j",
        "NEO4J_PASSWORD": "your-password",
        "NEO4J_DATABASE": "neo4j",
        "OPENAI_API_KEY": "sk-...",
        "EMBEDDING_MODEL": "text-embedding-3-small"
      }
    }
  }
}
The version is pinned in "neocarta[mcp]@0.8.0" inside args. Update this value when upgrading Neocarta to ensure the server version matches the connector version that loaded your graph.
Replace OPENAI_API_KEY with the appropriate credential for your embedding provider (see Configuration for the full provider list). The EMBEDDING_MODEL must match the model used when generating embeddings during ingest — mismatched models produce incompatible vectors.

​
Version Compatibility

The server validates the semantic graph’s recorded version against its own package version at startup using the __neocarta_graph__ metadata node written by connectors on each ingest run.

Version match

The server logs a confirmation at INFO level and proceeds normally.

Version mismatch

The server logs a WARNING identifying both versions but continues to run. Behavior may be unexpected if the schema has changed between versions.
Always keep the Neocarta connector (used during ingestion) and the MCP server on the same package version. Mismatched versions can lead to schema disagreements, missing node properties, or unexpected tool behavior.
If no __neocarta_graph__ metadata node is found — for example, if the graph was loaded by a very early version of Neocarta or by a non-Neocarta process — the server logs a warning and continues. It does not fail hard on missing metadata.

Build docs developers (and LLMs) love

Get started for freeTalk to us