Architecture

Cette page décrit comment le Cryptohopper Market Data MCP est structuré en interne, comment les requêtes circulent à travers le système, et quelles garanties il offre concernant la fraîcheur et la disponibilité des données.

Pour l'introduction conceptuelle, consulte Qu'est-ce que MCP ?

Aperçu des composants

Le Cryptohopper MCP est composé de quatre couches :

1. Couche protocole : Implémente la spécification MCP — découverte d'outils, invocation, réponses en streaming.
2. Couche d'authentification et de quota : Valide les jetons bearer, applique l'accès par palier, compte les appels par rapport aux limites hebdomadaires.
3. Couche d'agrégation de données : Interroge les exchanges en amont, normalise les réponses dans un schéma commun.
4. Connecteurs d'exchange : Adaptateurs par exchange qui traduisent entre les API natives de l'exchange et le schéma interne.

Une requête provenant d'un client MCP traverse les quatre couches dans l'ordre.

Flux de requête

Une invocation d'outil typique se déroule comme suit :

1. Le client envoie une requête. Le client MCP envoie une requête JSON-RPC via le flux SSE, contenant le nom de l'outil et les arguments.
2. La couche protocole valide. La requête est vérifiée par rapport au schéma JSON de l'outil. Les requêtes mal formées retournent INVALID_PARAMETER ou MISSING_PARAMETER.
3. La couche d'authentification valide le jeton. Le jeton bearer est résolu en un compte. Les jetons invalides ou révoqués retournent UNAUTHORIZED.
4. La couche de quota vérifie les limites. L'appel est compté par rapport au quota hebdomadaire du compte et à la limite de taux sur intervalle court. Dépasser l'une ou l'autre limite retourne QUOTA_EXCEEDED ou RATE_LIMIT_EXCEEDED.
5. Vérification de palier. L'exchange demandé et — pour les requêtes de chandeliers — la profondeur de l'historique sont validés par rapport à la liste autorisée du palier. Les violations retournent EXCHANGE_NOT_SUPPORTED ou HISTORY_LIMIT_EXCEEDED.
6. La couche d'agrégation dispatche. La requête est acheminée vers le connecteur d'exchange approprié.
7. Le connecteur interroge l'amont. Le connecteur effectue l'appel correspondant à l'API de l'exchange en amont.
8. La réponse se normalise. La réponse en amont est mappée au schéma interne et retournée au client via le flux SSE.

Chacune de ces étapes peut terminer la requête avec une erreur. La sémantique des erreurs est décrite dans la référence des erreurs.

Transport

Le MCP utilise HTTP avec Server-Sent Events (SSE) :

• Connexion initiale et authentification : une requête HTTP standard.
• Invocations d'outils en cours : un flux JSON-RPC bidirectionnel via SSE.

Le choix de SSE fait partie de la spécification MCP. Il prend en charge les réponses en streaming et les connexions de longue durée sans la surcharge des négociations websocket personnalisées.

Le point de terminaison du service est https://mcp-data.cryptohopper.com/mcp. Tout le trafic est chiffré TLS.

Sans état

Le serveur MCP ne conserve pas d'état de session entre les requêtes. Chaque invocation d'outil est indépendante :

• Pas de curseur ou d'itérateur côté serveur.
• Pas de cache par session.
• Pas de contexte implicite transporté entre les appels.

L'état qui doit persister entre les appels relève de la responsabilité du client. Dans les flux de travail d'agents, le modèle conserve l'état dans sa propre fenêtre de contexte.

Fraîcheur des données

Chaque type de données a un profil de fraîcheur différent :

Type de données	Source	Fraîcheur
Ticker	Exchange en amont	Quasi temps réel, rafraîchi à chaque invocation
Carnet d'ordres	Exchange en amont	Instantané au moment de la requête ; pas de mises à jour en streaming
Chandelier actuel	Exchange en amont	La barre actuelle reflète les dernières transactions
Chandelier historique	Exchange en amont + cache	Immuable une fois le chandelier clôturé

