AI Agent Integration

The BRO Oracle 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

check_circleStructured Verdicts

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

smart_toyMCP Native

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

fingerprintDeterministic IDs

Protocol IDs are keccak256 hashes of slugs -- 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 Risk Oracle 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

swap_horizDeFi Execution

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

balancePortfolio Rebalancing

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

fact_checkDue Diligence

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

notificationsAlerting

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

trending_upYield Optimization

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

how_to_voteGovernance

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

Agent Decision Framework

Always check staleness first. A stale score should be treated as unknown risk, not 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 →