Get started with AnythingGraph

Overview

AnythingGraph is a context layer for operational data. You model record types (entities) and how they relate, bring data in through the connector, and explore linked records in the dashboard. Optional AI metadata on each field helps VLMs and agents extract and map source data.

Philosophy

AnythingGraph is built on a simple idea: give your AI the right data—not all of it. Most teams already have the facts they need, but they live in spreadsheets, apps, and inboxes. The product turns that scattered information into a governed graph that reflects how your business actually works—accounts linked to contacts, orders, documents, and the rest.

• Connected, not duplicated — one place to see how records relate instead of re-explaining context in every tool or chat.
• Humans stay in the loop — ingest can fail safely in the landing zone; you review and teach mappings before bad data spreads.
• Same graph for people and agents — the dashboard, webhooks, and MCP all work on the same underlying data, so AI answers match what operators see.
• Scoped access by design — playbooks and optional access rules let agents work on a defined slice of the graph (a CRM pack, an org chart, a finance flow)—not an open-ended dump of everything in your systems.

The goal is clarity and control: operational truth you can explore, integrate, and share with AI on your terms.

Typical path

Once the stack is running, most people follow steps like these:

1. Clone the repo and start all services with ./start-all.sh.
2. Open the dashboard and install a playbook (starter pack with sample data).
3. Send JSON to the playbook webhook; review failures in the landing zone if needed.
4. Connect an agent over MCP to work with the same graph.
5. Optionally automate from your own apps with the SDKs.

Source code: AnythingGraph/AnythingGraph (platform) and AnythingGraph/sdk (client libraries).

Prerequisites

You need Rust and Node.js on your machine.

1. Clone the repository

Clone the main AnythingGraph repository only—you do not need a separate clone of the SDK repo to run the platform:

git clone https://github.com/AnythingGraph/AnythingGraph.git
cd AnythingGraph

Repository: github.com/AnythingGraph/AnythingGraph

2. Start the full stack

From the repository root, run:

chmod +x start-all.sh   # once
./start-all.sh

This starts the core services, dashboard API and UI, and remote MCP. Press Ctrl+C to stop everything. The script installs npm dependencies when needed and frees busy ports before binding.

3. Confirm services are up

Playbooks

What is a playbook?

A playbook is a packaged scenario for your graph: predefined record types (entities), relationships between them, optional sample data, and ingest rules that tell the connector how to map incoming JSON into those types.

Each playbook has:

• A stable playbook_id (for example crm-relationship-graph).
• Install steps that create the schema and examples in your workspace.
• A webhook URL for bulk JSON ingest after install.
• Guidance for AI agents (same playbook_id when using MCP).

Playbooks are the recommended starting point—you get a working graph in minutes instead of designing schema from scratch. See the playbook catalog for all packs in the OSS repo. You can still add your own record types and rows later without installing another pack.

Install and open a playbook

