Arquitectura

Esta página describe cómo está estructurado internamente el Cryptohopper Market Data MCP, cómo fluyen las solicitudes a través del sistema y qué garantías ofrece sobre la actualización y disponibilidad de los datos.

Para la introducción conceptual, consulta ¿Qué es MCP?

Descripción general de componentes

El Cryptohopper MCP está compuesto por cuatro capas:

1. Capa de protocolo: Implementa la especificación MCP — descubrimiento de herramientas, invocación, respuestas en streaming.
2. Capa de autenticación y cuota: Valida tokens bearer, aplica el acceso por nivel, cuenta las llamadas contra los límites semanales.
3. Capa de agregación de datos: Consulta los exchanges upstream, normaliza las respuestas en un esquema común.
4. Conectores de exchange: Adaptadores por exchange que traducen entre las APIs nativas del exchange y el esquema interno.

Una solicitud de un cliente MCP fluye a través de las cuatro capas en orden.

Flujo de solicitudes

Una invocación típica de herramienta procede de la siguiente manera:

1. El cliente envía la solicitud. El cliente MCP envía una solicitud JSON-RPC a través del stream SSE, que contiene el nombre de la herramienta y los argumentos.
2. La capa de protocolo valida. La solicitud se verifica contra el esquema JSON de la herramienta. Las solicitudes mal formadas devuelven INVALID_PARAMETER o MISSING_PARAMETER.
3. La capa de autenticación valida el token. El token bearer se resuelve a una cuenta. Los tokens inválidos o revocados devuelven UNAUTHORIZED.
4. La capa de cuota verifica los límites. La llamada se cuenta contra la cuota semanal de la cuenta y el límite de tasa de intervalo corto. Exceder cualquiera de los límites devuelve QUOTA_EXCEEDED o RATE_LIMIT_EXCEEDED.
5. Verificación de nivel. El exchange solicitado y — para consultas de velas — la profundidad histórica se validan contra la lista permitida del nivel. Las violaciones devuelven EXCHANGE_NOT_SUPPORTED o HISTORY_LIMIT_EXCEEDED.
6. La capa de agregación despacha. La solicitud se enruta al conector de exchange apropiado.
7. El conector consulta upstream. El conector realiza la llamada correspondiente a la API del exchange upstream.
8. La respuesta se normaliza. La respuesta upstream se mapea al esquema interno y se devuelve al cliente a través del stream SSE.

Cada uno de estos pasos puede terminar la solicitud con un error. La semántica de errores se describe en la referencia de errores.

Transporte

El MCP utiliza HTTP con Server-Sent Events (SSE):

• Conexión inicial y autenticación: una solicitud HTTP estándar.
• Invocaciones de herramientas continuas: un flujo JSON-RPC bidireccional sobre SSE.

La elección de SSE es parte de la especificación MCP. Soporta respuestas en streaming y conexiones de larga duración sin la sobrecarga de handshakes websocket personalizados.

El endpoint del servicio es https://mcp-data.cryptohopper.com/mcp. Todo el tráfico está cifrado con TLS.

Sin estado

El servidor MCP no mantiene estado de sesión entre solicitudes. Cada invocación de herramienta es independiente:

• Sin cursor o iterador del lado del servidor.
• Sin caché por sesión.
• Sin contexto implícito transportado entre llamadas.

El estado que necesita persistir entre llamadas es responsabilidad del cliente. En flujos de trabajo de agentes, el modelo mantiene el estado en su propia ventana de contexto.

Actualización de datos

Cada tipo de datos tiene un perfil de actualización diferente:

Tipo de datos	Fuente	Actualización
Ticker	Exchange upstream	Casi en tiempo real, actualizado en cada invocación
Libro de órdenes	Exchange upstream	Instantánea al momento de la solicitud; sin actualizaciones en streaming
Vela actual	Exchange upstream	La barra actual refleja las últimas operaciones
Vela histórica	Exchange upstream + caché	Inmutable una vez que la vela se ha cerrado

