SQD Portal

Consulte dados on-chain em EVM, Solana, Bitcoin, Substrate e Hyperliquid através da API do SQD Portal, disponível como endpoint remoto hospedado ou servidor stdio local.

GitHub
1
Experimente este MCPPatrocinado

Documentação

Servidor MCP SQD Portal

SQD Portal MCP server

Um servidor MCP que responde perguntas sobre blockchain a partir dos dados do SQD Portal: transações, logs, traces, transferências de tokens, carteiras, análises, séries temporais e candles em redes EVM, Solana, Bitcoin, Substrate, Hyperliquid e Tron, com um Explorer opcional integrado ao host.

O servidor não indexa chains por conta própria. Ele valida entradas, planeja consultas limitadas ao Portal e retorna resultados com metadados de cobertura, atualização, paginação e evidência, para que um assistente possa dizer exatamente o que viu. Não é necessária conta SQD, chave de API ou credencial de cliente.

Ele fala o protocolo MCP stateless 2026-07-28 via HTTP e stdio e mantém o caminho de negociação legado gerenciado pelo SDK para clientes que ainda estão implementando essa revisão. As notas de versão estão em CHANGELOG.md. Veja CONTRIBUTING.md para trabalhar no código e SECURITY.md para reportar uma vulnerabilidade.

Superfície pública atual

  • 28 ferramentas públicas
  • 3 ferramentas avançadas/debug
  • parâmetros públicos usam network
  • filtros de descoberta usam vm
  • sem aliases legados de ferramentas em v0.8.x

Ferramentas de consulta bruta respondem por padrão com respostas compactas. Peça response_format: "full" somente quando precisar do payload maior.

Perguntas sobre entidades podem usar portal_resolve_entity primeiro. Ela resolve símbolos/endereços de tokens EVM, aliases de contratos EVM, identificadores de pools, nomes de protocolos e nomes de moedas Hyperliquid em filtros prontos para consulta, mantendo correspondências ambíguas explícitas.

A resolução de símbolos de tokens e os metadados de tokens vêm de dados abertos de token-lists, não de constantes fixas de endereços de tokens. As respostas incluem avisos explícitos quando os dados da token-list estão indisponíveis, desatualizados ou não suportados para uma rede.

Perguntas sobre carteiras devem começar com portal_get_wallet_summary. Ela retorna fund_flow por padrão, incluindo movimentação de entrada/saída, fluxos de ativos, contrapartes, maiores movimentações observadas e próximos pivôs de evidência antes do drill-down com ferramentas brutas.

Grupos de ferramentas

Descoberta:

  • portal_list_networks
  • portal_get_network_info
  • portal_get_head
  • portal_resolve_entity

Conveniência cross-chain:

  • portal_get_recent_activity
  • portal_get_wallet_summary
  • portal_get_time_series

EVM:

  • portal_evm_query_transactions
  • portal_evm_query_logs
  • portal_evm_query_traces
  • portal_evm_query_token_transfers
  • portal_evm_get_contract_deployment
  • portal_evm_get_contract_activity
  • portal_evm_get_analytics
  • portal_evm_get_ohlc

Solana:

  • portal_solana_query_transactions
  • portal_solana_query_instructions
  • portal_solana_get_analytics

Bitcoin:

  • portal_bitcoin_query_transactions
  • portal_bitcoin_get_analytics

Substrate:

  • portal_substrate_query_events
  • portal_substrate_query_calls
  • portal_substrate_get_analytics

Hyperliquid:

  • portal_hyperliquid_query_fills
  • portal_hyperliquid_get_analytics
  • portal_hyperliquid_get_ohlc

Tron:

  • portal_tron_query_transactions
  • portal_tron_query_logs

Avançado/debug:

  • portal_debug_query_blocks
  • portal_debug_resolve_time_to_block
  • portal_debug_hyperliquid_query_replica_commands