1. Open Playbooks in the dashboard (http://127.0.0.1:5183/playbooks).
2. Install a pack—for example Organizational graph or CRM relationship graph. Installation creates entities, schema links, and sample rows.
3. Explore from the installed playbook view: record types, row links, and Graph View.
4. Copy the connector webhook URL from the playbook screen when you are ready to load data.

Inject data into a playbook

After a playbook is installed, send JSON to its webhook on the dashboard API. The dashboard builds ingest context for that playbook; the connector maps fields, creates rows, and links related records. Failures go to the landing zone.

Webhook pattern:

POST http://127.0.0.1:5180/api/playbooks/{playbookId}/webhook
Content-Type: application/json

Body shape — either a JSON array of objects or a wrapper:

{ "records": [ { ... }, { ... } ] }

Use field names described in the playbook instructions (in the dashboard). Optional query ?source=your-system labels the batch for connector training.

Example: Organizational graph (employees)

POST http://127.0.0.1:5180/api/playbooks/organizational-graph/webhook

{
  "records": [
    {
      "full_name": "Jane Smith",
      "job_title": "Engineer",
      "email": "jane@acme.example",
      "corporation_name": "Acme Corp"
    }
  ]
}

Example: CRM relationship graph (contacts)

Include account_name so the connector can link to an existing account row:

POST http://127.0.0.1:5180/api/playbooks/crm-relationship-graph/webhook

{
  "records": [
    {
      "full_name": "Alex Rivera",
      "email": "alex@northwind.example",
      "account_name": "Northwind Traders"
    }
  ]
}

You can also inject via the SDK:

client.dashboard.playbook_webhook("organizational-graph", {"records": [...]})

Inject data without a playbook

You do not need a playbook to use AnythingGraph. Without one, you define the graph yourself and write data through the dashboard, APIs, SDK, or MCP—there is no playbook webhook or playbook-scoped field mapping.

1. Dashboard UI (simplest)

• Entities — create record types and fields.
• Open an entity → add rows (your business records).
• Entity relationships — define how types link; Row links — connect specific rows.

No connector involved; data goes straight to the graph store behind the dashboard.

2. Dashboard API (same as UI, scriptable)

With the stack running, the dashboard proxies to the data layer, for example:

• POST /api/entities — create a record type
• POST /api/entities/{id}/data — create a row
• POST /api/entity-relationships and POST /api/relationships — schema and row links

Base URL: http://127.0.0.1:5180. See dashboard/README.md in the repo for the full route list.

3. SDK or MCP (integrations and agents)

• SDK — call data_layer clients to create entities and rows directly (ports 8182 by default). Use connector.ingest only if you supply your own ingest context (advanced; playbooks build that context for you).
• MCP — ask an assistant to create record types and rows in conversation after you define what you need (see Use MCP with your AI).

Landing zone

The landing zone is a review queue in the dashboard for records that could not finish playbook ingest. Good rows are written to the graph; failed rows are held aside so you can fix mappings instead of silently dropping bad data.

Open it from the sidebar (Landing zone) or from the home page banner when new failures are waiting. URL: http://127.0.0.1:5183/landing-zone.

How records get there (logic)

When you POST to a playbook webhook, the path is:

1. Dashboard API receives JSON and builds ingest context for that playbook (entities, field rules, relationship rules).
2. Connector service processes each record in the batch.
3. Records that complete mapping, row creation, and relationship linking stay in the graph.
4. Records that fail at any step are saved in the connector’s landing zone store with the original JSON, a reason, and which step failed.
5. The dashboard reads that queue and shows it in the UI.

A single webhook call can therefore partially succeed: some rows land in the graph while others appear in the landing zone. Check the ingest response or the landing zone list after each batch.

Failure steps (what “Step” means in the UI)

What you should do

1. Open the row — expand the payload preview and read Reason and Playbook.
2. Approve (train) — fix field mappings in the approve dialog: which incoming keys map to which entity fields. This saves rules for the same payload shape (fingerprint) so the next ingest can map automatically. The failed row is removed from the queue.
3. Send the webhook again — approve trains the connector; it does not by itself insert the row. Re-post the same or corrected JSON to the playbook webhook.
4. Delete — dismiss a row without training if it was a test or bad data you do not want to retry.

Common situations

• Wrong column names from a spreadsheet export → approve with correct mappings, then resend.
• Missing parent record (contact before account) → create the parent in the dashboard or include it in an earlier webhook batch, then resend the child row.
• Required field empty → fix the JSON and resend; use approve only if keys were labeled differently but values are present.
• Playbooks with strict validation (for example data-quality packs) → expect more landing zone traffic until mappings and data quality match the playbook rules.

What is ontology?

In everyday terms, an ontology is a shared picture of what exists in your domain and how those things connect. It is not a single database table—it is the vocabulary and rules your organization agrees on: “we have Accounts and Contacts,” “a Contact belongs to an Account,” “an Invoice references a Vendor.”

Spreadsheets name columns differently; apps use their own IDs. An ontology sits above that noise and says what the business objects mean and how they relate, so people and software can talk about the same reality.

How AnythingGraph uses ontology

You express ontology in practical building blocks—no PhD required:

• Entities (record types) — the kinds of things you track (Employee, Account, Invoice).
• Fields — properties on each type (email, amount, status).
• Entity relationships — allowed links between types (Contact → Account).
• Rows and row links — real instances and how specific records connect.
• Playbooks — pre-built ontologies for common scenarios (CRM, org chart, procure-to-pay).

When you open Graph View in the dashboard, you are looking at that structure visually—the schema layer of your graph, not just a flat list of files or tables.

How ontology empowers AnythingGraph

Ontology is what turns raw JSON into business context. It enables the product ideas from the overview:

• Smarter ingest — the connector does not only copy keys; it routes payloads to the right record type and relationship rules defined by your ontology (or playbook). That is why field mapping and the landing zone exist: they protect the model when upstream data does not match the vocabulary yet.
• Navigation that follows the business — you traverse “this contact’s account” instead of hunting foreign keys across silos. Humans explore in the UI; agents can follow the same links via MCP.
• Reusable packs — playbooks ship a vetted ontology so you start from a known model instead of inventing types and links from scratch.
• Governed AI context — when you scope an agent to a playbook_id, you are limiting it to one ontology slice (CRM, HR, finance)—the “right data, not all of it” promise in structural form.
• One source of truth for integrations — webhooks, SDK calls, and the dashboard all read and write the same graph, so integrations do not each invent a different shape for “customer” or “order.”

Use cases

End-to-end guides for common integration patterns. Each use case builds on playbooks, the connector, and the same graph you explore in the dashboard.

• VLM document extraction — fetch schema via REST or MCP, run your vision model on PDFs and scans, ingest JSON through the playbook webhook, and validate in the landing zone and Graph View. See also AI metadata on entity fields.

Use MCP with your AI

MCP lets assistants such as Cursor or Claude work with the same graph you see in the dashboard—list record types, read rows, create links, and ask questions in natural language.

When you run ./start-all.sh, remote MCP is already available at http://127.0.0.1:3333/mcp. You can also copy the JSON snippet from the dashboard under Settings → Remote MCP setting on an installed playbook.

Connect Cursor (remote MCP)

1. Keep ./start-all.sh running.
2. Open Settings → MCP in Cursor (or add .cursor/mcp.json in your project).
3. Paste the remote MCP block from the dashboard, or use:

{
  "mcpServers": {
    "anythinggraph": {
      "url": "http://127.0.0.1:3333/mcp"
    }
  }
}

Reload MCP in Cursor and confirm the server shows as connected.

Example prompts (after a playbook is installed)

These are conversation starters—your assistant uses MCP tools behind the scenes; you do not call APIs yourself.

• “What record types exist in my graph?” — good first check after install.
• “List contacts for playbook crm-relationship-graph.” — scopes reads to that pack when the playbook uses access rules.
• “Who works at Acme Corp?” — after loading organizational data via the webhook.
• “Add a new contact Alex Lee, email alex@contoso.example, account Contoso Holdings.” — agent creates rows and links if the schema allows.

If MCP does not connect

• Confirm ./start-all.sh is still running and port 3333 is free.
• Check http://127.0.0.1:5180/api/health and open the dashboard once to verify the API.
• Restart Cursor (or your MCP host) after editing mcp.json.

SDK guide

Official HTTP clients for Python, Node.js, and Go live in AnythingGraph/sdk. Use them from scripts, backends, or ETL jobs—the same services the dashboard and connector use.

Install from the AnythingGraph/sdk repository when you build apps—no separate platform clone required.

Python

git clone https://github.com/AnythingGraph/sdk.git
cd sdk/python && pip install -e .

from anythinggraph import AnythingGraphClient

client = AnythingGraphClient()
print(client.data_layer.health())
client.dashboard.playbook_webhook(
    "organizational-graph",
    {"records": [{"full_name": "Sam Lee", "email": "sam@acme.example", "corporation_name": "Acme Corp"}]},
)

Node.js

git clone https://github.com/AnythingGraph/sdk.git
cd sdk/nodejs && npm install

import { AnythingGraphClient } from 'anythinggraph-sdk';

const client = new AnythingGraphClient();
await client.dataLayer.health();
const playbooks = await client.dashboard.listPlaybooks();

Go

git clone https://github.com/AnythingGraph/sdk.git
cd sdk/golang && go build ./...

client := anythinggraph.NewClient(nil)
health, err := client.DataLayer.Health(context.Background())

Environment variables (DATA_LAYER_URL, CONNECTOR_URL, DASHBOARD_API_URL, etc.) override defaults when services run on other hosts. See the SDK README for ReBAC headers and ingest options.