AI Integrations
PuppyGraph can be the live graph backend for AI tools. Your agent can inspect the graph schema, generate Cypher or Gremlin, run the query against current source data, and answer from returned rows.
Choose a starting point
- Connect Claude Code, Claude Desktop, or another MCP-compatible client: Run the MCP server.
- Run a standalone natural-language-to-Cypher chatbot: Run the Python chatbot demo.
- Add a product-specific assistant to your application: Build your own query tool.
- Create a graph schema from connected tables: PuppyGraph AI.
Before you integrate
This page assumes you already have a running PuppyGraph instance and an active graph schema. To prepare that environment, use:
- Launching PuppyGraph in Docker for a local instance.
- Connecting to connect source data.
- Graph Modeling or the PuppyGraph AI to create the graph schema.
The examples below use PuppyGraph's default local ports: 8081 for the Web UI
and REST API, 7687 for openCypher over Bolt, and 8182 for Gremlin
WebSocket.
Run the MCP server
Use the PuppyGraph MCP Server when you want Claude Code, Claude Desktop, Cursor, or another MCP-compatible client to call PuppyGraph tools directly. Besides querying a graph, an agent can use it to connect a data source, build a graph schema, and check the graph against its data, the same steps PuppyGraph AI performs on the AI page.
The server connects to PuppyGraph through Bolt for openCypher, Gremlin
WebSocket for traversals, and the HTTP API on port 8081 for the graph schema
and the setup tools. It needs Node.js 20 or later.
Tools
The server exposes 28 tools. Three of them query the graph:
| Tool | What it does |
|---|---|
puppygraph_query |
Runs a Cypher or Gremlin query and returns the rows, query warnings, and PuppyGraph's error message on failure. |
puppygraph_schema |
Returns the graph schema: node and edge labels and their attributes. |
puppygraph_status |
Reports the connection status and whether read-only mode is on. |
Each of these three is also available with an mcp__ prefix, such as
mcp__puppygraph_query, for MCP clients that expect it.
The other 25 tools take an agent from an empty PuppyGraph to a graph it can query:
| Tools | What they do |
|---|---|
puppygraph_guide |
Describes the steps to query or build a graph, and the rules for keys, types, and edges. |
puppygraph_catalog_spec, puppygraph_list_catalogs, puppygraph_create_catalog, puppygraph_test_catalog |
List the supported catalog types and their connection fields, list the registered catalogs with credentials masked, register a data source as a catalog, and check that PuppyGraph can read through it. |
puppygraph_list_tables, puppygraph_describe_table |
List a catalog's databases or tables, and a table's columns with their PuppyGraph types. |
puppygraph_sample_table, puppygraph_profile_column, puppygraph_table_row_count, puppygraph_check_join |
Read the source tables: sample rows, profile a column (null and distinct counts, whether it can be an ID or references another table), count rows, and check how many values of one column exist in another table's column. |
puppygraph_schema_template, puppygraph_validate_schema, puppygraph_upload_schema |
Return an annotated example graph schema, check a schema against the source tables without changing anything, and install a whole schema. Replacing an installed schema needs replace: true. |
puppygraph_search_schema, puppygraph_get_schema_element |
Find node and edge types in the installed schema by keyword, and show one of them in full. |
puppygraph_add_node, puppygraph_update_node, puppygraph_remove_node, puppygraph_add_edge, puppygraph_update_edge, puppygraph_remove_edge, puppygraph_add_node_attribute, puppygraph_add_edge_attribute |
Change one node type, edge type, or attribute of the installed schema and leave the rest alone. |
puppygraph_check_edges |
Checks the installed graph against its data: for each edge type, how many rows reach an existing source and target node, and whether node IDs are unique. |
The four tools that read source tables return sample values to the agent's
model, and they need the DATA:read permission. On a catalog used by a graph
with row-level security, only administrators
can run them, because they read the tables without row filters.
Install the server
The server is published on npm as
@puppygraph/mcp-server.
There is nothing to install beforehand. Your MCP client starts the server with
this command, and npx downloads the package the first time:
This page describes version 1.3.0. To pin a version, use
@puppygraph/mcp-server@1.3.0 in place of @puppygraph/mcp-server in the
commands below.
Configure your MCP client
With PuppyGraph on localhost and the default credentials, the server needs no
configuration. For Claude Code:
Add --scope user to make it available in all your projects. To pass settings,
add -e NAME=value before -- for each environment variable.
For Claude Desktop, edit claude_desktop_config.json (Settings >
Developer > Edit Config) and restart Claude Desktop. Cursor reads the
same mcpServers shape from ~/.cursor/mcp.json or .cursor/mcp.json:
{
"mcpServers": {
"puppygraph": {
"command": "npx",
"args": ["-y", "@puppygraph/mcp-server"],
"env": {
"PUPPYGRAPH_URL": "bolt://localhost:7687"
}
}
}
}
The env block is optional. Any client that launches stdio MCP servers works
the same way.
Environment variables
All settings are environment variables. The defaults match a local PuppyGraph container.
| Variable | Default | Description |
|---|---|---|
PUPPYGRAPH_URL |
bolt://localhost:7687 |
Bolt endpoint for openCypher. |
PUPPYGRAPH_USERNAME |
puppygraph |
PuppyGraph username the server signs in with over Bolt. |
PUPPYGRAPH_PASSWORD |
puppygraph123 |
Password of that PuppyGraph user. |
PUPPYGRAPH_DATABASE |
Empty | Bolt database name. |
PUPPYGRAPH_GREMLIN_URL |
ws://localhost:8182/gremlin |
Gremlin WebSocket endpoint. It must start with ws:// or wss://. |
PUPPYGRAPH_GREMLIN_USERNAME |
puppygraph |
PuppyGraph username the server signs in with over Gremlin. |
PUPPYGRAPH_GREMLIN_PASSWORD |
puppygraph123 |
Password of that PuppyGraph user. |
PUPPYGRAPH_GREMLIN_TRAVERSAL_SOURCE |
g |
Gremlin traversal source. |
PUPPYGRAPH_SCHEMA_URL |
http://localhost:8081/schemajson |
Graph schema endpoint. |
PUPPYGRAPH_SCHEMA_USERNAME |
puppygraph |
PuppyGraph username the server signs in with over the HTTP API, for the graph schema and the setup tools. |
PUPPYGRAPH_SCHEMA_PASSWORD |
puppygraph123 |
Password of that PuppyGraph user. It is the PuppyGraph login password, not a data source password. |
PUPPYGRAPH_HTTP_URL |
Origin of PUPPYGRAPH_SCHEMA_URL |
PuppyGraph HTTP API used by the setup tools. |
PUPPYGRAPH_MCP_SECRET_ENV_ALLOWLIST |
Empty | Comma-separated names of extra variables that the agent may name as a data source password. |
PUPPYGRAPH_READ_ONLY |
false |
Turns on read-only mode. |
The three username and password pairs are PuppyGraph user credentials, one
for each connection. They are usually the same user. If you changed that user's
password, set it in all three: PUPPYGRAPH_PASSWORD,
PUPPYGRAPH_GREMLIN_PASSWORD, and PUPPYGRAPH_SCHEMA_PASSWORD.
To keep a data source password out of the conversation, put it in the MCP
server's environment and have the agent pass the variable name instead. The
server reads only variables whose names start with PUPPYGRAPH_SECRET_, and
those listed in PUPPYGRAPH_MCP_SECRET_ENV_ALLOWLIST. The setup tools mask
credentials as ****** in their responses.
Read-only mode
The server allows writes by default. To stop an agent from changing
PuppyGraph, start the server with the --read-only flag or
PUPPYGRAPH_READ_ONLY=true:
In read-only mode:
puppygraph_queryrejects Cypher that usesCREATE,MERGE,DELETE,SET,REMOVE,DROP,LOAD CSV, orFOREACH, and Gremlin that usesaddV,addE,mergeV,mergeE,property,drop,io,addVertex,addEdge, orremove, before the query reaches PuppyGraph.puppygraph_create_catalog,puppygraph_upload_schema, and the tools that add, update, or remove schema elements are not offered to the agent.- The tools that only read, including the ones that sample and profile source tables, stay available.
Read-only mode guards against agent mistakes. It is not access control. To enforce read-only access, connect the server as a PuppyGraph user without write permissions. See Role-Based Access Control.
Run the Python chatbot demo
Use the Python chatbot demo when you want a standalone application that turns natural language into Cypher and shows the result in a Gradio UI.
The demo lives in the PuppyGraph Python repository. It includes a schema viewer, graph statistics, a text-to-Cypher RAG system, and an MCP server implementation for query execution and schema lookup.
git clone https://github.com/puppygraph/puppygraph-python.git
cd puppygraph-python/apps/chatbot
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
Edit .env with:
ANTHROPIC_API_KEY.PUPPYGRAPH_BOLT_URI, defaultbolt://localhost:7687.PUPPYGRAPH_HTTP_URI, defaulthttp://localhost:8081.PUPPYGRAPH_USERNAMEandPUPPYGRAPH_PASSWORD.
Then start the app:
Open http://localhost:7860 and ask a graph question, for example:
Build your own query tool
For most application agents, use openCypher over Bolt. Many AI frameworks already know how to work with Neo4j-compatible drivers, and Cypher is easier to inspect than a long traversal string.
from neo4j import GraphDatabase
def run_cypher(query: str, parameters: dict | None = None) -> list[dict]:
driver = GraphDatabase.driver(
"bolt://localhost:7687",
auth=("puppygraph", "puppygraph123"),
)
try:
records, _, _ = driver.execute_query(
query,
parameters or {},
)
return [record.data() for record in records]
finally:
driver.close()
Give the model a short contract for this tool:
Use this tool only for read-only graph queries.
Always include LIMIT unless the query is an aggregate count.
Answer only from returned rows.
If the result is empty, explain which labels and relationships were queried.
Use Gremlin when your application already models traversal steps directly:
from gremlin_python.driver.driver_remote_connection import DriverRemoteConnection
from gremlin_python.process.anonymous_traversal import traversal
connection = DriverRemoteConnection(
"ws://localhost:8182/gremlin",
"g",
username="puppygraph",
password="puppygraph123",
)
try:
g = traversal().with_remote(connection)
rows = g.V().limit(20).value_map(True).to_list()
finally:
connection.close()
Keep the integration safe
- Use a service account for the application. See Role-Based Access Control.
- Apply row-level security when users should see different slices of the graph.
- Keep generated queries out of
INFOlogs. Use debug-level logging or a controlled audit path for query diagnostics. - Keep schema and catalog mutations behind an explicit administrative approval flow.
- Store the user question, generated query, and returned rows together when debugging AI answers.