# verdigraph-mcp

> A secure development environment for builders constructing private cognitive graphs. Deterministic content-addressed brain artifacts, free preview, optional Ed25519-signed compliance attestation.

This is a hosted, OAuth 2.1 + PKCE authenticated Model Context Protocol server.
Pay per call in USD via Stripe Checkout. Prepaid USD credits, atomic micro-USD debit, INSUFFICIENT_CREDITS on zero balance.

## Brain-building shop (live MCP build environment, PRIVATE brains)

- Human-facing UI: https://verdigraph.dev/app
- Pair an agent to a browser session via brain_pair_session (BYO LLM — we never proxy inference).
- Import: brain_import (free preview). Unlock: $9 one-time or $19/mo.
- Brains are PRIVATE PROPERTY of the building caller_id. No public marketplace.
  An owner can prove a brain's structure to a downstream party via:
    (1) the deterministic brain_id + source genome bytes (zero-trust),
    (2) the free /app/import preview (no auth; node ids + edges + invariants),
    (3) a purchased Ed25519 attestation ($199 standard / $499 enterprise — see brain_attest_*).

## Public /app/import endpoint (auth-free, deterministic, idempotent)

Free preview build. Same input bytes always produce the same brain_id + content_hash.
Request:
  POST https://verdigraph.dev/app/import
  content-type: application/json
  body: { "format": "verdigraph_genome" | "claude_project_export" | "openai_assistant" | "prompt_list" | "auto",
          "content": "<stringified agent JSON or newline-separated prompts>" }
Response (200):
  { "ok": true,
    "preview": { brain_id, brain_uri, content_hash, agent_name, node_count, edge_count,
                 node_ids[], edges[], sample_nodes[], llm_bindings, provenance, paywall },
    "invariants": { passed, checks: [{ id, description, passed, passed_with_default?, advisory?, detail? }] } }
Response headers include x-verdigraph-content-hash, x-verdigraph-brain-id, x-verdigraph-deterministic=1.

Curl example:
  curl -sS -X POST https://verdigraph.dev/app/import     -H 'content-type: application/json'     --data '{"format":"verdigraph_genome","content":"{"agent_name":"x","purpose":"y","initial_nodes":["a"],"fitness_metrics":["task_success_rate"]}"}'     | jq '.preview.brain_id, .preview.content_hash, .invariants.passed'

See https://verdigraph.dev/CANONICALIZATION.md for the exact canonical-JSON rule used to derive content_hash.

## Build session (live MCP pairing, optional)

The deterministic build path (POST /app/import) is the recommended way to construct
brains from code or CI. The interactive Build session is a SECOND path for cases
where a human watching the browser wants to see their own LLM agent operate the
build environment in real time via the brain_* MCP tools.

How it works:
  1. Open https://verdigraph.dev/app — a fresh build_session_id is minted automatically
     and a Crockford-base32 pairing code (format XXXX-XXXX) appears.
  2. The user pastes the pairing code into their LLM agent (Claude Desktop, Cowork,
     a custom client) so the agent can call brain_pair_session(pairing_code) over
     /mcp. After successful pair, the agent has a session_id it can include on
     subsequent brain_import / brain_evolve / brain_verify calls.
  3. Every tool call carrying that build_session_id emits start / result / error /
     invariant_report events onto an SSE stream the /app browser is already
     subscribed to at /app/sessions/:id/events. The browser renders the events as
     they happen — live tool-call log on the right, invariants flipping green/red,
     the central graph mutating as the agent evolves the brain.
  4. The session closes when the page closes or the agent calls a sessionClose tool.

When to use which:
  - Deterministic / CI / agent-only:   POST /app/import (auth-free, idempotent, fast)
  - Human-in-the-loop / demo / debug:  brain_pair_session + brain_* MCP tools
  - The same brain artifact is produced either way; pairing adds live observability
    rather than changing what gets built.

## For agents

- MCP endpoint (Streamable HTTP and SSE): https://verdigraph.dev/mcp
- Manifest (SEP-1960): https://verdigraph.dev/.well-known/mcp
- Server card (SEP-1649): https://verdigraph.dev/.well-known/mcp/server-card.json
- OAuth metadata: https://verdigraph.dev/.well-known/oauth-authorization-server

## Tools (29)