Esses grupos também são os toolsets (discovery, convenience, evm, solana, bitcoin, substrate, hyperliquid, tron, debug). Uma implantação pode reduzir o catálogo com MCP_TOOLSETS ou MCP_TOOLS, e uma conexão HTTP pode restringi-lo ainda mais com ?toolsets= ou um cabeçalho X-MCP-Toolsets; veja as notas de implantação HTTP. Sem nada configurado, toda a superfície de 31 ferramentas é servida, e o endpoint hospedado mantém esse padrão.

Dados suportados

  • Redes EVM indexadas pelo Portal, incluindo Base, Ethereum, Optimism, Arbitrum, Monad, Hyperliquid EVM e muitas outras
  • Transações nativas Tron (transferências TRX, transferências TRC-10, chamadas de contrato com logs inline e transações internas) e logs de eventos TVM, como transferências TRC-20, com endereços Base58 ou hex, valores exatos de TRX e o hash da transação pai em cada log; a skill do plugin SQD incluída documenta a Stream API bruta para qualquer coisa além disso
  • Mainnet Solana
  • Mainnet Bitcoin
  • Fills e comandos de réplica Hyperliquid
  • Redes Substrate indexadas pelo Portal

O suporte a Substrate é atualmente apenas histórico. Não há tail em tempo real.

Formato da resposta

A maioria das ferramentas retorna o mesmo envelope no MCP structuredContent e em um fallback de texto JSON compacto para clientes mais antigos. O envelope contém um corpo de resultado normal mais metadados compartilhados, como:

  • answer
  • display
  • next_steps
  • investigation
  • _freshness
  • _coverage
  • _pagination
  • _ordering

investigation é um guia de evidência compacto para agentes: identifica o caminho principal do resultado, a janela limitada, campos de pivô úteis, como endereços ou hashes de transação, filtros de acompanhamento e limitações antes que um resultado seja tratado como completo. Resultados materiais bem-sucedidos também carregam um recibo _evidence com argumentos canônicos, um digest determinístico, reconciliação de linhas, janelas de origem e semântica de replay exata ou semântica. Recibos exatos fixam sua janela de evidência. Recibos semânticos informam que reexecutar uma janela relativa móvel pode retornar um snapshot mais recente.

Quando uma resposta usa dados estimados, parciais, amostrados, limitados ou paginados, a resposta de nível superior e os metadados informam isso. _pagination.has_more é verdadeiro exatamente quando next_cursor está presente, e _coverage indica se a janela solicitada foi lida por completo (window_complete) e se a resposta contém todas as linhas correspondentes (result_complete). Acompanhamentos seguros de paginação incluem metadados de chamada de ferramenta executáveis com argumentos de cursor explícitos; sugestões que não podem ser reconstruídas com segurança são marcadas como não executáveis.

Ferramentas voltadas a gráficos também retornam descritores de gráfico e tabela para que clientes MCP ou LLMs possam renderizá-los sem engenharia reversa do payload.

SQD Explorer (beta)

O SQD Explorer é um MCP App que renderiza resultados de ferramentas dentro de hosts que suportam MCP Apps. Está em beta e desativado por padrão. Uma implantação padrão responde com structuredContent e texto JSON compacto apenas, e nenhum resultado de ferramenta pede que o host abra uma interface. Há duas formas de optar por ativá-lo:

  • Uma conexão: adicione ?app=1 ao endpoint, por exemplo https://portal.sqd.dev/mcp?app=1. Use isso para testar a beta sem mudar nada para outros usuários.
  • Implantação inteira: defina MCP_APP_ENABLED=true. Uma conexão ainda pode sobrescrever em qualquer direção, então ?app=0 desativa um único cliente de volta.

O recurso do app permanece registrado de qualquer forma, então um host pode lê-lo diretamente sem que ninguém opte por ativá-lo.

