# DealGraph for agents

> How to connect AI agents to DealGraph: hosted MCP server, AGENTS.md snippet, Claude skill,
> and the write-safety golden loop.

## Hosted MCP server

DealGraph ships a remote MCP server (streamable HTTP, stateless) at:

```
https://dealgraph.vc/api/mcp
```

Authentication: pass your DealGraph API key as a bearer token. Without a key the server runs
against the read-only demo dataset, so you can try every tool with zero setup.

### Claude Code

```bash
claude mcp add --transport http dealgraph https://dealgraph.vc/api/mcp \
  --header "Authorization: Bearer $DEALGRAPH_API_KEY"
```

### Cursor / other MCP clients

Add to your MCP config:

```json
{
  "mcpServers": {
    "dealgraph": {
      "url": "https://dealgraph.vc/api/mcp",
      "headers": { "Authorization": "Bearer dg_live_..." }
    }
  }
}
```

For stdio-only clients, bridge with `npx mcp-remote https://dealgraph.vc/api/mcp --header "Authorization: Bearer dg_live_..."`.

### Tools

Read: `get_dashboard`, `list_portfolios`, `get_portfolio`, `list_companies`, `get_company`,
`get_company_metrics`, `list_funding_rounds`, `list_investments`, `search`, `get_changes`,
`get_audit`. Write: `push_metric` (defaults to dry-run; set `dryRun: false` only after a human
confirmed the diff).

## The golden loop (write safety)

Every agent writing to DealGraph should follow propose-before-write:

1. **GET current state** (avoid duplicates; `?externalRef=` resolves cross-system ids).
2. **Dry-run the write**: `?dryRun=true` or header `Prefer: validate` — full validation plus the
   would-be response from a rolled-back transaction (response header `X-Dry-Run: true`).
3. **Show the human the before → after diff** and wait for an explicit yes.
4. **Write with an `Idempotency-Key`** (any UUID). Retries replay instead of duplicating.
5. **Attribute yourself**: `X-Actor` header plus `source`/`notes` fields. Everything lands in
   `GET /audit`.

Mistakes are reversible: DELETE is soft by default; `POST /<entity>/{id}/restore` undoes it.

## AGENTS.md / CLAUDE.md snippet

Paste this into your repo so coding agents know how to talk to DealGraph:

```markdown
## DealGraph (portfolio system of record)

- API: https://dealgraph.vc/api/v1 — bearer key in env var DEALGRAPH_API_KEY (never hardcode).
- Contract: https://dealgraph.vc/api/v1/openapi.json · Full docs: https://dealgraph.vc/llms-full.txt
- All money is absolute EUR. Success envelope { data }, errors { error: { code, message } }.
- Golden loop for writes: GET current state → POST/PATCH with ?dryRun=true → show the human
  the diff → on yes, write with an Idempotency-Key header and X-Actor: <agent name>.
- Never hard-delete (?hard=true) without explicit human approval; soft delete is the default
  and reversible via POST /<entity>/{id}/restore.
- Incremental sync: ?updatedSince= on lists, GET /changes?since=<ISO> as the change feed.
```

## Claude skill

A ready-made skill with the full workflow (FX conversion, reporting sync, propose-before-write)
is published at [https://dealgraph.vc/docs/skill.md](https://dealgraph.vc/docs/skill.md). Save it as
`.claude/skills/dealgraph/SKILL.md` in your project.

## Agent-readable site surface

- [/llms.txt](https://dealgraph.vc/llms.txt) — index for agents
- [/llms-full.txt](https://dealgraph.vc/llms-full.txt) — full API docs, one fetch
- Markdown mirrors: [/docs/quickstart.md](https://dealgraph.vc/docs/quickstart.md), [/docs/agents.md](https://dealgraph.vc/docs/agents.md), [/docs/skill.md](https://dealgraph.vc/docs/skill.md)
- [/api/v1/openapi.json](https://dealgraph.vc/api/v1/openapi.json) — OpenAPI 3.1