# 04 — MCP Integration

Cerbero Bite consuma sei servizi MCP HTTP della suite (`Cerbero_mcp`).
Non utilizza l'SDK Python `mcp`: ogni server espone gli endpoint REST
`POST <base_url>/tools/<tool_name>` con autenticazione Bearer, e Cerbero
Bite vi si collega tramite `httpx.AsyncClient` long-lived
(`clients/_base.py`).

## Configurazione di connessione

Le URL sono risolte da `cerbero_bite.config.mcp_endpoints.load_endpoints`,
con default che corrispondono al DNS della rete Docker
`cerbero-suite` (`http://mcp-deribit:9011`, `http://mcp-macro:9013`,
ecc.). Ogni servizio può essere sovrascritto da una variabile
d'ambiente dedicata, utile in sviluppo:

| Servizio | Variabile d'ambiente | Default Docker DNS |
|---|---|---|
| Deribit | `CERBERO_BITE_MCP_DERIBIT_URL` | `http://mcp-deribit:9011` |
| Hyperliquid | `CERBERO_BITE_MCP_HYPERLIQUID_URL` | `http://mcp-hyperliquid:9012` |
| Macro | `CERBERO_BITE_MCP_MACRO_URL` | `http://mcp-macro:9013` |
| Sentiment | `CERBERO_BITE_MCP_SENTIMENT_URL` | `http://mcp-sentiment:9014` |
| Telegram | `CERBERO_BITE_MCP_TELEGRAM_URL` | `http://mcp-telegram:9017` |
| Portfolio | `CERBERO_BITE_MCP_PORTFOLIO_URL` | `http://mcp-portfolio:9018` |

Il bearer token per le chiamate è il token con capability `core` letto
da `secrets/core.token` (path configurabile via
`CERBERO_BITE_CORE_TOKEN_FILE`, default `/run/secrets/core_token` nel
container). Non è loggato.

```python
# clients/_base.py — sintesi
class HttpToolClient:
    service: str            # "deribit", "macro", ...
    base_url: str           # "http://mcp-deribit:9011"
    token: str              # bearer
    timeout_s: float = 8.0
    retry_max: int = 3      # esponenziale 1s/5s/30s
    client: httpx.AsyncClient | None  # condiviso dal RuntimeContext

    async def call(self, tool: str, body: dict | None = None) -> Any: ...
```

Ogni wrapper concreto compone un `HttpToolClient` e ritorna i record
Pydantic consumati direttamente dagli algoritmi `core/`.

## Server MCP usati

### `cerbero-deribit`

Sorgente di tutti i dati di mercato sulle opzioni e canale di
esecuzione: Cerbero Bite invia gli ordini combo direttamente al broker
attraverso questo MCP, senza intermediazioni.

| Tool | Uso | Frequenza |
|---|---|---|
| `environment_info` | Verifica al boot: testnet/mainnet, base_url, max_leverage | Boot + ogni ciclo health |
| `get_ticker(instrument_name)` | Spot proxy via `ETH-PERPETUAL.mark_price`, mid/bid/ask + greche per le leg | Ogni ciclo entry + monitor |
| `get_ticker_batch(instrument_names)` | Quotes in batch per la chain candidata (max 20) | Solo entry |
| `get_dvol(currency="ETH", start_date, end_date)` | Latest DVOL per filtro §2.3 e bias §3.1 | Ogni ciclo entry + monitor |
| `get_instruments(currency, kind="option", expiry_from, expiry_to, min_open_interest)` | Lista strike per il DTE window | Solo entry |
| `get_orderbook(instrument_name, depth=3)` | `book_depth_top3` per liquidity gate | Solo entry |
| `get_historical(instrument, start_date, end_date, resolution)` | Spot 30g fa per bias direzionale + bootstrap return_4h | Entry + monitor (fallback) |
| `get_technical_indicators(instrument, indicators=["adx"], ...)` | ADX(14) per il filtro Iron Condor §3.1 | Solo entry |
| `get_account_summary(currency="USDC")` | Equity Deribit, margin libero (informativo) | Boot + monitor |
| `get_positions(currency="USDC")` | Riconciliazione stato dopo crash | Boot |
| `place_combo_order(legs, side, amount, type, price, label)` | **Esecuzione**: combo atomico via `private/create_combo` + `private/buy/sell` sul combo creato | Entry + monitor (close) |
| `cancel_order(order_id)` | Repricing e annullamenti | Solo monitor |

Note operative:

- Tutti i prezzi e le greche sono restituiti come `float` dal server e
  convertiti in `Decimal` ad alta precisione nel wrapper, mai usati
  come `float` nel motore decisionale.