Quando ativado, hosts compatíveis recebem um card inline dimensionado ao conteúdo e um workspace em tela cheia para 21 ferramentas de dados: métricas lideradas pelo número principal, gráficos de múltiplas séries e valores com sinal, candles de preço com volume vinculado e leitura fixa, painéis ranqueados e de linha do tempo que mostram dez linhas com controle "Mostrar tudo", tabelas de evidência que paginam dez linhas com busca em todas as linhas, links do explorer para endereços, hashes e blocos, logos e nomes de chains a partir dos metadados de rede SQD, controles de continuação, histórico da sessão atual e exportação JSON ou CSV pelo host. Inspeção por ponteiro e teclado expõe valores exatos plotados. Buckets ausentes permanecem visíveis como lacunas, identificadores não são encurtados e qualquer limite local de linhas é separado da completude do servidor. Acompanhamentos com falha mantêm o último bom resultado sob o erro. O app é autocontido e não usa armazenamento persistente do navegador; suas únicas requisições no lado do navegador são imagens de logos de chains de cdn.subsquid.io e sqd.dev, as duas origens declaradas no CSP do recurso. Hosts sem suporte a MCP Apps recebem o mesmo structuredContent e fallback de texto JSON compacto, então a resposta subjacente nunca depende da interface. docs/explorer-design.md registra as regras de design que o app segue.

Três prompts MCP fornecem pontos de partida reproduzíveis sem adicionar ferramentas:

  • investigate-wallet
  • investigate-contract
  • investigate-market

Para uma demonstração focada em gráficos, pergunte: Show BTC price action and trading volume on Hyperliquid for the past hour, using five-minute candles. Explain whether the final candle is closed. O resultado abre o SQD Explorer com um gráfico de candles, volume, tabela de evidência, limites de tempo solicitados e indexados e um recibo. Reproduza o requested_window_start_timestamp e o requested_window_end_exclusive retornados como entradas fixas from_timestamp e to_timestamp quando precisar de uma execução de verificação estável.

Experimente no Claude

O endpoint hospedado tem o Explorer desativado, então um novo usuário ativa a própria conexão:

  1. No claude.ai ou Claude Desktop, abra Settings → Connectors → Add custom connector, insira https://portal.sqd.dev/mcp?app=1 e escolha sem autenticação. O ?app=1 ativa a beta apenas para esta conexão. No Claude Desktop, você pode, em vez disso, instalar sqd.mcpb da versão mais recente e ativar a configuração "SQD Explorer (beta)".
  2. Inicie um novo chat e habilite o conector SQD para ele.
  3. Faça uma pergunta de dados. Qualquer uma destas cai em uma ferramenta que carrega o Explorer:
    • What has this wallet been doing on Base lately? com um endereço (resumo da carteira)
    • Show me recent activity on Ethereum (atividade recente)
    • Chart hourly transaction counts on Base for the last day (série temporal)

O resultado é renderizado como um card inline em vez de um bloco de texto; abra o card para o workspace em tela cheia. Apenas as 21 ferramentas de dados carregam o Explorer. Uma pergunta de catálogo, como Which networks do you support?, chama portal_list_networks e responde em texto simples, o que é esperado e não uma falha.

Instalação

npm install
npm run build

Execução

stdio:

npm start

HTTP:

npm run start:http

Descoberta para desenvolvedores

O servidor expõe um guia estruturado de seleção de ferramentas para quem constrói clientes:

  • O recurso MCP sqd://tools retorna metadados de ferramentas agrupados, exemplos, pontos de partida e notas de integração.
  • O recurso MCP sqd://tools/{name} retorna a entrada do guia para uma ferramenta, por exemplo sqd://tools/portal_get_time_series.

A descoberta de ferramentas e recursos permanece no próprio protocolo MCP. O servidor não mantém um catálogo HTTP duplicado.

Plugin Codex

O wrapper do plugin Codex está em plugins/portal e usa por padrão o endpoint MCP hospedado em https://portal.sqd.dev/mcp.

Instale-o a partir deste marketplace local ao repositório:

codex plugin marketplace add .
codex plugin add portal@sqd

