Architectuur

Deze pagina beschrijft hoe de Cryptohopper Market Data MCP intern is gestructureerd, hoe verzoeken door het systeem stromen en welke garanties het geeft over versheid en beschikbaarheid van gegevens.

Voor de conceptuele introductie, zie Wat is MCP?

Overzicht van componenten

De Cryptohopper MCP bestaat uit vier lagen:

1. Protocollaag: Implementeert de MCP-specificatie — tool-ontdekking, aanroeping, streaming-responsen.
2. Auth- en quotalag: Valideert bearer tokens, handhaaft tier-toegang, telt aanroepen tegen wekelijkse limieten.
3. Gegevensaggregatielaag: Vraagt upstreambeurzen op, normaliseert responsen naar een gemeenschappelijk schema.
4. Beursconnectors: Per-beurs-adapters die vertalen tussen beurs-eigen API's en het interne schema.

Een verzoek van een MCP-client stroomt door alle vier de lagen in volgorde.

Verzoekstroom

Een typische tool-aanroeping verloopt als volgt:

1. Client stuurt verzoek. De MCP-client stuurt een JSON-RPC-verzoek via de SSE-stream, met de toolnaam en argumenten.
2. Protocollaag valideert. Het verzoek wordt gecontroleerd tegen het JSON-schema van de tool. Misvormde verzoeken retourneren INVALID_PARAMETER of MISSING_PARAMETER.
3. Auth-laag valideert token. Het bearer token wordt omgezet naar een account. Ongeldige of ingetrokken tokens retourneren UNAUTHORIZED.
4. Quotalag controleert limieten. De aanroep wordt geteld tegen het wekelijkse quotum van het account en de korte-interval rate limit. Het overschrijden van een van beide limieten retourneert QUOTA_EXCEEDED of RATE_LIMIT_EXCEEDED.
5. Tier-controle. De gevraagde beurs en — voor kaarsquery's — de lookback-diepte worden gevalideerd tegen de allow-lijst van de tier. Overtredingen retourneren EXCHANGE_NOT_SUPPORTED of HISTORY_LIMIT_EXCEEDED.
6. Aggregatielaag dispatcht. Het verzoek wordt gerouteerd naar de juiste beursconnector.
7. Connector vraagt upstream op. De connector maakt de bijbehorende aanroep naar de upstream-beurs-API.
8. Respons normaliseert. Het upstreamrespons wordt gemapt naar het interne schema en geretourneerd naar de client via de SSE-stream.

Elk van deze stappen kan het verzoek beëindigen met een fout. Foutsemantieken worden beschreven in foutreferentie.

Transport

De MCP gebruikt HTTP met Server-Sent Events (SSE):

• Initiële verbinding en authenticatie: een standaard HTTP-verzoek.
• Doorlopende tool-aanroepen: een bidirectionele JSON-RPC-flow via SSE.

De keuze voor SSE maakt deel uit van de MCP-specificatie. Het ondersteunt streaming-responsen en langdurige verbindingen zonder de overhead van op maat gemaakte websocket-handshakes.

Het service-eindpunt is https://mcp-data.cryptohopper.com/mcp. Al het verkeer is TLS-versleuteld.

Statelessness

De MCP-server houdt geen sessiestatus bij tussen verzoeken. Elke tool-aanroep is onafhankelijk:

• Geen server-side cursor of iterator.
• Geen per-sessie cache.
• Geen impliciete context die tussen aanroepen wordt meegedragen.

Status die tussen aanroepen moet blijven bestaan, is de verantwoordelijkheid van de client. In agent-workflows houdt het model de status bij in zijn eigen contextvenster.

Versheid van gegevens

Elk gegevenstype heeft een ander versheidsprofiel:

Gegevenstype	Bron	Versheid
Ticker	Upstreambeurs	Near real-time, ververst bij elke aanroep
Orderboek	Upstreambeurs	Snapshot op verzoektijdstip; geen streaming-updates
Huidige kaars	Upstreambeurs	Huidige bar weerspiegelt laatste trades
Historische kaars	Upstreambeurs + cache	Onveranderlijk zodra de kaars is gesloten

Ticker- en orderboek-aanroepen halen altijd op van de upstreambeurs. Historische kaarsen kunnen worden geserveerd vanuit cache wanneer de bar al is gesloten, aangezien gesloten bars onveranderlijk zijn.