Las llamadas de ticker y libro de órdenes siempre obtienen datos del exchange upstream. Las velas históricas pueden servirse desde caché cuando la barra ya se ha cerrado, ya que las barras cerradas son inmutables.

Nota: El MCP no proporciona un modo de streaming pub/sub. Cada llamada es una obtención puntual.

Modelo de agregación

Cada conector de exchange implementa la misma interfaz interna pero envuelve la API específica del exchange. La capa de agregación:

• Normaliza los formatos de símbolo. Los exchanges usan diferentes notaciones de pares (BTCUSDT vs BTC-USDT vs BTC/USDT); el MCP expone un formato uniforme BASE/QUOTE.
• Armoniza los nombres de campos. Las APIs de exchange difieren en cómo nombran los campos de bid, ask, último precio y volumen; el MCP devuelve un esquema común.
• Maneja las convenciones de zona horaria y timestamp. Todos los timestamps en las respuestas son UTC, formateados ISO-8601.
• Filtra a pares soportados. Los mercados no spot (perpetuos, opciones) se excluyen de las respuestas MCP incluso si el exchange upstream los ofrece.

Consulta el modelo de datos para el esquema de respuesta completo.

Diferencias por exchange

El MCP busca una salida uniforme, pero las diferencias del exchange upstream no siempre pueden ocultarse completamente:

• Profundidad del libro de órdenes. Diferentes exchanges exponen diferentes profundidades máximas. El MCP devuelve lo que expone el upstream.
• Marcos temporales de velas. No todos los exchanges soportan todos los marcos temporales. Las combinaciones no soportadas devuelven TIMEFRAME_NOT_SUPPORTED.
• Retrospectiva histórica. Los exchanges varían en qué tan atrás sirven datos históricos. Las solicitudes dentro de los límites de nivel del MCP aún pueden fallar si el exchange upstream no sirve esa profundidad; esto devuelve DATA_UNAVAILABLE.

Las capacidades por exchange se reflejan en la respuesta a las herramientas list-pairs y list-exchanges.

Confiabilidad upstream

Las APIs de exchange upstream pueden no estar disponibles o ser lentas. El MCP no reintenta llamadas upstream en nombre del cliente; un upstream que falla devuelve EXCHANGE_UNAVAILABLE o DATA_UNAVAILABLE.

Se espera que los clientes reintenten errores transitorios después de un breve retraso. Los clientes MCP bien comportados hacen esto automáticamente.

El MCP en sí está diseñado para alta disponibilidad, pero depende de la salud del exchange upstream para la confiabilidad de extremo a extremo.

Concurrencia

Se permiten múltiples invocaciones concurrentes de herramientas desde un solo cliente. Cada invocación es independiente y cuenta por separado contra la cuota. El límite de tasa se aplica tanto a llamadas concurrentes como secuenciales.

Los clientes que dispersan muchas solicitudes simultáneas deben limitar la velocidad para evitar alcanzar el límite de tasa.

Límite de seguridad

El servidor MCP:

• Termina TLS en el borde.
• Valida el token bearer en cada solicitud.
• No acepta ni actúa sobre credenciales de ningún exchange externo. Todo el acceso al exchange upstream utiliza las propias credenciales del MCP, configuradas del lado del servidor.
• No expone los mensajes de error sin procesar del exchange upstream al cliente — los errores se mapean a los propios códigos de error del MCP.

Las claves del lado del cliente son la única credencial que los clientes necesitan proporcionar. Consulta las mejores prácticas de seguridad de claves API.

Versionado

La superficie del protocolo MCP está versionada según la especificación MCP. Los esquemas de herramientas pueden evolucionar con el tiempo:

• Cambios aditivos (nuevas herramientas, nuevos argumentos opcionales, nuevos campos de respuesta) no son disruptivos.
• Cambios disruptivos (campos eliminados, tipos de argumentos modificados) se anuncian con anticipación.

Los clientes descubren la superficie de herramientas actual dinámicamente al conectarse, por lo que los cambios aditivos entran en vigor sin necesidad de redespliegue del cliente.