Abra um novo thread do Codex após instalar. Os prompts de primeiro uso incluem fills de perp BTC da Hyperliquid, volume recente de transações na Base e as transferências USDC mais recentes na Base.

Plugin Claude Code

O plugin Claude Code usa o mesmo endpoint MCP hospedado e o mesmo seletor público:

claude plugin marketplace add subsquid-labs/portal-mcp-server
claude plugin install portal@sqd

Abra uma nova sessão do Claude Code após instalar para que as ferramentas MCP SQD sejam carregadas.

Grok

O chat Grok pode usar SQD como um conector personalizado:

  1. Abra grok.com/connectors.
  2. Escolha New Connector e depois Custom.
  3. Insira https://portal.sqd.dev/mcp como URL do servidor MCP.
  4. Deixe a autenticação não definida.

O Grok Build lê plugins do Claude Code diretamente, então usa o mesmo pacote:

grok plugin install --trust subsquid-labs/portal-mcp-server#plugins/portal

ChatGPT

Em um workspace com MCP apps personalizados ativados, abra Settings → Apps → Create, insira https://portal.sqd.dev/mcp, escolha sem autenticação, examine as ferramentas e crie o app rascunho. O servidor é somente leitura e não exige credenciais de usuário.

Claude Desktop

Baixe sqd.mcpb da versão mais recente e abra-o: o Claude Desktop instala o pacote com um clique e lista as 31 ferramentas. O pacote carrega o servidor, suas dependências de produção e uma configuração opcional, "SQD Explorer (beta)", que vem desativada por padrão. É necessário Node 22 ou mais novo na máquina.

Fallback manual, a partir de um clone local após npm run build, adicione uma entrada como esta a claude_desktop_config.json:

{
  "mcpServers": {
    "SQD": {
      "command": "node",
      "args": ["/absolute/path/to/sqd-portal-mcp-server/dist/index.js"]
    }
  }
}

Notas de uso

  • Se você não souber o nome exato da rede, comece com portal_list_networks.
  • Se precisar de estado indexado recente, use portal_get_network_info ou portal_get_head primeiro.
  • Se a pergunta for ampla, comece com portal_get_recent_activity, portal_get_wallet_summary ou portal_get_time_series antes de partir para consultas brutas.
  • Janelas de tempo aceitam redação compacta e natural, como 30m, past 30 minutes, in the past 1h, in last 38 mins, last hour ou 30 minutes ago.
  • Use portal_evm_get_ohlc e portal_hyperliquid_get_ohlc somente quando realmente precisar de saída em formato de candles.
  • Para consultas grandes ou exploratórias, prefira response_format: "compact" a menos que precise do formato completo do registro.

Notas de implantação HTTP

HTTP mode expõe o MCP em / e /mcp, liveness em /health e readiness em /ready. O serviço hospedado expõe a mesma resposta de health versionada em https://portal.sqd.dev/mcp/health.

  • Os endpoints de MCP e health não exigem autenticação.
  • A descoberta de ferramentas e recursos usa o protocolo MCP; rotas aposentadas /tools e /tools.json retornam 404.
  • Defina MCP_CURSOR_SECRET em qualquer implantação com mais de um processo, para que um cursor emitido por uma instância seja aceito pela próxima. Se não definido, cada processo assina com sua própria chave aleatória e um cursor deixa de funcionar após reinicialização ou salto de balanceamento de carga.
  • /health reporta version e commit, o commit git do qual a imagem foi construída, e todo resultado de ferramenta repete ambos em _server. Tags do Docker Hub: latest, X.Y.Z e X.Y vêm apenas de uma tag de release v*; edge e sha-<commit> vêm de todo push main. Fixe uma tag de versão em produção.
  • /ready é 200 somente depois que o catálogo de dados carregou uma vez e a última sondagem do Portal teve sucesso dentro de MCP_READY_MAX_AGE_MS; caso contrário, é 503 com um reason e Retry-After. Aponte as verificações de readiness do orquestrador para /ready e as de liveness para /health. O HEALTHCHECK da imagem Docker usa /ready.
  • O servidor vincula 127.0.0.1 a menos que MCP_BIND diga o contrário, e toda rota verifica o cabeçalho Host (e Origin, quando um navegador envia um) contra uma allowlist, para que uma página de DNS-rebound não alcance uma instância local. Hosts e origens de loopback sempre passam; requisições sem Origin sempre passam na verificação de origem. Um bind fora de loopback deve definir MCP_ALLOWED_HOSTS e MCP_ALLOWED_ORIGINS; se algum estiver ausente, o servidor registra um erro de inicialização e atende sem essa verificação. A imagem Docker define MCP_BIND=0.0.0.0, então defina ambas as variáveis na implantação, ou * atrás de um proxy que já as valide.
  • Toda requisição é limitada: cabeçalhos dentro de MCP_HEADERS_TIMEOUT_MS, a requisição inteira dentro de MCP_REQUEST_TIMEOUT_MS, keep-alive ocioso dentro de MCP_KEEP_ALIVE_TIMEOUT_MS e corpos MCP acima de MCP_MAX_BODY_BYTES são recusados com 413 antes do parsing (411 para um corpo chunked sem comprimento).

Variáveis de ambiente úteis:

  • MCP_CURSOR_SECRET a chave com a qual os cursores de paginação são assinados. Defina-a em qualquer implantação com mais de um processo. Se não definida, cada processo assina com sua própria chave aleatória, então um cursor emitido por uma instância é rejeitado pela próxima e os clientes perdem seu lugar após reinicialização ou salto de balanceamento de carga. É também o que impede um chamador de cunhar um cursor para uma janela que a ferramenta nunca teria oferecido.
  • MCP_TOOLSETS conjuntos de ferramentas separados por vírgula para servir (discovery, convenience, evm, solana, bitcoin, substrate, hyperliquid, tron, debug; all ou default para tudo). Nomes desconhecidos são ignorados com um erro de inicialização. Tem precedência sobre MCP_TOOLS. Padrão: todos os nove, o catálogo completo de 31 ferramentas.
  • MCP_TOOLS nomes exatos de ferramentas separados por vírgula para servir quando MCP_TOOLSETS não estiver definido.
  • Por conexão, ?toolsets=evm na URL do endpoint ou um cabeçalho X-MCP-Toolsets: evm restringe o conjunto da implantação apenas para aquela conexão; nunca pode adicionar um conjunto de ferramentas. Prompts que referenciam uma ferramenta fora do conjunto ativo não são oferecidos. O conjunto ativo é um rótulo limitado (all, um nome de conjunto de ferramentas ou custom) em mcp_tool_client_calls_total.
  • MCP_BIND interface para escutar, padrão 127.0.0.1 (0.0.0.0 na imagem Docker)
  • MCP_ALLOWED_HOSTS hostnames separados por vírgula aceitos em Host (porta ignorada) além de loopback; * desativa a verificação. Necessário para um bind fora de loopback.
  • MCP_ALLOWED_ORIGINS hostnames separados por vírgula aceitos em Origin além de loopback; * desativa a verificação. Necessário para um bind fora de loopback.
  • MCP_REQUEST_TIMEOUT_MS, MCP_HEADERS_TIMEOUT_MS, MCP_KEEP_ALIVE_TIMEOUT_MS limites de tempo de requisição, padrões 120000, 30000, 65000
  • MCP_MAX_BODY_BYTES limite do corpo de requisição MCP, padrão 1048576
  • MCP_READY_PROBE_INTERVAL_MS e MCP_READY_MAX_AGE_MS cadência e frescor da sondagem de readiness, padrões 30000 e 90000
  • MCP_APP_ENABLED para oferecer o beta SQD Explorer a hosts compatíveis, padrão desligado. Aceita true ou 1. ?app=1 e ?app=0 por conexão o substituem.
  • MCP_TOOL_WEIGHT_BUDGET para limitar o custo combinado de chamadas de ferramenta ativas, padrão 32. Perfis medidos permitem até 32 lookups, 4 chamadas raw ou summary, ou 2 chamadas analytics por vez, enquanto o trabalho enfileirado permanece ciente de cancelamento.
  • MCP_TOOL_MAX_QUEUE para limitar chamadas de ferramenta enfileiradas, padrão 64
  • MCP_TOOL_QUEUE_TIMEOUT_MS para limitar o tempo de espera de admissão de ferramentas, padrão 5000
  • MCP_TOOL_CLIENT_WEIGHT_SHARE percentual do orçamento de peso que um chamador (uma conexão, identificada por um endereço com hash) pode manter por vez, padrão 50; nunca abaixo da ferramenta única mais pesada para que toda ferramenta permaneça agendável. MCP_TOOL_CLIENT_MAX_QUEUE limita as chamadas enfileiradas de um chamador, padrão 16. Um chamador acima de sua cota recebe o resultado retryable overloaded com reason: client_share enquanto outros continuam fluindo.
  • MCP_TRUST_PROXY definido como 1 (ou o número de proxies na frente do servidor) para basear a justiça no endereço que esses proxies observaram em vez do endereço do socket. O cabeçalho é lido somente quando o peer imediato é ele próprio um proxy confiável, e o salto é contado da direita de X-Forwarded-For, porque um chamador pode escrever qualquer coisa à esquerda dele. O endereço é hasheado e nunca armazenado ou rotulado.
  • MCP_TRUSTED_PROXY_PREFIXES uma lista separada por vírgulas de prefixos de endereço que contam como seus proxies, correspondidos contra o início do endereço do peer (por exemplo 203.0.113. ou 2606:4700:). Definir isso substitui o padrão em vez de adicionar a ele, então inclua loopback ou seu intervalo privado se um proxy co-localizado também alcançar o servidor. Com isso não definido, loopback e intervalos privados são confiáveis, que é onde um proxy co-localizado fica; em uma rede privada compartilhada, isso significa que qualquer host nessa rede pode apresentar um endereço encaminhado, então nomeie seus proxies explicitamente lá.
  • MCP_SLOW_REQUEST_MS limite para uma linha JSON em stderr por chamada de ferramenta lenta com tempos de espera de admissão e execução e a família de cliente limitada, padrão 5000.

Guardrails de custo

Todo limite de varredura no servidor é compilado e definido por ferramenta: uma varredura de trace filtrada para em 5.000 blocos, uma busca de implantação de contrato em 1.000.000. Guardrails adicionam um segundo teto acima desses que uma implantação define a partir do ambiente, para que um endpoint sob carga possa ser reduzido sem uma nova imagem.

  • MCP_GUARDRAIL_MODE um de off (padrão), shadow ou enforce.
  • MCP_GUARDRAIL_<CLASS>_<LIMIT> define um teto, onde <CLASS> é LOOKUP, RAW_QUERY, SUMMARY ou ANALYTICS, e <LIMIT> é MAX_SCAN_BLOCKS, MAX_WINDOW_SECONDS ou MAX_UPSTREAM_BYTES. Por exemplo MCP_GUARDRAIL_RAW_QUERY_MAX_SCAN_BLOCKS=50000.

Não há padrões numéricos. Uma classe sem nada definido não tem teto extra, então off e enforce sem nada configurado são o mesmo servidor. A única maneira de um guardrail mudar o comportamento é se você definir um número.

shadow avalia cada teto e registra o que a aplicação teria feito, sem mudar uma única resposta. enforce age:

  • Uma varredura acima de seu teto para no teto e reporta o que cobriu pelo mesmo caminho de cobertura parcial que uma varredura que atinge seu limite compilado já usa, então _coverage.result_complete se torna false e a resposta nomeia os blocos que pesquisou. Nunca afirma uma resposta completa que não obteve.
  • Uma janela de consulta acima de seu teto é recusada antes que qualquer coisa seja buscada, com o limite nomeado no erro e os próximos passos, porque não há resultado parcial para retornar para uma requisição que nunca foi permitida começar.