Let op: De MCP biedt geen pub/sub streaming-modus. Elke aanroep is een ophaalactie op een bepaald tijdstip.

Aggregatiemodel

Elke beursconnector implementeert dezelfde interne interface maar verpakt de specifieke API van de beurs. De aggregatielaag:

• Normaliseert symboolformaten. Beurzen gebruiken verschillende paarnotaties (BTCUSDT vs BTC-USDT vs BTC/USDT); de MCP stelt een uniform BASE/QUOTE-formaat bloot.
• Harmoniseert veldnamen. Beurs-API's verschillen in hoe ze bid-, ask-, last price- en volumevelden noemen; de MCP retourneert een gemeenschappelijk schema.
• Handelt tijdzone- en timestamp-conventies af. Alle timestamps in responsen zijn UTC, ISO-8601 geformatteerd.
• Filtert op ondersteunde paren. Niet-spotmarkten (perpetuals, opties) worden uitgesloten van MCP-responsen, zelfs als de upstreambeurs ze aanbiedt.

Zie gegevensmodel voor het volledige responsschema.

Verschillen per beurs

De MCP streeft naar een uniforme output, maar upstreambeursenverschillen kunnen niet altijd volledig worden verborgen:

• Orderboekdiepte. Verschillende beurzen stellen verschillende maximale dieptes bloot. De MCP retourneert wat de upstream blootstelt.
• Kaars-timeframes. Niet elke beurs ondersteunt elk timeframe. Niet-ondersteunde combinaties retourneren TIMEFRAME_NOT_SUPPORTED.
• Historische lookback. Beurzen variëren in hoe ver terug ze historische gegevens serveren. Verzoeken binnen de tierlimieten van de MCP kunnen nog steeds mislukken als de upstreambeurs die diepte niet serveert; dit retourneert DATA_UNAVAILABLE.

Mogelijkheden per beurs worden weerspiegeld in het respons op de list-pairs- en list-exchanges-tools.

Betrouwbaarheid van upstream

Upstreambeursenvervallen kunnen niet beschikbaar of traag zijn. De MCP probeert geen upstreamaanroepen opnieuw namens de client; een falende upstream retourneert EXCHANGE_UNAVAILABLE of DATA_UNAVAILABLE.

Van clients wordt verwacht dat ze tijdelijke fouten opnieuw proberen na een korte vertraging. Goed opgezette MCP-clients doen dit automatisch.

De MCP zelf is ontworpen voor hoge beschikbaarheid, maar is afhankelijk van de upstream-beursengezondheid voor end-to-end betrouwbaarheid.

Gelijktijdigheid

Meerdere gelijktijdige tool-aanroepen van één client zijn toegestaan. Elke aanroep is onafhankelijk en telt afzonderlijk mee tegen het quotum. De rate limit geldt zowel voor gelijktijdige aanroepen als voor opeenvolgende.

Clients die veel gelijktijdige verzoeken uitwaaieren, moeten throttlen om te voorkomen dat ze de rate limit bereiken.

Beveiligingsgrens

De MCP-server:

• Beëindigt TLS aan de rand.
• Valideert het bearer token bij elk verzoek.
• Accepteert of handelt niet op basis van inloggegevens voor externe beurzen. Alle upstream-beurstoegang gebruikt de eigen inloggegevens van de MCP, geconfigureerd aan de serverkant.
• Stelt de ruwe foutmeldingen van de upstreambeurs niet bloot aan de client — fouten worden gemapt naar de eigen foutcodes van de MCP.

Client-side sleutels zijn de enige inloggegevens die clients moeten verstrekken. Zie best practices voor API-sleutelbeveiliging.

Versiebeheer

Het MCP-protocoloppervlak heeft een versienummer volgens de MCP-specificatie. Tool-schema's kunnen in de loop van de tijd evolueren:

• Additieve wijzigingen (nieuwe tools, nieuwe optionele argumenten, nieuwe responsvelden) zijn niet-brekend.
• Brekende wijzigingen (verwijderde velden, gewijzigde argumenttypes) worden van tevoren aangekondigd.

Clients ontdekken het huidige tool-oppervlak dynamisch bij verbinding, dus additieve wijzigingen worden van kracht zonder heruitrol van de client.