SQD Portal

Servidor MCP de SQD Portal

Un servidor MCP que responde preguntas sobre blockchain a partir de los datos de SQD Portal: transacciones, registros, trazas, transferencias de tokens, carteras, análisis, series temporales y velas en redes EVM, Solana, Bitcoin, Substrate, Hyperliquid y Tron, con un Explorador opcional integrado en el host.

El servidor no indexa cadenas por sí mismo. Valida la entrada, planifica consultas acotadas al Portal y devuelve resultados con metadatos de cobertura, frescura, paginación y evidencia para que un asistente pueda decir exactamente lo que vio. No se requiere cuenta de SQD, clave de API ni credencial de cliente.

Habla el protocolo MCP sin estado 2026-07-28 a través de HTTP y stdio, y mantiene la ruta de negociación heredada gestionada por el SDK para clientes que aún están implementando esa revisión. Las notas de versión están en CHANGELOG.md. Consulta CONTRIBUTING.md para trabajar en el código y SECURITY.md para reportar una vulnerabilidad.

Superficie pública actual

• 28 herramientas públicas
• 3 herramientas avanzadas/de depuración
• los parámetros públicos usan network
• los filtros de descubrimiento usan vm
• sin alias de herramientas heredados en v0.8.x

Las herramientas de consulta sin procesar devuelven respuestas compactas por defecto. Solicita response_format: "full" solo cuando necesites el payload más grande.

Las preguntas sobre entidades pueden usar portal_resolve_entity primero. Resuelve símbolos/direcciones de tokens EVM, alias de contratos EVM, identificadores de pools, nombres de protocolos y nombres de monedas de Hyperliquid en filtros listos para consulta, manteniendo explícitas las coincidencias ambiguas.

La resolución de símbolos de tokens y los metadatos de tokens provienen de datos abiertos de listas de tokens, no de constantes de direcciones de tokens integradas. Las respuestas incluyen avisos explícitos cuando los datos de la lista de tokens no están disponibles, están desactualizados o no son compatibles con una red.

Las preguntas sobre carteras deben comenzar con portal_get_wallet_summary. Devuelve fund_flow por defecto, incluyendo movimientos entrantes/salientes, flujos de activos, contrapartes, movimientos más grandes observados y siguientes pivotes de evidencia antes del análisis detallado con herramientas sin procesar.

Grupos de herramientas

Descubrimiento:

• portal_list_networks
• portal_get_network_info
• portal_get_head
• portal_resolve_entity

Conveniencia entre cadenas:

• 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

Avanzadas/depuración:

• portal_debug_query_blocks
• portal_debug_resolve_time_to_block
• portal_debug_hyperliquid_query_replica_commands

Estos grupos también son los conjuntos de herramientas (discovery, convenience, evm, solana, bitcoin, substrate, hyperliquid, tron, debug). Un despliegue puede recortar el catálogo con MCP_TOOLSETS o MCP_TOOLS, y una conexión HTTP puede reducirlo aún más con ?toolsets= o un encabezado X-MCP-Toolsets; consulta las notas de despliegue HTTP. Sin configuración, se sirve la superficie completa de 31 herramientas, y el endpoint alojado mantiene ese valor por defecto.

Datos compatibles

• Redes EVM indexadas por Portal, incluyendo Base, Ethereum, Optimism, Arbitrum, Monad, Hyperliquid EVM y muchas otras
• Transacciones nativas de Tron (transferencias TRX, transferencias TRC-10, llamadas a contratos con registros en línea y transacciones internas) y registros de eventos TVM como transferencias TRC-20, con direcciones Base58 o hex, montos exactos de TRX y el hash de la transacción padre en cada registro; la habilidad del plugin SQD incluido documenta la API Stream sin procesar para cualquier cosa más allá de eso
• Mainnet de Solana
• Mainnet de Bitcoin
• Rellenos de Hyperliquid y comandos de réplica
• Redes Substrate indexadas por Portal

El soporte de Substrate es actualmente solo histórico. No tiene cola en tiempo real.

Forma de la respuesta

La mayoría de las herramientas devuelven el mismo sobre en MCP structuredContent y en un respaldo de texto JSON compacto para clientes más antiguos. El sobre contiene un cuerpo de resultado normal más metadatos compartidos como:

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

