DealGraph
Log InJoin the Beta
Open in ClaudeOpen in ChatGPT

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

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:

{
  "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:

## 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. Save it as .claude/skills/dealgraph/SKILL.md in your project.

Agent-readable site surface

Try the write safety

This fires a real POST against the live API with ?dryRun=true on the demo org. Full validation, real response, zero persistence.

POST /api/v1/companies/d3m0c0de…/metrics?dryRun=true
The response lands here. Edit the JSON: try an invalid metricKey and watch the validator name the field.

Generate your AGENTS.md block

Paste-ready snippet that teaches any coding agent the DealGraph golden loop: read, dry-run, ask, write.

Paste into your repo's AGENTS.md or CLAUDE.md. Your coding agent picks up the golden loop from there.

## DealGraph (portfolio system of record)

- API: https://dealgraph.vc/api/v1 — bearer key in env var DEALGRAPH_API_KEY (never hardcode it).
- 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: my-agent.
- 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.
- Rate limit: 120 req/min per key; honor Retry-After on 429.