- Se la chain risponde con `mark_iv` palesemente fuori range
  (es. 7% o 300%) o tutti i `bid == 0` la chiamata viene segnalata come
  `McpDataAnomalyError`; l'orchestrator emette un alert e salta il
  ciclo.
- L'invio di `place_combo_order` è atomico: la creazione del combo e
  l'ordine eseguito sul combo viaggiano in sequenza ma all'interno di
  un'unica chiamata MCP, senza esposizione a leg risk.

### `cerbero-hyperliquid`

| Tool | Uso |
|---|---|
| `get_funding_rate(instrument="ETH")` | Funding rate ETH-PERP (annualizzato × 8760) per il filtro entry §2.6 |

### `cerbero-sentiment`

| Tool | Uso |
|---|---|
| `get_cross_exchange_funding(assets=["ETH"])` | Mediana funding annualizzato (Binance/Bybit/OKX 1095, Hyperliquid 8760) per bias direzionale §3.1 |

Le news qualitative non vengono consumate dal decision loop:
Cerbero Bite è deterministico e non interpreta testi liberi.

### `cerbero-macro`

| Tool | Uso |
|---|---|
| `get_macro_calendar(days, country_filter, importance_min)` | Filtro entry §2.5: zero eventi `high` in `country_filter` (default `["US","EU"]`) entro la finestra DTE |

### `cerbero-portfolio`

| Tool | Uso |
|---|---|
| `get_total_portfolio_value(currency="EUR")` | Capitale di base per il sizing engine, dopo conversione in USD |
| `get_holdings()` | Aggregazione manuale di `current_value_eur` per i ticker che contengono `"ETH"`, usata dal filtro §2.7 (`eth_holdings_pct_max`) |

### `cerbero-telegram`

Cerbero Bite usa Telegram in modalità **notify-only**: nessuna conferma
manuale, nessun callback. L'engine apre e chiude le posizioni
automaticamente quando le regole sono soddisfatte; Telegram viene
informato post-fact.

| Tool | Uso |
|---|---|
| `notify(message, priority, tag)` | Alert MEDIUM o messaggi informativi |
| `notify_position_opened(instrument, side, size, strategy, greeks, expected_pnl)` | Notifica di entry placed |
| `notify_position_closed(instrument, realized_pnl, reason)` | Notifica di exit filled |
| `notify_alert(source, message, priority)` | Alert HIGH (kill switch) |
| `notify_system_error(message, component, priority)` | Alert CRITICAL |

## Errori e degradation

| Server fuori uso | Comportamento |
|---|---|
| `cerbero-deribit` | **Hard fail**: senza dati di mercato e canale di esecuzione il ciclo viene saltato; in monitor le posizioni esistenti restano nello stato corrente, alert HIGH e kill switch |
| `cerbero-hyperliquid` | Skip del filtro funding §2.6 con warning; il ciclo prosegue se le altre condizioni sono soddisfatte |
| `cerbero-sentiment` | Bias §3.1 cade su `no_entry` per default (senza funding cross il bias non può fissare la direzione) |
| `cerbero-macro` | Hard fail per il filtro §2.5; senza calendar non si apre |
| `cerbero-portfolio` | Skip dei filtri §2.7 con warning; il sizing usa l'ultimo capitale noto da SQLite |
| `cerbero-telegram` | Skip notifiche post-fact; il ciclo decisionale non viene bloccato (l'engine non aspetta risposte) |

I trigger HIGH e CRITICAL armano il kill switch e propagano un alert
in audit chain.

## Verifica ambiente al boot

All'avvio l'orchestrator (`runtime/orchestrator.boot`) chiama
`cerbero-deribit.environment_info` e confronta il campo `environment`
con `strategy.execution.environment`. Un `mismatch` (per esempio engine
configurato per `testnet` ma server agganciato a `mainnet`) produce un
alert CRITICAL e arma il kill switch prima che qualsiasi ciclo
trading parta. La stessa verifica viene ripetuta dal probe periodico
(ogni 5 minuti) di `runtime/health_check.HealthCheck`.

## Versioning

I server MCP non espongono attualmente un endpoint `get_version()`
formale; il check di compatibilità si limita a `environment_info` per
Deribit e a un round-trip lightweight sui tool read-only degli altri
servizi nel job di health check. Quando i server pubblicheranno il
versionamento esplicito, l'orchestrator confronterà al boot le
versioni con la tabella `EXPECTED_MCP_VERSIONS` e armerà il kill
switch su mismatch.