investigation es una guía de evidencia compacta para agentes: identifica la ruta de resultado principal, la ventana acotada, campos pivote útiles como direcciones o hashes de transacciones, filtros de seguimiento y limitaciones antes de que un resultado se trate como completo. Los resultados materiales exitosos también llevan un recibo _evidence con argumentos canónicos, un resumen determinista, reconciliación de filas, ventanas de origen y semántica de reproducción exacta o semántica. Los recibos exactos fijan su ventana de evidencia. Los recibos semánticos revelan que volver a ejecutar una ventana relativa móvil puede devolver una instantánea más reciente.

Cuando una respuesta usa datos estimados, parciales, muestreados, limitados o paginados, la respuesta de nivel superior y los metadatos lo revelan. _pagination.has_more es verdadero exactamente cuando next_cursor está presente, y _coverage indica si la ventana solicitada se leyó por completo (window_complete) y si la respuesta contiene todas las filas coincidentes (result_complete). Los seguimientos de paginación seguros incluyen metadatos de llamada a herramienta ejecutables con argumentos de cursor explícitos; las sugerencias que no se pueden reconstruir de forma segura se marcan como no ejecutables.

Las herramientas orientadas a gráficos también devuelven descriptores de gráficos y tablas para que los clientes MCP o LLMs puedan renderizarlos sin ingeniería inversa del payload.

Explorador SQD (beta)

SQD Explorer es una aplicación MCP que renderiza resultados de herramientas dentro de hosts que admiten aplicaciones MCP. Está en beta y desactivado por defecto. Un despliegue por defecto responde con structuredContent y solo texto JSON compacto, y ningún resultado de herramienta pide a un host que abra una interfaz de usuario. Hay dos formas de optar por participar:

• Una conexión: agrega ?app=1 al endpoint, por ejemplo https://portal.sqd.dev/mcp?app=1. Usa esto para probar la beta sin cambiar nada para otros usuarios.
• Despliegue completo: establece MCP_APP_ENABLED=true. Una conexión aún puede anularlo en cualquier dirección, por lo que ?app=0 excluye a un solo cliente.

El recurso de la aplicación permanece registrado de cualquier manera, por lo que un host puede leerlo directamente sin que nadie opte por participar.

Cuando está habilitado, los hosts compatibles reciben una tarjeta en línea ajustada a su contenido y un espacio de trabajo de pantalla completa para 21 herramientas de datos: métricas lideradas por el número principal, gráficos de múltiples series y valores firmados, velas de precios con volumen vinculado y una lectura fija, paneles clasificados y de línea de tiempo que muestran diez filas con un control Mostrar todo, tablas de evidencia que paginan diez filas con búsqueda en cada fila, enlaces de explorador para direcciones, hashes y bloques, logotipos y nombres de cadenas de los metadatos de red de SQD, controles de continuación, historial de la sesión actual y exportación JSON o CSV a través del host. La inspección con puntero y teclado expone los valores trazados exactos. Los buckets faltantes permanecen visibles como espacios, los identificadores no se acortan y cualquier límite local de filas es separado de la completitud del servidor. Los seguimientos fallidos mantienen el último resultado bueno bajo el error. La aplicación es autónoma y no usa almacenamiento persistente del navegador; sus únicas solicitudes del lado del navegador son imágenes de logotipos de cadenas de cdn.subsquid.io y sqd.dev, los dos orígenes declarados en el CSP del recurso. Los hosts sin soporte de aplicaciones MCP reciben el mismo structuredContent y respaldo de texto JSON compacto, por lo que la respuesta subyacente nunca depende de la interfaz de usuario. docs/explorer-design.md registra las reglas de diseño que sigue la aplicación.

Tres prompts MCP proporcionan puntos de partida reproducibles sin agregar herramientas:

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

Para una demostración centrada en gráficos, pregunta: Show BTC price action and trading volume on Hyperliquid for the past hour, using five-minute candles. Explain whether the final candle is closed. El resultado abre el Explorador SQD con un gráfico de velas, volumen, una tabla de evidencia, límites de tiempo solicitados e indexados y un recibo. Reproduce los requested_window_start_timestamp y requested_window_end_exclusive devueltos como entradas fijas from_timestamp y to_timestamp cuando necesites una ejecución de verificación estable.

Pruébalo en Claude

El endpoint alojado tiene el Explorador desactivado, por lo que un nuevo usuario opta por su propia conexión:

