Architettura

Questa pagina descrive come il Cryptohopper Market Data MCP è strutturato internamente, come le richieste fluiscono attraverso il sistema e quali garanzie offre riguardo alla freschezza e disponibilità dei dati.

Per l'introduzione concettuale, vedi Cos'è MCP?

Panoramica dei componenti

Il Cryptohopper MCP è composto da quattro livelli:

1. Livello protocollo: Implementa le specifiche MCP — scoperta tool, invocazione, risposte in streaming.
2. Livello autenticazione e quota: Valida i bearer token, applica l'accesso per tier, conta le chiamate rispetto ai limiti settimanali.
3. Livello aggregazione dati: Interroga gli exchange upstream, normalizza le risposte in uno schema comune.
4. Connettori exchange: Adattatori per-exchange che traducono tra le API native dell'exchange e lo schema interno.

Una richiesta da un client MCP fluisce attraverso tutti e quattro i livelli in ordine.

Flusso delle richieste

Una tipica invocazione di tool procede come segue:

1. Il client invia la richiesta. Il client MCP invia una richiesta JSON-RPC attraverso lo stream SSE, contenente il nome del tool e gli argomenti.
2. Il livello protocollo valida. La richiesta viene controllata rispetto allo schema JSON del tool. Richieste malformate restituiscono INVALID_PARAMETER o MISSING_PARAMETER.
3. Il livello autenticazione valida il token. Il bearer token viene risolto in un account. Token non validi o revocati restituiscono UNAUTHORIZED.
4. Il livello quota controlla i limiti. La chiamata viene conteggiata rispetto alla quota settimanale dell'account e al limite di frequenza a breve intervallo. Il superamento di uno dei limiti restituisce QUOTA_EXCEEDED o RATE_LIMIT_EXCEEDED.
5. Controllo tier. L'exchange richiesto e — per le query delle candele — la profondità del lookback vengono validati rispetto all'elenco consentito del tier. Le violazioni restituiscono EXCHANGE_NOT_SUPPORTED o HISTORY_LIMIT_EXCEEDED.
6. Il livello aggregazione distribuisce. La richiesta viene instradata al connettore exchange appropriato.
7. Il connettore interroga l'upstream. Il connettore effettua la chiamata corrispondente all'API dell'exchange upstream.
8. La risposta si normalizza. La risposta upstream viene mappata allo schema interno e restituita al client attraverso lo stream SSE.

Ciascuno di questi passaggi può terminare la richiesta con un errore. La semantica degli errori è descritta nel riferimento errori.

Trasporto

L'MCP utilizza HTTP con Server-Sent Events (SSE):

• Connessione iniziale e autenticazione: una richiesta HTTP standard.
• Invocazioni tool in corso: un flusso JSON-RPC bidirezionale tramite SSE.

La scelta di SSE fa parte delle specifiche MCP. Supporta risposte in streaming e connessioni di lunga durata senza l'overhead di handshake websocket personalizzati.

L'endpoint del servizio è https://mcp-data.cryptohopper.com/mcp. Tutto il traffico è crittografato con TLS.

Assenza di stato

Il server MCP non mantiene lo stato di sessione tra le richieste. Ogni invocazione di tool è indipendente:

• Nessun cursore o iteratore lato server.
• Nessuna cache per sessione.
• Nessun contesto implicito trasportato tra le chiamate.

Lo stato che deve persistere tra le chiamate è responsabilità del client. Nei workflow degli agenti, il modello mantiene lo stato nella propria finestra di contesto.

Freschezza dei dati

Ogni tipo di dato ha un profilo di freschezza diverso:

Tipo di dato	Fonte	Freschezza
Ticker	Exchange upstream	Quasi in tempo reale, aggiornato ad ogni invocazione
Registro degli ordini	Exchange upstream	Snapshot al momento della richiesta; nessun aggiornamento in streaming
Candela corrente	Exchange upstream	La barra corrente riflette gli ultimi trades
Candela storica	Exchange upstream + cache	Immutabile una volta chiusa la candela