- verdigraph_choose_compute_profile — Pick the cheapest reliable model + thinking budget for a task.
- verdigraph_list_profiles — List compute profiles with cost-per-1k token rates.
- verdigraph_create_agent — Initialize a developmental agent from a genome.
- verdigraph_list_agents — List the caller's active agents.
- verdigraph_get_graph_summary — Return node, edge, and ledger counts for an agent's graph.
- verdigraph_get_agent_state — Return the agent's full developmental state.
- verdigraph_submit_evaluation — Submit a task evaluation; growth/pruning fires automatically.
- verdigraph_best_next_steps — Suggest the cheapest reliable route for a pending task.
- verdigraph_get_ledger — Return the developmental ledger (immutable event log).
- verdigraph_save_agent_state — Snapshot an agent's state to R2.
- verdigraph_load_agent_state — Rehydrate an agent from a saved snapshot.
- verdigraph_delete_agent — Permanently remove an agent and its state.
- verdigraph_should_use_cache — Decide whether a task should hit the response cache.
- verdigraph_should_escalate — Decide whether to escalate to a higher-tier model.
- verdigraph_get_balance (free) — Return the caller's current prepaid USD credit balance.
- verdigraph_create_topup_session (free) — Create a Stripe Checkout session ($5–$500) to top up credits.
- verdigraph_topup_url (free) — Return the public /credits URL to hand to a human for anonymous purchase.
- verdigraph_redeem_credit_code (free) — Redeem a single-use vdc_ credit code (atomic claim + balance credit).
- verdigraph_create_subscription (free) — Create a recurring $20/month credit auto-refill subscription.
- brain_pair_session (free) — Pair an authenticated agent with a browser build session (BYO LLM).
- brain_list_formats (free) — List supported agent file formats for brain import.
- brain_import — Deterministically build a Verdigraph brain from an agent file.
- brain_get — Fetch a brain artifact (paywall-gated; subscription unlocks all).
- brain_verify — Re-run the 9 brain invariants against an existing brain.
- brain_evolve — Apply task events to mutate a brain under its growth_rules.
- brain_checkout (free) — Create a Stripe Checkout session ($9 one-time or $19/mo).
- brain_attest_preview (free) — Preview an unsigned attestation for a brain (free).
- brain_attest_purchase — Purchase a signed Ed25519 attestation ($199 standard / $499 enterprise).
- brain_attest_verify (free) — Verify a signed attestation's signature and content_hash.

## Connecting your agent (Claude Desktop / Claude Code / Cowork)

The full onboarding page with copy-paste install JSON and the 4-step "paid-to-using"
walkthrough lives at https://verdigraph.dev/connect. After paying at https://verdigraph.dev/credits,
the success page reuses the same onboarding flow with the credit code prepended.

Claude Desktop config snippet:
  { "mcpServers": { "verdigraph": { "type": "http", "url": "https://verdigraph.dev/mcp" } } }

Claude Code one-liner:
  claude mcp add --transport http verdigraph https://verdigraph.dev/mcp

Cowork: Settings → Connectors → Add custom MCP server → paste https://verdigraph.dev/mcp.

All three clients drive OAuth 2.1 + PKCE on first tool call. The caller_id is minted
server-side at that point; the client stores the bearer token automatically.

## Buying API credits

Three paths, in increasing order of integration:

  (a) Anonymous purchase (no auth required):
        Open https://verdigraph.dev/credits → pick an amount → either supply your
        caller_id (credits land directly) OR leave blank + supply email and a
        single-use vdc_<24-char> code is minted. Redeem the code in your bot's
        first authenticated session via verdigraph_redeem_credit_code(code).

  (b) Authenticated topup (OAuth'd bot):
        Call verdigraph_create_topup_session(amount_usd) → returns a Stripe
        Checkout URL pre-bound to your caller_id. Hand to your human; on
        payment, credits land on your caller automatically.

  (c) Monthly auto-refill (OAuth'd bot):
        Call verdigraph_create_subscription(amount_usd: 20) → recurring
        Stripe subscription at the chosen monthly amount. Each invoice.paid
        credits your caller. Cancel any time; unused credits never expire.

INSUFFICIENT_CREDITS responses always carry topup_url + recommended_amount_usd
so error-handling code can surface the next step without guessing.

## Pricing

- Top-ups: $5–$500 via Stripe Checkout (livemode).
- Per-call routing fee: $0.002 USD, plus model passthrough at provider rates.
- Insufficient credits returns INSUFFICIENT_CREDITS — no charge taken.

## Repo

https://github.com/viridis-security/verdigraph-neurogenesis