1. En claude.ai o Claude Desktop, abre Configuración → Conectores → Agregar conector personalizado, ingresa https://portal.sqd.dev/mcp?app=1 y elige sin autenticación. El ?app=1 activa la beta solo para esta conexión. En Claude Desktop puedes instalar sqd.mcpb desde la última versión y activar su configuración "SQD Explorer (beta)".
2. Inicia un nuevo chat y habilita el conector SQD para él.
3. Haz una pregunta de datos. Cualquiera de estas llega a una herramienta que lleva el Explorador:
   • What has this wallet been doing on Base lately? con una dirección (resumen de cartera)
   • Show me recent activity on Ethereum (actividad reciente)
   • Chart hourly transaction counts on Base for the last day (serie temporal)

El resultado se renderiza como una tarjeta en línea en lugar de un bloque de texto; abre la tarjeta para el espacio de trabajo de pantalla completa. Solo las 21 herramientas de datos llevan el Explorador. Una pregunta de catálogo como Which networks do you support? llama a portal_list_networks y responde en texto plano, lo cual es esperado en lugar de un fallo.

Instalación

npm install
npm run build

Ejecución

stdio:

npm start

HTTP:

npm run start:http

Descubrimiento para desarrolladores

El servidor expone una guía estructurada de selección de herramientas para constructores de clientes:

• El recurso MCP sqd://tools devuelve metadatos de herramientas agrupados, ejemplos, puntos de partida y notas de integración.
• El recurso MCP sqd://tools/{name} devuelve la entrada de la guía para una herramienta, por ejemplo sqd://tools/portal_get_time_series.

El descubrimiento de herramientas y recursos permanece en el propio protocolo MCP. El servidor no mantiene un catálogo HTTP duplicado.

Plugin de Codex

El envoltorio del plugin de Codex vive en plugins/portal y usa por defecto el endpoint MCP alojado en https://portal.sqd.dev/mcp.

Instálalo desde este marketplace local del repositorio:

codex plugin marketplace add .
codex plugin add portal@sqd

Abre un nuevo hilo de Codex después de instalar. Los prompts de primer uso incluyen rellenos de BTC perpetuo de Hyperliquid, volumen reciente de transacciones en Base y las últimas transferencias de USDC en Base.

Plugin de Claude Code

El plugin de Claude Code usa el mismo endpoint MCP alojado y el mismo selector público:

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

Abre una nueva sesión de Claude Code después de instalar para que las herramientas MCP de SQD se carguen.

Grok

El chat de Grok puede usar SQD como conector personalizado:

1. Abre grok.com/connectors.
2. Elige Nuevo conector, luego Personalizado.
3. Ingresa https://portal.sqd.dev/mcp como la URL del servidor MCP.
4. Deja la autenticación sin configurar.

Grok Build lee los plugins de Claude Code directamente, por lo que usa el mismo paquete:

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

ChatGPT

En un espacio de trabajo con aplicaciones MCP personalizadas habilitadas, abre Configuración → Aplicaciones → Crear, ingresa https://portal.sqd.dev/mcp, elige sin autenticación, escanea las herramientas y crea el borrador de la aplicación. El servidor es de solo lectura y no requiere credenciales de usuario.

Claude Desktop

Descarga sqd.mcpb de la última versión y ábrelo: Claude Desktop instala el paquete con un clic y lista las 31 herramientas. El paquete incluye el servidor, sus dependencias de producción y una configuración opcional, "SQD Explorer (beta)", que está desactivada por defecto. Necesita Node 22 o más reciente en la máquina.

Respaldo manual, desde un clon local después de npm run build, agrega una 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

• Si no conoces el nombre exacto de la red, comienza con portal_list_networks.
• Si necesitas estado indexado reciente, usa portal_get_network_info o portal_get_head primero.
• Si la pregunta es amplia, comienza con portal_get_recent_activity, portal_get_wallet_summary o portal_get_time_series antes de pasar a consultas sin procesar.
• Las ventanas de tiempo aceptan redacción compacta y natural como 30m, past 30 minutes, in the past 1h, in last 38 mins, last hour o 30 minutes ago.
• Usa portal_evm_get_ohlc y portal_hyperliquid_get_ohlc solo cuando realmente necesites salida en forma de velas.
• Para consultas grandes o exploratorias, prefiere response_format: "compact" a menos que necesites la forma completa del registro.

Notas de despliegue HTTP

