# LiveGraph — a guide for AI agents

> LiveGraph is a model-agnostic multi-agent orchestration platform: a graph of agents
> (nodes) connected by routing edges, executed hop by hop on a live canvas that a human
> can watch, interrupt, and reroute while the run is executing. Hosted at https://www.livegraph.ai.

This file is for you — an agent (or the person wiring one up) deciding how to call
LiveGraph programmatically. There are two integration surfaces: calling a published
graph as an MCP tool, and driving the REST API directly.

## Call a graph as an MCP tool

Any LiveGraph graph can be published as an MCP server. If the graph's owner has
assigned it an MCP slug, the endpoint is:

    POST https://api.livegraph.ai/mcp/serve/:slug

- It speaks MCP JSON-RPC 2.0 — one POST per request, no SSE: `initialize`,
  `tools/list`, `tools/call`, `resources/read`.
- `tools/list` advertises exactly one tool, `run_<graph-name>`, taking
  `{prompt, context?}`. `tools/call` launches a run and waits ~30s for the
  result; a slow run returns a `run://<id>` resource URI you poll with
  `resources/read`.
- Auth: send an `X-Api-Key: lgk_…` header (a member key needs at least viewer on
  the served graph), or nothing at all when the owner has opted the slug into
  public access. Public slugs are rate-capped and their output is marked as
  untrusted third-party content — treat it accordingly.
- The human-facing version of this story, including the connector catalog for the
  outbound direction (agents calling remote MCP servers), is https://www.livegraph.ai/mcp.

## Start a run over REST

The REST API lives on the api host (https://api.livegraph.ai), not the web origin. Everything
the app does goes through it.

1. Get an API key: a human creates one under Settings → API keys at
   https://www.livegraph.ai/settings (shown once, then only its hash is stored). Send it as
   `X-Api-Key: lgk_…`. The key acts as its owner — every graph role check
   applies unchanged, so a member's key can only do what that member can. Keys can
   be scoped, e.g. to `runs:create` on specific graphs.
2. Launch a run:

       POST https://api.livegraph.ai/runs
       X-Api-Key: lgk_…
       Content-Type: application/json

       {"graphId": "<graph uuid>", "input": "<prompt for the entry node>"}

   Returns `201` with the run object. `mode` defaults to `"pinned"` — the run
   executes a snapshot of the graph, so edits made after launch do not affect it.
   Pass `"mode": "live"` only when an operator should be able to reroute the run
   mid-flight. Optional `maxCostUsd` caps spend on that run.
3. Poll for the result:

       GET https://api.livegraph.ai/runs/:id
       X-Api-Key: lgk_…

   The run object carries status (`pending` → `running` → `completed` /
   `failed` / `cancelled`, plus `awaiting_approval` when a gate parks it) and
   the output once finished.
4. Scheduled and webhook firing also exist: a graph's owner attaches cron
   schedules or webhook triggers to it, and each webhook exposes a token URL —
   `POST https://api.livegraph.ai/webhooks/:token` — that fires the graph with no auth beyond
   the token itself.

Notes for callers: inputs starting with `/push` or `/pr` are owner commands a
scoped key cannot run. Approval-gated runs park until a human approves — a polled
run that sits in `awaiting_approval` is waiting on a person, not on you.

## Where to learn more

- https://www.livegraph.ai/docs — concepts: graphs, runs, live vs pinned, tools, approvals
- https://www.livegraph.ai/mcp — MCP in both directions, plus the connector catalog
- https://www.livegraph.ai/templates — ready-made agent setups that instantiate into editable graphs
- https://www.livegraph.ai/demo — watch the engine run and steer it, no signup
- https://www.livegraph.ai/llms.txt — the curated machine-readable site summary
- https://www.livegraph.ai/llms-full.txt — every public page as a link list