Les appels de ticker et de carnet d'ordres récupèrent toujours depuis l'exchange en amont. Les chandeliers historiques peuvent être servis depuis le cache lorsque la barre a déjà été clôturée, car les barres clôturées sont immuables.

Note : Le MCP ne fournit pas de mode de streaming pub/sub. Chaque appel est une récupération ponctuelle.

Modèle d'agrégation

Chaque connecteur d'exchange implémente la même interface interne mais enveloppe l'API spécifique de l'exchange. La couche d'agrégation :

• Normalise les formats de symboles. Les exchanges utilisent différentes notations de paires (BTCUSDT vs BTC-USDT vs BTC/USDT) ; le MCP expose un format BASE/QUOTE uniforme.
• Harmonise les noms de champs. Les API d'exchange diffèrent dans la façon dont elles nomment les champs bid, ask, dernier prix et volume ; le MCP retourne un schéma commun.
• Gère les conventions de fuseau horaire et d'horodatage. Tous les horodatages dans les réponses sont au format UTC, ISO-8601.
• Filtre les paires prises en charge. Les marchés non-spot (perpétuels, options) sont exclus des réponses MCP même si l'exchange en amont les propose.

Consulte le modèle de données pour le schéma de réponse complet.

Différences par exchange

Le MCP vise une sortie uniforme, mais les différences entre exchanges en amont ne peuvent pas toujours être entièrement masquées :

• Profondeur du carnet d'ordres. Différents exchanges exposent différentes profondeurs maximales. Le MCP retourne ce que l'amont expose.
• Intervalles de temps des chandeliers. Tous les exchanges ne prennent pas en charge tous les intervalles de temps. Les combinaisons non prises en charge retournent TIMEFRAME_NOT_SUPPORTED.
• Profondeur de l'historique. Les exchanges varient dans la profondeur d'historique qu'ils servent. Les requêtes dans les limites de palier du MCP peuvent toujours échouer si l'exchange en amont ne sert pas cette profondeur ; cela retourne DATA_UNAVAILABLE.

Les capacités par exchange sont reflétées dans la réponse aux outils list-pairs et list-exchanges.

Fiabilité en amont

Les API d'exchange en amont peuvent être indisponibles ou lentes. Le MCP ne réessaie pas les appels en amont au nom du client ; un échec en amont retourne EXCHANGE_UNAVAILABLE ou DATA_UNAVAILABLE.

Les clients sont censés réessayer les erreurs transitoires après un bref délai. Les clients MCP bien conçus le font automatiquement.

Le MCP lui-même est conçu pour une haute disponibilité, mais dépend de la santé de l'exchange en amont pour la fiabilité de bout en bout.

Concurrence

Plusieurs invocations d'outils simultanées provenant d'un seul client sont autorisées. Chaque invocation est indépendante et compte séparément par rapport au quota. La limite de taux s'applique aux appels simultanés ainsi qu'aux appels séquentiels.

Les clients qui lancent de nombreuses requêtes simultanées doivent limiter leur débit pour éviter d'atteindre la limite de taux.

Limite de sécurité

Le serveur MCP :

• Termine TLS à la périphérie.
• Valide le jeton bearer à chaque requête.
• N'accepte ni n'agit sur les identifiants pour aucun exchange externe. Tous les accès aux exchanges en amont utilisent les propres identifiants du MCP, configurés côté serveur.
• N'expose pas les messages d'erreur bruts de l'exchange en amont au client — les erreurs sont mappées aux propres codes d'erreur du MCP.

Les clés côté client sont les seuls identifiants que les clients doivent fournir. Consulte les meilleures pratiques de sécurité des clés API.

Versioning

La surface du protocole MCP est versionnée selon la spécification MCP. Les schémas d'outils peuvent évoluer au fil du temps :

• Les modifications additives (nouveaux outils, nouveaux arguments optionnels, nouveaux champs de réponse) ne cassent pas la compatibilité.
• Les modifications incompatibles (champs supprimés, types d'arguments modifiés) sont annoncées à l'avance.

Les clients découvrent dynamiquement la surface actuelle des outils lors de la connexion, de sorte que les modifications additives prennent effet sans redéploiement du client.