El modo HTTP expone MCP en / y /mcp, el liveness en /health y el readiness en /ready. El servicio alojado expone la misma respuesta de salud versionada en https://portal.sqd.dev/mcp/health.

• Los endpoints de MCP y salud no requieren autenticación.
• El descubrimiento de herramientas y recursos utiliza el protocolo MCP; las rutas retiradas /tools y /tools.json devuelven 404.
• Establezca MCP_CURSOR_SECRET en cualquier despliegue que ejecute más de un proceso, para que un cursor emitido por una instancia sea aceptado por la siguiente. Si no se establece, cada proceso firma con su propia clave aleatoria y un cursor deja de funcionar tras un reinicio o un salto de balanceo de carga.
• /health informa de version y commit, el commit de git desde el que se construyó la imagen, y cada resultado de herramienta repite ambos en _server. Etiquetas de Docker Hub: latest, X.Y.Z y X.Y provienen solo de una etiqueta de lanzamiento v*; edge y sha-<commit> provienen de cada push a main. Fije una etiqueta de versión en producción.
• /ready es 200 solo después de que el catálogo de conjuntos de datos se haya cargado una vez y la última sonda de Portal haya tenido éxito dentro de MCP_READY_MAX_AGE_MS; de lo contrario, es 503 con un reason y Retry-After. Apunte las comprobaciones de readiness del orquestador a /ready y las de liveness a /health. El HEALTHCHECK de la imagen Docker utiliza /ready.
• El servidor se vincula a 127.0.0.1 a menos que MCP_BIND indique lo contrario, y cada ruta comprueba el encabezado Host (y Origin, cuando un navegador envía uno) contra una lista de permitidos, de modo que una página de rebote de DNS no pueda alcanzar una instancia local. Los hosts y orígenes de bucle local siempre pasan; las solicitudes sin Origin siempre pasan la comprobación de origen. Un enlace que no sea de bucle local debe establecer MCP_ALLOWED_HOSTS y MCP_ALLOWED_ORIGINS; si falta alguno, el servidor registra un error de inicio y sirve sin esa comprobación. La imagen Docker establece MCP_BIND=0.0.0.0, así que establezca ambas variables en el despliegue, o * detrás de un proxy que ya las valide.
• Cada solicitud está limitada: encabezados dentro de MCP_HEADERS_TIMEOUT_MS, toda la solicitud dentro de MCP_REQUEST_TIMEOUT_MS, keep-alive inactivo dentro de MCP_KEEP_ALIVE_TIMEOUT_MS, y los cuerpos MCP por encima de MCP_MAX_BODY_BYTES se rechazan con 413 antes del análisis (411 para un cuerpo fragmentado sin longitud).

Variables de entorno útiles:

• MCP_CURSOR_SECRET la clave con la que se firman los cursores de paginación. Establézcala en cualquier despliegue que ejecute más de un proceso. Si no se establece, cada proceso firma con su propia clave aleatoria, por lo que un cursor emitido por una instancia es rechazado por la siguiente y los clientes pierden su lugar tras un reinicio o un salto de balanceo de carga. También es lo que impide que un llamador acuñe un cursor para una ventana que la herramienta nunca habría ofrecido.
• MCP_TOOLSETS conjuntos de herramientas separados por comas para servir (discovery, convenience, evm, solana, bitcoin, substrate, hyperliquid, tron, debug; all o default para todo). Los nombres desconocidos se ignoran con un error de inicio. Gana sobre MCP_TOOLS. Predeterminado: los nueve, el catálogo completo de 31 herramientas.
• MCP_TOOLS nombres exactos de herramientas separados por comas para servir cuando MCP_TOOLSETS no está establecido.
• Por conexión, ?toolsets=evm en la URL del endpoint o un encabezado X-MCP-Toolsets: evm reduce el conjunto del despliegue solo para esa conexión; nunca puede agregar un conjunto de herramientas. Los prompts que hacen referencia a una herramienta fuera del conjunto activo no se ofrecen. El conjunto activo es una etiqueta limitada (all, un nombre de conjunto de herramientas o custom) en mcp_tool_client_calls_total.
• MCP_BIND interfaz en la que escuchar, predeterminado 127.0.0.1 (0.0.0.0 en la imagen Docker)
• MCP_ALLOWED_HOSTS nombres de host separados por comas aceptados en Host (se ignora el puerto) además del bucle local; * desactiva la comprobación. Requerido para un enlace que no sea de bucle local.
• MCP_ALLOWED_ORIGINS nombres de host separados por comas aceptados en Origin además del bucle local; * desactiva la comprobación. Requerido para un enlace que no sea de bucle local.
• MCP_REQUEST_TIMEOUT_MS, MCP_HEADERS_TIMEOUT_MS, MCP_KEEP_ALIVE_TIMEOUT_MS límites de tiempo de solicitud, predeterminados 120000, 30000, 65000
• MCP_MAX_BODY_BYTES límite del cuerpo de solicitud MCP, predeterminado 1048576
• MCP_READY_PROBE_INTERVAL_MS y MCP_READY_MAX_AGE_MS cadencia y frescura de la sonda de readiness, predeterminados 30000 y 90000
• MCP_APP_ENABLED para ofrecer el SQD Explorer beta a hosts compatibles, predeterminado desactivado. Acepta true o 1. Los ?app=1 y ?app=0 por conexión lo anulan.
• MCP_TOOL_WEIGHT_BUDGET para limitar el costo combinado de llamadas de herramienta activas, predeterminado 32. Los perfiles medidos permiten hasta 32 búsquedas, 4 llamadas raw o summary, o 2 llamadas de análisis a la vez mientras el trabajo en cola permanece consciente de la cancelación.
• MCP_TOOL_MAX_QUEUE para limitar las llamadas de herramienta en cola, predeterminado 64
• MCP_TOOL_QUEUE_TIMEOUT_MS para limitar el tiempo de espera de admisión de herramientas, predeterminado 5000
• MCP_TOOL_CLIENT_WEIGHT_SHARE porcentaje del presupuesto de peso que un llamador (una conexión, identificada por una dirección con hash) puede mantener a la vez, predeterminado 50; nunca por debajo de la herramienta individual más pesada para que cada herramienta siga siendo programable. MCP_TOOL_CLIENT_MAX_QUEUE limita las llamadas en cola de un llamador, predeterminado 16. Un llamador que supere su parte obtiene el resultado reintentable overloaded con reason: client_share mientras otros siguen fluyendo.
• MCP_TRUST_PROXY establecido en 1 (o en el número de proxies frente al servidor) para basar la equidad en la dirección que esos proxies observaron en lugar de la dirección del socket. El encabezado se lee solo cuando el par inmediato es en sí mismo un proxy de confianza, y el salto se cuenta desde la derecha de X-Forwarded-For, porque un llamador puede escribir cualquier cosa a la izquierda de él. La dirección se somete a hash y nunca se almacena ni etiqueta.
• MCP_TRUSTED_PROXY_PREFIXES una lista separada por comas de prefijos de dirección que cuentan como sus proxies, comparados con el inicio de la dirección del par (por ejemplo 203.0.113. o 2606:4700:). Establecerlo reemplaza el predeterminado en lugar de agregarlo, así que incluya el bucle local o su rango privado si un proxy co-ubicado también alcanza el servidor. Sin establecer, se confía en el bucle local y los rangos privados, que es donde se encuentra un proxy co-ubicado; en una red privada compartida eso significa que cualquier host en esa red puede presentar una dirección reenviada, así que nombre sus proxies explícitamente allí.
• MCP_SLOW_REQUEST_MS umbral para una línea JSON en stderr por llamada de herramienta lenta con tiempos de espera de admisión y ejecución y la familia de cliente limitada, predeterminado 5000.

Salvaguardas de costo

Cada límite de escaneo en el servidor está compilado y establecido por herramienta: un escaneo de trazas filtrado se detiene en 5,000 bloques, una búsqueda de despliegue de contratos en 1,000,000. Las salvaguardas agregan un segundo techo por encima de esos que un despliegue establece desde el entorno, de modo que un endpoint bajo carga pueda reducirse sin una nueva imagen.

• MCP_GUARDRAIL_MODE uno de off (predeterminado), shadow o enforce.
• MCP_GUARDRAIL_<CLASS>_<LIMIT> establece un techo, donde <CLASS> es LOOKUP, RAW_QUERY, SUMMARY o ANALYTICS, y <LIMIT> es MAX_SCAN_BLOCKS, MAX_WINDOW_SECONDS o MAX_UPSTREAM_BYTES. Por ejemplo MCP_GUARDRAIL_RAW_QUERY_MAX_SCAN_BLOCKS=50000.

No hay predeterminados numéricos. Una clase sin nada establecido no tiene techo adicional, por lo que off y enforce sin nada configurado son el mismo servidor. La única forma en que una salvaguarda cambia el comportamiento es si establece un número.

shadow evalúa cada techo y registra lo que la aplicación habría hecho, sin cambiar una sola respuesta. enforce actúa:

• Un escaneo sobre su techo se detiene en el techo e informa lo que cubrió a través del mismo camino de cobertura parcial que un escaneo que alcanza su límite compilado ya usa, por lo que _coverage.result_complete se convierte en false y la respuesta nombra los bloques que buscó. Nunca afirma una respuesta completa que no obtuvo.
• Una ventana de consulta sobre su techo se rechaza antes de obtener cualquier cosa, con el límite nombrado en el error y los siguientes pasos, porque no hay resultado parcial que devolver para una solicitud a la que nunca se le permitió comenzar.

Cuatro contadores, todos con etiquetas limitadas: mcp_guardrail_admitted_total{class}, mcp_guardrail_would_block_total{class,limit}, mcp_guardrail_blocked_total{class,limit} y mcp_guardrail_fail_open_total{reason}.

Despliegue recomendado. Establezca los techos que está considerando y ejecute shadow durante una semana. Lea mcp_guardrail_would_block_total: es exactamente el conjunto de solicitudes reales que el techo habría cortado. Si ese conjunto es más grande de lo esperado, el techo está mal, no el tráfico. Cambie a enforce una vez que tenga el tamaño que pretendía.

Trazas

Las métricas dicen con qué frecuencia y durante cuánto tiempo; una traza dice dónde se fue el tiempo dentro de una llamada. Las trazas están desactivadas a menos que establezca OTEL_EXPORTER_OTLP_ENDPOINT. Sin establecer, nada aquí se importa, asigna o envía, y los paquetes de OpenTelemetry no necesitan instalarse en absoluto.

El SDK no es una dependencia de este paquete. Él y su exportador arrastran alrededor de 74 paquetes contra un tarball publicado de aproximadamente 3.4MB, y casi nadie que ejecute esto sobre stdio quiere algo de eso, por lo que se declaran como pares opcionales. Para activar las trazas, instálelos junto al servidor y apúntelo a su colector:

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

OTEL_EXPORTER_OTLP_ENDPOINT=http://collector:4318

Una llamada de herramienta es un árbol:

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)

Las variables OTEL_* son leídas por el propio SDK de OpenTelemetry, por lo que el muestreo, los encabezados, el procesamiento por lotes y el protocolo se configuran de la manera estándar. El resto:

• Un traceparent en la solicitud HTTP, o en el _meta de la llamada de herramienta, hace que la llamada sea parte de la traza del llamador en lugar de comenzar una nueva. El valor _meta gana, porque es la afirmación más específica sobre a qué turno pertenece esta llamada.
• Cada solicitud de Portal lleva un traceparent que nombra su propio span de fetch, de modo que una traza del lado de Portal pueda unirse a esta. No se agrega nada cuando las trazas están desactivadas.
• Las líneas de registro JSON llevan trace_id y span_id mientras las trazas están activadas, de modo que un evento de registro y su span puedan buscarse entre sí.
• /health informa si las trazas están configuradas, si comenzaron y si la captura de argumentos está activada.

Los atributos de span no llevan argumentos, direcciones, hashes, cursores ni texto libre. Son el nombre de la herramienta, su clase de trabajo, el conjunto de datos, conteos limitados y un resultado limitado. Un span sale del proceso hacia un colector al que la consulta en sí nunca llega, por lo que la regla es la que siguen las etiquetas de métricas, y más estricta que los registros, que al menos permanecen en su propio stderr. MCP_OTEL_INCLUDE_ARGS=1 agrega los argumentos de herramienta sin procesar al span de herramienta. Está desactivado por predeterminado y no es seguro para producción: un argumento de herramienta es rutinariamente una dirección de billetera, y a menudo las propias palabras de un usuario.

Pruebas

npm run test:offline compila, ejecuta lint, verifica tipos, ejecuta las pruebas unitarias y ejecuta cada suite que no necesita acceso a Portal. npm run test:live ejecuta las suites respaldadas por Portal. RELEASE_ASSURANCE.md resume lo que verifica un lanzamiento, y scripts/README.md enumera cada suite.

Licencia

MIT