Docs

MCP Tools Reference

Six logical tools, shared across every pack. The pack argument is a runtime string — validation happens at call time via the registry. Pack-specific extras are exposed under cloven.<packId>.<toolName> and only appear in tools/list when the caller is subscribed to that pack.

cloven.fresh

Fetch the current Mind State for a pack. Returns structured data, narrated brief, citations, and a freshness timestamp.

Input schema.

{
  pack: string,           // pack id — "crypto" (live), "ai" / "markets" (Phase 1.5)
  query?: string          // optional NL refinement (filters state to relevant subset)
}

Output.

{
  state: <pack state schema>,
  brief: string,                         // prose with [N] citation anchors
  citations: Citation[],                 // resolved source URLs
  freshness: { generatedAt: string, ageSeconds: number },
  attestation?: { type: "erc8004" | "eas", ref: string }  // Phase 3
}

Cost. $0.001 (x402) or 1 call against tier quota.

cloven.brief

Fetch only the narrated prose brief for a pack. Cheaper than cloven.fresh when the agent already has a state cache.

Input schema.

{ pack: string }

Output.

{
  brief: string,
  citations: Citation[],
  freshness: { generatedAt: string, ageSeconds: number }
}

Cost. $0.005 (x402) or 1 call against tier quota.

cloven.search

Semantic walk over the compacted state. Returns top-k matching citations with excerpts. Phase 1 search is a JSON-tree walk with case-insensitive substring scoring; Phase 1.5 swaps in a vector index when usage justifies it.

Input schema.

{
  pack: string,
  q: string,                              // search query
  k?: number                              // 1–20, default 5
}

Output.

{
  matches: Array<{ path: string, value: unknown, score: number }>,
  total: number,
  freshness: { generatedAt: string, ageSeconds: number }
}

Cost. $0.002 (x402) or 1 call against tier quota.

cloven.snapshot

Time-travel. Returns a historical Mind State at the requested ISO8601 timestamp. Storage window: 24h for free / hobby (Redis only), 30 days for Pro+ (Postgres backed), 365 days for Team+. If the exact minute isn't stored, the snapshot endpoint returns 404 — there is no auto-rounding (use cloven.subscribe for delta windows).

Input schema.

{
  pack: string,
  at: string                              // ISO8601 timestamp, minute precision
}

Output. Same shape as cloven.fresh but pinned to the historical state. brief may be empty for historical snapshots — use cloven.brief for current prose.

Cost. $0.01 (x402) or 1 call against tier quota.

cloven.subscribe

MCP does not natively support SSE; this tool returns a signed URL the client opens directly. The URL is valid for one hour and streams pulse / delta / keepalive events as the pack's state advances.

Input schema.

{ pack: string }

Output.

{
  url: string,                            // signed SSE URL
  expiresAt: string                       // ISO8601, 1 hour ahead
}

Cost. $0.005 / hour open (x402). SSE keepalive events are not billed individually — billing is per hour the stream is held.

The SDK exposes this as an AsyncIterable<MindPulse> so you can write for await (const p of client.pack("crypto").subscribe()) and not think about the URL.

cloven.cite

Resolve a [N] citation anchor (or a free-form claim) back to its underlying source. Use this when the LLM downstream needs a hyperlink for a brief sentence, or when auditing the trace.

Input schema.

{
  pack: string,
  ref?: number,                           // [N] anchor (1-indexed)
  claim?: string                          // alternative: free-form claim
}

Output.

{
  citation: Citation,                     // ref + sourceId + url + fetchedAt
  source: { id, name, publicUrl },
  freshness: { generatedAt, ageSeconds }
}

Cost. $0.001 (x402) or 1 call against tier quota.

Citation shape

Every tool that returns prose returns a citations array matching this shape:

interface Citation {
  ref: number;            // [N] anchor in the brief
  sourceId: string;       // matches SourceConnector.id
  url: string;            // public URL for the cited claim
  fetchedAt: string;      // ISO8601 when the data was pulled
  excerpt?: string;       // optional hover preview
}

Pack-specific extras

Each pack may declare additional MCP tools via pack.extraTools. They are registered as cloven.<packId>.<toolName> and surfaced in tools/list only when the caller's key is subscribed to that pack. The crypto pack declares no extras in Phase 1 — that codepath is live but inert until a pack registers them.

Planned crypto-pack extras (post-1.0):

  • cloven.crypto.rug_check(token, chain) — GoPlus on-demand audit.
  • cloven.crypto.search_pool(query) — GeckoTerminal pool search.
  • cloven.crypto.token_history(symbol, window) — time-series snapshot.

Error model

Tool calls return { isError: true, content: [{ type: "text", text: "<message>" }] } on failure. The error text contains a code prefix (pack_not_found, quota_exhausted, state_unavailable, x402_required) so the LLM can branch. See error envelope for the full code table.

Resources

The MCP resources/list endpoint exposes read-only metadata:

cloven://packs                       List of all registered packs
cloven://pack/{id}/schema            JSON schema for a pack's state
cloven://pack/{id}/sources           Source connectors powering a pack
cloven://pricing                     Current price table
cloven://status                      Per-pack health: last sync, errors

Subscribing to cloven://pack/{id}/status pushes real-time source health updates to clients that support resource subscriptions.

Prompts

Two ready-made workflow prompts ship with the server:

  • cloven.prompts.analyze-pack — fetch state, identify top 3 signals, cite each, conclude with one actionable insight.
  • cloven.prompts.compare-snapshot — fetch current + historical state, diff them, cite each delta back to sources.

Clients that support MCP prompts/list see them automatically.