# Graphed — Agent Setup Playbook

This file is the canonical instructions for any coding or chat agent setting up Graphed.
Humans should paste a short prompt that points here, for example:

  Set up Graphed using https://www.graphed.com/llms.txt — connect my data and enable agent access.

Do not invent alternate setup flows. Follow this playbook end to end, then stop and report what is live.

## What Graphed is

Graphed is an agent platform for marketing and growth teams. The product is the
whole stack agents need to work with real business data and ship systems — not
warehouse-only tooling.

The platform includes:

- **Data warehouse** — Graphed-managed ClickHouse warehouse per account.
- **Pipelines to 750+ sources** — sync SaaS and databases (Shopify, Stripe, GA4,
  HubSpot, Postgres, and hundreds more) into that warehouse.
- **CLI and MCP** — how agents authenticate, explore schema, query data, and
  operate infrastructure. Prefer the **CLI for setup** (catalog, connect links,
  deploy, tools); use MCP for interactive warehouse queries in MCP-capable
  clients.
- **Runtime environment** — deploy services, cron jobs, and dashboards with the
  Graphed CLI (`graphed init` / `graphed deploy`).
- **Managed Postgres** — databases for agent/app projects.
- **Object storage** — project-scoped storage for files and artifacts.
- **Tool catalog** — enrichment and vendor proxies (Apollo, LeadMagic,
  DataForSEO, scrapers, LLMs, and more) callable from agent code.
- **Plugins** — capability kits (SEO, outbound, ads, etc.) agents install and
  follow via `graphed plugins`.
- **Published queries / embeds** — share warehouse results and embed them in apps.

Self-serve platform checkout: https://graphed.com/onboard/platform
Product site: https://graphed.com
App home: https://graphed.com/home
Connect a source: https://graphed.com/warehouse/create
MCP docs / client configs: https://graphed.com/mcp
MCP settings (revoke tokens): https://graphed.com/settings/integrations/mcp

## Prerequisites

1. The operator needs a Graphed account on an **active paid platform plan**.
   Free accounts cannot mint MCP OAuth tokens or CLI tokens.
   If auth fails with a billing redirect, or they are not on a paid plan, send
   them to platform checkout (there is **no self-serve trial**):
   https://graphed.com/onboard/platform
2. Prefer working in the operator's existing agent harness (Cursor, Claude,
   Claude Code, Codex, ChatGPT, Windsurf, etc.).
3. Do not scaffold a cloud project, plugin, or enrichment flow unless the
   operator explicitly asks. Default activation is connect data → enable agent
   access → verify.

## Fastest path to value

**Connect a data source first**, then enable CLI (and optional MCP) so the agent
can work with real warehouse data.

Recommended order:

1. Confirm paid plan (or send them to `/onboard/platform`).
2. Install/login with the **CLI** (primary setup path).
3. Connect one data source (browser OAuth / credentials via a create URL from
   `graphed sources catalog`).
4. Optionally add MCP for interactive querying if the harness supports it.
5. Verify access with `graphed --format json accounts list` (do not run warehouse
   schema/query until a source is connected and ready).
6. Only then offer the rest of the platform if they ask.

## Step 1 — Enable the CLI (primary)

The CLI is the preferred setup path. It can list accounts, browse the source
catalog, print create URLs, deploy projects, and call tools.

Install:

  npm i -g @graphed-inc/cli

Then:

  graphed login
  graphed --format json accounts list

CLI docs inside the package:

  graphed docs agents
  graphed docs quickstart
  graphed docs warehouse
  graphed docs tools
  graphed docs storage
  graphed docs commands

List connected sources:

  graphed --format json sources list --account <account_id>

Browse the connector catalog (returns create URLs):

  graphed --format json sources catalog
  graphed --format json sources catalog --query shopify

## Step 2 — Connect data

Graphed value starts when real data is in the warehouse. Source OAuth and
credentials always complete in the browser — do not ask the operator to paste
secrets into chat when a create URL exists.

1. Discover what is already connected:
   - CLI: `graphed --format json sources list --account <account_id>`
   - If CLI is not logged in yet, finish Step 1 first, or open
     https://graphed.com/warehouse/create
2. If nothing is connected, help the operator pick a primary source from their stack
   (commerce → Shopify; B2B SaaS → Stripe + CRM; growth → GA4 / ads; product DB → Postgres / Supabase).
