AI Agent Integration

The BlackHart Liquid Security Index is designed for autonomous agents. Structured responses, MCP-native tooling, and machine-readable risk verdicts enable agents to make security-informed decisions without human review.

Built for Agents First

Structured Verdicts

Every response includes machine-readable risk verdicts (strong/moderate/weak/critical), so no parsing is needed.

MCP Native

First-class MCP server. Drop into Claude Code, Cursor, or any MCP-compatible agent with one config line.

Deterministic IDs

Protocol IDs are keccak256 hashes of slugs, so agents can compute them locally without lookup calls.

MCP Server (Recommended)

The fastest path for AI agents. Add to your project's .mcp.json:

.mcp.json

{
  "mcpServers": {
    "bro-oracle": {
      "command": "npx",
      "args": ["@blackhart/bro-mcp"],
      "env": {
        "BRO_API_KEY": "your-key-here"
      }
    }
  }
}

Tool Schema

Each MCP tool exposes a typed JSON Schema input. Agents can discover tools dynamically:

bro_get_score schema

{
  "name": "bro_get_score",
  "description": "Get the BlackHart Risk Index (BRI) score for a DeFi protocol",
  "inputSchema": {
    "type": "object",
    "properties": {
      "slug": {
        "type": "string",
        "description": "Protocol identifier (e.g., 'uniswap-v4', 'aave-v3', 'sky')"
      }
    },
    "required": ["slug"]
  }
}

Programmatic Agent Usage

For custom agents built with the MCP SDK:

agent-risk-check.ts

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

const transport = new StdioClientTransport({
  command: "npx",
  args: ["@blackhart/bro-mcp"],
  env: { BRO_API_KEY: process.env.BRO_API_KEY },
});

const client = new Client({ name: "my-agent", version: "1.0.0" });
await client.connect(transport);

// Get score for a protocol
const result = await client.callTool({
  name: "bro_get_score",
  arguments: { slug: "aave-v3" },
});

// Use in risk decision
const score = JSON.parse(result.content[0].text);
if (score.bri < 650) {
  console.log("Protocol below risk threshold, skipping");
}

Agent-Optimized Responses

Every API response includes pre-computed verdicts and staleness checks so agents don't need to implement threshold logic:

GET /api/v1/scores/aave

{
  "slug": "aave-v3",
  "bri": 934,
  "forge_scale": "MITHRIL",
  "forge_scale_num": 6,
  "risk_acceptable": true,
  "dimensions": {
    "access_control": { "score": 90, "weight": 18, "verdict": "strong" },
    "economic_soundness": { "score": 91, "weight": 13, "verdict": "strong" },
    "oracle_integrity": { "score": 88, "weight": 13, "verdict": "strong" },
    "compositional_risk": { "score": 85, "weight": 10, "verdict": "strong" },
    "governance": { "score": 92, "weight": 10, "verdict": "strong" },
    "maturity": { "score": 95, "weight": 12, "verdict": "strong" },
    "adversarial_resilience": { "score": 100, "weight": 10, "verdict": "strong" },
    "supply_chain": { "score": 90, "weight": 4, "verdict": "strong" },
    "opsec": { "score": 85, "weight": 10, "verdict": "strong" }
  },
  "staleness": {
    "updated_at": "2026-05-04T14:00:00Z",
    "age_seconds": 3600,
    "is_stale": false,
    "max_age_seconds": 86400
  },
  "evidence": {
    "ipfs_hash": "QmX7b2...",
    "methodology_version": "2.0"
  }
}

OpenAPI Spec

For agents using function-calling or tool-use with OpenAPI schemas:

openapi.yaml

openapi: "3.1.0"
info:
  title: BlackHart Liquid Security Index API
  version: "1.0"
servers:
  - url: https://oracle.blackhart.io/api/v1
paths:
  /scores/{slug}:
    get:
      operationId: getProtocolScore
      summary: Get BRI score and all dimensions for a protocol
      parameters:
        - name: slug
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Protocol score
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Score"

Agent Use Cases

DeFi Execution

Gate transactions on risk scores before swapping, lending, or providing liquidity. Reject protocols below a BRI threshold.

Portfolio Rebalancing

Monitor score changes via WebSocket. Trigger rebalance when a held protocol drops below DAMASCUS.

Due Diligence

Automatically assess new protocols before integration. Compare dimensions against your risk policy.

Alerting

Subscribe to score change events. Page humans when a protocol's BRI drops by more than 50 points.

Yield Optimization

Filter yield opportunities by risk. Only route to protocols rated MITHRIL or above.

Governance

Inform DAO governance votes with risk data. Flag proposals that integrate low-rated protocols.

Agent Decision Framework

Always check staleness first. Treat a stale score as unknown risk. Do not fall back to the last known value.

Use dimension scores for nuanced decisions. A protocol with high overall BRI but low oracle score may still be risky for oracle-dependent operations.

Batch reads save latency. When evaluating multiple protocols, use batchGetScores() or the batch API endpoint.

Cache locally, validate freshness. Cache scores for up to 1 hour, but always verify staleness before high-value decisions.

Use Cases API Plans