Arquitetura

Esta página descreve como o Cryptohopper Market Data MCP é estruturado internamente, como as requisições fluem pelo sistema e quais garantias ele oferece sobre a atualização e disponibilidade dos dados.

Para a introdução conceitual, veja O que é MCP?

Visão geral dos componentes

O Cryptohopper MCP é composto por quatro camadas:

1. Camada de protocolo: Implementa a especificação MCP — descoberta de ferramentas, invocação, respostas em streaming.
2. Camada de autenticação e quota: Valida tokens bearer, aplica acesso por nível, conta chamadas contra limites semanais.
3. Camada de agregação de dados: Consulta corretoras upstream, normaliza respostas em um esquema comum.
4. Conectores de corretoras: Adaptadores por corretora que traduzem entre APIs nativas das corretoras e o esquema interno.

Uma requisição de um cliente MCP flui por todas as quatro camadas em ordem.

Fluxo de requisição

Uma invocação típica de ferramenta procede da seguinte forma:

1. Cliente envia requisição. O cliente MCP envia uma requisição JSON-RPC pelo stream SSE, contendo o nome da ferramenta e argumentos.
2. Camada de protocolo valida. A requisição é verificada contra o esquema JSON da ferramenta. Requisições malformadas retornam INVALID_PARAMETER ou MISSING_PARAMETER.
3. Camada de autenticação valida token. O token bearer é resolvido para uma conta. Tokens inválidos ou revogados retornam UNAUTHORIZED.
4. Camada de quota verifica limites. A chamada é contada contra a quota semanal da conta e o limite de taxa de curto intervalo. Exceder qualquer limite retorna QUOTA_EXCEEDED ou RATE_LIMIT_EXCEEDED.
5. Verificação de nível. A corretora solicitada e — para consultas de velas — a profundidade de histórico são validadas contra a lista de permissões do nível. Violações retornam EXCHANGE_NOT_SUPPORTED ou HISTORY_LIMIT_EXCEEDED.
6. Camada de agregação despacha. A requisição é roteada para o conector de corretora apropriado.
7. Conector consulta upstream. O conector faz a chamada correspondente à API da corretora upstream.
8. Resposta normaliza. A resposta upstream é mapeada para o esquema interno e retornada ao cliente através do stream SSE.

Cada uma dessas etapas pode terminar a requisição com um erro. A semântica de erros é descrita na referência de erros.

Transporte

O MCP usa HTTP com Server-Sent Events (SSE):

• Conexão inicial e autenticação: uma requisição HTTP padrão.
• Invocações contínuas de ferramentas: um fluxo JSON-RPC bidirecional sobre SSE.

A escolha de SSE faz parte da especificação MCP. Ela suporta respostas em streaming e conexões de longa duração sem a sobrecarga de handshakes websocket personalizados.

O endpoint do serviço é https://mcp-data.cryptohopper.com/mcp. Todo o tráfego é criptografado com TLS.

Ausência de estado

O servidor MCP não mantém estado de sessão entre requisições. Cada invocação de ferramenta é independente:

• Sem cursor ou iterador no lado do servidor.
• Sem cache por sessão.
• Sem contexto implícito carregado entre chamadas.

Estado que precisa persistir entre chamadas é responsabilidade do cliente. Em fluxos de trabalho de agentes, o modelo mantém estado em sua própria janela de contexto.

Atualização de dados

Cada tipo de dado tem um perfil de atualização diferente:

Tipo de dado	Origem	Atualização
Ticker	Corretora upstream	Quase em tempo real, atualizado a cada invocação
Livro de ofertas	Corretora upstream	Instantâneo no momento da requisição; sem atualizações em streaming
Vela atual	Corretora upstream	Barra atual reflete negociações mais recentes
Vela histórica	Corretora upstream + cache	Imutável uma vez que a vela foi fechada

Chamadas de ticker e livro de ofertas sempre buscam da corretora upstream. Velas históricas podem ser servidas do cache quando a barra já foi fechada, pois barras fechadas são imutáveis.

Nota: O MCP não fornece um modo de streaming pub/sub. Cada chamada é uma busca pontual.

Modelo de agregação

Cada conector de corretora implementa a mesma interface interna mas envolve a API específica da corretora. A camada de agregação:

• Normaliza formatos de símbolos. Corretoras usam diferentes notações de pares (BTCUSDT vs BTC-USDT vs BTC/USDT); o MCP expõe um formato uniforme BASE/QUOTE.
• Harmoniza nomes de campos. APIs de corretoras diferem em como nomeiam campos de oferta de compra, oferta de venda, último preço e volume; o MCP retorna um esquema comum.
• Trata convenções de fuso horário e timestamp. Todos os timestamps nas respostas são UTC, formatados em ISO-8601.
• Filtra para pares suportados. Mercados não-spot (perpétuos, opções) são excluídos das respostas MCP mesmo se a corretora upstream os oferece.

Veja modelo de dados para o esquema completo de resposta.

Diferenças por corretora

O MCP visa uma saída uniforme, mas diferenças de corretoras upstream nem sempre podem ser completamente ocultadas:

• Profundidade do livro de ofertas. Diferentes corretoras expõem diferentes profundidades máximas. O MCP retorna o que a upstream expõe.
• Intervalos de tempo de velas. Nem toda corretora suporta todo intervalo de tempo. Combinações não suportadas retornam TIMEFRAME_NOT_SUPPORTED.
• Histórico disponível. Corretoras variam em quão longe no passado servem dados históricos. Requisições dentro dos limites de nível do MCP ainda podem falhar se a corretora upstream não serve essa profundidade; isso retorna DATA_UNAVAILABLE.

Capacidades por corretora são refletidas na resposta às ferramentas list-pairs e list-exchanges.

Confiabilidade upstream

APIs de corretoras upstream podem estar indisponíveis ou lentas. O MCP não repete chamadas upstream em nome do cliente; uma falha upstream retorna EXCHANGE_UNAVAILABLE ou DATA_UNAVAILABLE.

Espera-se que clientes repitam erros transitórios após um breve atraso. Clientes MCP bem comportados fazem isso automaticamente.

O próprio MCP é projetado para alta disponibilidade, mas depende da saúde das corretoras upstream para confiabilidade de ponta a ponta.

Concorrência

Múltiplas invocações concorrentes de ferramentas de um único cliente são permitidas. Cada invocação é independente e conta separadamente contra a quota. O limite de taxa se aplica a chamadas concorrentes assim como a sequenciais.

Clientes que distribuem muitas requisições simultâneas devem moderar para evitar atingir o limite de taxa.

Limite de segurança

O servidor MCP:

• Termina TLS na borda.
• Valida o token bearer em cada requisição.
• Não aceita nem age sobre credenciais para nenhuma corretora externa. Todo acesso à corretora upstream usa as próprias credenciais do MCP, configuradas no lado do servidor.
• Não expõe mensagens de erro brutas da corretora upstream ao cliente — erros são mapeados para os próprios códigos de erro do MCP.

Chaves do lado do cliente são a única credencial que clientes precisam fornecer. Veja melhores práticas de segurança de chaves de API.

Versionamento

A superfície de protocolo MCP é versionada de acordo com a especificação MCP. Esquemas de ferramentas podem evoluir ao longo do tempo:

• Mudanças aditivas (novas ferramentas, novos argumentos opcionais, novos campos de resposta) não são quebras.
• Mudanças de quebra (campos removidos, tipos de argumentos alterados) são anunciadas com antecedência.

Clientes descobrem a superfície atual de ferramentas dinamicamente na conexão, então mudanças aditivas entram em efeito sem reimplantação do cliente.