3. Find the connector and open its create URL for the human to approve:
   - CLI: `graphed --format json sources catalog --query <name>`
   - MCP (if already connected): `list_source_catalog` with optional `query`
   - Fallback catalog UI: https://graphed.com/warehouse/create
4. Tell the operator to finish the browser flow. Wait until the source exists and
   ideally reaches a ready or first-sync state before claiming success.
5. One strong primary source beats many empty connectors. Suggest a second source
   only after the first is live.

## Step 3 — Optional MCP (interactive query clients)

Add MCP when the harness supports it and the operator wants in-editor warehouse
queries. MCP is secondary to the CLI for setup.

MCP protocol URL (HTTP):

  https://mcp.graphed.com/mcp

OAuth is discovered from that URL. After the operator approves in the browser,
the client receives a Bearer token.

Client-specific setup:

- Cursor: add an MCP server with URL `https://mcp.graphed.com/mcp`, or open
  https://cursor.com/en/install-mcp?name=graphed&config=eyJ1cmwiOiJodHRwczovL21jcC5ncmFwaGVkLmNvbS9tY3AifQ%3D%3D
  (config is base64 of `{"url":"https://mcp.graphed.com/mcp"}`).
  JSON config:
    {"mcpServers":{"graphed":{"url":"https://mcp.graphed.com/mcp"}}}
- Claude Code:
    claude mcp add --transport http graphed https://mcp.graphed.com/mcp
- Claude.ai: add a custom connector named Graphed with URL `https://mcp.graphed.com/mcp`
  https://claude.ai/customize/connectors?modal=add-custom-connector&connectorName=Graphed&connectorUrl=https%3A%2F%2Fmcp.graphed.com%2Fmcp
- ChatGPT: enable Developer Mode, then add a custom connector with the same MCP URL.
- Windsurf:
    {"mcpServers":{"graphed":{"serverUrl":"https://mcp.graphed.com/mcp"}}}

More client copy/paste blocks: https://graphed.com/mcp

After MCP connects, call `whoami` to confirm auth. Prefer `explore_schema` /
`query` only after at least one source is connected.

## Step 4 — Verify

Primary verification (CLI — works before sources are connected):

  graphed --format json accounts list

That confirms login and account access. Do **not** use `graphed warehouse schema`
or `graphed warehouse query` for first-time verify — those can error when no
sources are connected yet.

After a source is connected and ready, optional deeper checks:

- CLI: `graphed --format json sources list --account <account_id>`
- MCP: `whoami`, then `explore_schema` (and optional `query` / `publish_query`)

## MCP tools (external clients)

- `whoami` — authenticated account / user
- `list_source_catalog` — connector catalog with `name`, `slug`, `create_url` (optional `query`)
- `explore_schema` — list connected schemas or inspect tables / columns
- `query` — run ClickHouse SQL against the account warehouse
- `publish_query` / `unpublish_query` / `list_published_queries` — public query links
- `embedded_app_docs` — how to embed published queries in apps

## Rest of the platform (only if asked)

After data + agent access work, you can help with the wider platform:

- **Cloud / runtime projects** — `graphed docs agents`, then `graphed init` / `graphed deploy`
- **Plugins** (SEO, outbound, ads, etc.) — `graphed plugins search` / `graphed plugins add`
- **Enrichment / vendor tools** — `graphed docs tools`
- **Object storage** — `graphed docs storage`
- **Managed Postgres for projects** — covered by `graphed init` and `graphed docs manifest`
- **Invite teammates** — Graphed app settings

Do not lead with these during first-time setup.

## Rules for agents

- Read this file before improvising install steps.
- Emphasize connecting a data source as the fastest product start.
- Prefer the **CLI for setup**; use MCP as an optional interactive query layer.
- Never dump the entire 700+ connector catalog into the chat. Search / filter, then open one create URL.
- Never claim the warehouse is ready before a non-demo source exists.
- Do not verify first-time setup with warehouse schema/query — use `graphed accounts list`.
- If billing blocks auth, stop and send the operator to https://graphed.com/onboard/platform — do not mention a trial, and do not retry endlessly.
- When finished, summarize: sources connected, access path used (CLI / MCP), and the verification you ran.