Connect to Your Agent

graphbase uses the MCP stdio transport — the server reads JSON-RPC 2.0 from stdin and writes responses to stdout. Any MCP-compatible agent host can connect to it.

Claude Code

Copy .mcp.json.example to .mcp.json in your project root:

cp .mcp.json.example .mcp.json

Edit the file with the absolute path to your installed binary:

{
  "mcpServers": {
    "graphbase-memories": {
      "command": "/absolute/path/to/.venv/bin/graphbase",
      "args": ["serve"],
      "env": {
        "GRAPHBASE_NEO4J_URI": "bolt://localhost:7687",
        "GRAPHBASE_NEO4J_USER": "neo4j",
        "GRAPHBASE_NEO4J_PASSWORD": "graphbase"
      }
    }
  }
}

Restart Claude Code. The 12 graphbase-memories tools will appear in the tool panel.

which graphbase
# or, if using a project-local venv:
echo "$(pwd)/.venv/bin/graphbase"

Other MCP hosts (Cursor, Cline, Continue, etc.)

Any host that supports MCP stdio servers accepts the same configuration shape. Use the command + args + env pattern from the Claude Code example above, adjusted for your host's config format.

Global install (all projects)

To make the server available across all projects, install it globally and configure it in your user-level MCP config (~/.claude/mcp.json for Claude Code):

pip install graphbase-memories

{
  "mcpServers": {
    "graphbase-memories": {
      "command": "graphbase",
      "args": ["serve"],
      "env": {
        "GRAPHBASE_NEO4J_PASSWORD": "graphbase"
      }
    }
  }
}

Verify connection

After connecting, call get_scope_state with no arguments to confirm the server is reachable:

get_scope_state()

Expected response:

{
  "scope_state": "unresolved",
  "project_exists": false
}

unresolved means no project_id was provided — that is correct and expected on the first call. See Scope Resolution for how to move from unresolved to resolved.

Devtools server

For human inspection of memory (not agent use), start the HTTP server:

graphbase devtools --port 8765

Endpoints: