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 has no configuration file. Every setting is read from environment variables at startup, which the server inherits from the shell or from a .env file in the working directory. This keeps configuration portable and compatible with any MCP client that accepts an env block (Claude Desktop, LangChain MCP adapters, etc.).

​
Environment Variables

​
Neo4j Connection

VariableRequiredDefaultDescription
NEO4J_URIYes—Neo4j connection URI, e.g. bolt://localhost:7687 or neo4j+s://...aura.graphenedb.com
NEO4J_USERNAMEYes—Neo4j username
NEO4J_PASSWORDYes—Neo4j password
NEO4J_DATABASENoneo4jThe Neo4j database to connect to. Use neo4j for the default database or AuraDB instances.

​
Embedding Model

VariableRequiredDefaultDescription
EMBEDDING_MODELNotext-embedding-3-smallLiteLLM model identifier used to embed the agent’s query at search time. Must match the model used during ingest so query vectors and stored vectors are comparable.
EMBEDDING_DIMENSIONSNoauto-detectedOptional vector dimension override for models that support truncation. Must match the dimension the graph was embedded at. Models that do not support truncation ignore this value.
EMBEDDING_BATCH_SIZE does not apply to the MCP server. The server embeds a single query string per tool call and never batches — that variable is only relevant during ingest with the embedding connectors.

​
Auth for Embedding Providers

Embedding provider credentials are read by LiteLLM at call time. Set the variable for whichever provider your EMBEDDING_MODEL targets:

OpenAI

OPENAI_API_KEY

Google Gemini

GEMINI_API_KEY

Azure OpenAI

AZURE_API_KEY
AZURE_API_BASE
AZURE_API_VERSION

Amazon Bedrock

AWS_ACCESS_KEY_ID
AWS_SECRET_ACCESS_KEY
AWS_REGION_NAME

Cohere

COHERE_API_KEY

LiteLLM Proxy / Custom

Pass api_key / api_base via litellm_kwargs in the Python API, or set them as LITELLM_* variables recognized by your proxy.
See the LiteLLM provider docs for the full list of supported providers and their required variables.

​
.env File Loading

The server calls load_dotenv() at startup before reading any settings. A .env file placed in the working directory from which the server is launched is automatically loaded — no extra flags required. Here is a minimal .env file covering the most common setup (OpenAI embeddings, local Neo4j):
.env
# Neo4j connection
NEO4J_URI=bolt://localhost:7687
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=your-password
NEO4J_DATABASE=neo4j

# Embedding model
OPENAI_API_KEY=sk-...
EMBEDDING_MODEL=text-embedding-3-small
And a .env for Azure OpenAI with a non-default dimension:
.env
# Neo4j connection
NEO4J_URI=neo4j+s://your-instance.databases.neo4j.io
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=your-password
NEO4J_DATABASE=neo4j

# Azure OpenAI embedding
AZURE_API_KEY=your-azure-key
AZURE_API_BASE=https://your-resource.openai.azure.com/
AZURE_API_VERSION=2024-02-01
EMBEDDING_MODEL=azure/text-embedding-3-large
EMBEDDING_DIMENSIONS=1024
When running the server via uvx (e.g. in Claude Desktop), the working directory is not your project root. Pass all variables directly in the env block of your MCP client configuration instead of relying on a .env file.

​
Transport

The server runs exclusively over stdio (standard MCP transport). It does not expose an HTTP port and cannot be reached over the network directly — the MCP client is responsible for spawning the process and communicating over its stdin/stdout. This makes it compatible with any MCP-capable client:

Claude Desktop

Add the neocarta entry to claude_desktop_config.json. See Connecting to Claude Desktop.

LangChain / LangGraph

Use the langchain-mcp-adapters package to wrap the stdio server as a set of LangChain tools.

Neocarta CLI

Every MCP tool is also available as neocarta tool <tool-name> for shell use or non-MCP agents — no server process needed.

Any MCP Client

Any client that supports the stdio MCP transport can connect by launching neocarta-mcp as a subprocess.

Build docs developers (and LLMs) love

Get started for freeTalk to us