Le chiamate ticker e registro degli ordini recuperano sempre dall'exchange upstream. Le candele storiche possono essere servite dalla cache quando la barra si è già chiusa, poiché le barre chiuse sono immutabili.

Nota: L'MCP non fornisce una modalità streaming pub/sub. Ogni chiamata è un recupero point-in-time.

Modello di aggregazione

Ogni connettore exchange implementa la stessa interfaccia interna ma incapsula l'API specifica dell'exchange. Il livello di aggregazione:

• Normalizza i formati dei simboli. Gli exchange usano notazioni diverse per le coppie (BTCUSDT vs BTC-USDT vs BTC/USDT); l'MCP espone un formato uniforme BASE/QUOTE.
• Armonizza i nomi dei campi. Le API degli exchange differiscono nel modo in cui denominano i campi bid, ask, ultimo prezzo e volume; l'MCP restituisce uno schema comune.
• Gestisce convenzioni di fuso orario e timestamp. Tutti i timestamp nelle risposte sono UTC, formattati ISO-8601.
• Filtra alle coppie supportate. I mercati non-spot (perpetui, opzioni) sono esclusi dalle risposte MCP anche se l'exchange upstream li offre.

Vedi modello dati per lo schema completo delle risposte.

Differenze per-exchange

L'MCP mira a un output uniforme, ma le differenze degli exchange upstream non possono sempre essere completamente nascoste:

• Profondità del registro degli ordini. Exchange diversi espongono profondità massime diverse. L'MCP restituisce ciò che l'upstream espone.
• Timeframe delle candele. Non ogni exchange supporta ogni timeframe. Combinazioni non supportate restituiscono TIMEFRAME_NOT_SUPPORTED.
• Lookback storico. Gli exchange variano in quanto lontano servono dati storici. Richieste entro i limiti del tier dell'MCP possono comunque fallire se l'exchange upstream non serve quella profondità; questo restituisce DATA_UNAVAILABLE.

Le capacità per-exchange sono riflesse nella risposta ai tool list-pairs e list-exchanges.

Affidabilità upstream

Le API degli exchange upstream possono essere non disponibili o lente. L'MCP non riprova le chiamate upstream per conto del client; un upstream che fallisce restituisce EXCHANGE_UNAVAILABLE o DATA_UNAVAILABLE.

Ci si aspetta che i client riprovino gli errori transitori dopo un breve ritardo. Client MCP ben implementati lo fanno automaticamente.

L'MCP stesso è progettato per l'alta disponibilità, ma dipende dalla salute degli exchange upstream per l'affidabilità end-to-end.

Concorrenza

Sono permesse invocazioni multiple di tool concorrenti da un singolo client. Ogni invocazione è indipendente e conta separatamente rispetto alla quota. Il limite di frequenza si applica sia alle chiamate concorrenti che a quelle sequenziali.

I client che effettuano molte richieste simultanee dovrebbero limitarsi per evitare di raggiungere il limite di frequenza.

Confine di sicurezza

Il server MCP:

• Termina TLS al perimetro.
• Valida il bearer token ad ogni richiesta.
• Non accetta né agisce su credenziali per nessun exchange esterno. Tutto l'accesso agli exchange upstream utilizza le proprie credenziali dell'MCP, configurate lato server.
• Non espone i messaggi di errore grezzi dell'exchange upstream al client — gli errori sono mappati ai codici di errore propri dell'MCP.

Le chiavi lato client sono le uniche credenziali che i client devono fornire. Vedi best practice per la sicurezza delle chiavi API.

Versionamento

La superficie del protocollo MCP è versionata secondo le specifiche MCP. Gli schemi dei tool possono evolversi nel tempo:

• Modifiche additive (nuovi tool, nuovi argomenti opzionali, nuovi campi nelle risposte) non sono breaking.
• Modifiche breaking (campi rimossi, tipi di argomenti modificati) sono annunciate in anticipo.

I client scoprono dinamicamente la superficie corrente dei tool alla connessione, quindi le modifiche additive diventano effettive senza ridistribuzione del client.