Quatro contadores, todos com rótulos limitados: mcp_guardrail_admitted_total{class}, mcp_guardrail_would_block_total{class,limit}, mcp_guardrail_blocked_total{class,limit} e mcp_guardrail_fail_open_total{reason}.

Rollout recomendado. Defina os tetos que você está considerando e execute shadow por uma semana. Leia mcp_guardrail_would_block_total: é exatamente o conjunto de requisições reais que o teto teria cortado. Se esse conjunto for maior do que você esperava, o teto está errado, não o tráfego. Mude para enforce quando estiver do tamanho que você pretendia.

Traces

Métricas dizem com que frequência e por quanto tempo; um trace diz onde o tempo foi gasto dentro de uma chamada. Traces estão desligados a menos que você defina OTEL_EXPORTER_OTLP_ENDPOINT. Com isso não definido, nada aqui é importado, alocado ou enviado, e os pacotes OpenTelemetry não precisam ser instalados.

O SDK não é uma dependência deste pacote. Ele e seu exporter puxam cerca de 74 pacotes contra um tarball publicado de aproximadamente 3,4MB, e quase ninguém executando isso via stdio quer qualquer parte disso, então são declarados como peers opcionais. Para ligar traces, instale-os junto com o servidor e aponte para seu coletor:

npm i @opentelemetry/sdk-node @opentelemetry/exporter-trace-otlp-http

OTEL_EXPORTER_OTLP_ENDPOINT=http://collector:4318

Uma chamada de ferramenta é uma árvore:

mcp.request                       (HTTP only: method, transport)
└─ tools/call portal_evm_query_logs
   ├─ mcp.admission               (the wait for a slot)
   ├─ portal.fetch                (one per attempt: dataset, status, bytes, resend count)
   ├─ portal.fetch
   └─ mcp.format_result           (hashing the answer for the evidence receipt)

Variáveis OTEL_* são lidas pelo próprio SDK OpenTelemetry, então amostragem, cabeçalhos, batching e protocolo são configurados da maneira padrão. O resto:

  • Um traceparent na requisição HTTP, ou no _meta da chamada de ferramenta, faz a chamada parte do trace do chamador em vez de iniciar um novo. O valor _meta vence, porque é a afirmação mais específica sobre a qual turno esta chamada pertence.
  • Cada requisição do Portal carrega um traceparent nomeando seu próprio span de fetch, então um trace do lado do Portal pode se juntar a este. Nada é adicionado quando tracing está desligado.
  • As linhas de log JSON carregam trace_id e span_id enquanto tracing está ligado, então um evento de log e seu span podem ser encontrados um a partir do outro.
  • /health reporta se tracing está configurado, se iniciou e se a captura de argumentos está ligada.

Atributos de span não carregam argumentos, endereços, hashes, cursores ou texto livre. Eles são o nome da ferramenta, sua classe de trabalho, o dataset, contagens limitadas e um resultado limitado. Um span deixa o processo para um coletor que a própria consulta nunca alcança, então a regra é a que os rótulos de métrica seguem, e mais estrita que os logs, que pelo menos ficam no seu próprio stderr. MCP_OTEL_INCLUDE_ARGS=1 adiciona os argumentos brutos da ferramenta ao span da ferramenta. Está desligado por padrão e inseguro para produção: um argumento de ferramenta é rotineiramente um endereço de carteira, e frequentemente as próprias palavras de um usuário.

Testes

npm run test:offline compila, faz lint, typecheck, executa os testes unitários e executa toda suíte que não precisa de acesso ao Portal. npm run test:live executa as suítes apoiadas pelo Portal. RELEASE_ASSURANCE.md resume o que um release verifica, e scripts/README.md lista toda suíte.

Licença

MIT