Skip to content

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

Before you integrate

This page assumes you already have a running PuppyGraph instance and an active graph schema. To prepare that environment, use:

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:

npx -y @puppygraph/mcp-server

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:

claude mcp add puppygraph -- npx -y @puppygraph/mcp-server

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:

claude mcp add puppygraph -- npx -y @puppygraph/mcp-server --read-only

In read-only mode:

  • puppygraph_query rejects Cypher that uses CREATE, MERGE, DELETE, SET, REMOVE, DROP, LOAD CSV, or FOREACH, and Gremlin that uses addV, addE, mergeV, mergeE, property, drop, io, addVertex, addEdge, or remove, 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, default bolt://localhost:7687.
  • PUPPYGRAPH_HTTP_URI, default http://localhost:8081.
  • PUPPYGRAPH_USERNAME and PUPPYGRAPH_PASSWORD.

Then start the app:

python gradio_app.py

Open http://localhost:7860 and ask a graph question, for example:

What types of nodes exist?

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.

pip install neo4j
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:

pip install gremlinpython
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 INFO logs. 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.