mcp-tenderly

Un servidor MCP que permite a un asistente de IA simular transacciones EVM y depurar por qué revierten, usando la API de simulación gratuita de Tenderly.

Pregunta "¿funcionaría esta transacción?" o "¿por qué falló?" y obtén una respuesta basada en el estado real de una cadena bifurcada (fork): el rastro de llamadas decodificado, el motivo del revert, la línea exacta del código fuente — en lugar de una suposición.

Nada se transmite jamás. Las simulaciones son de solo lectura contra un fork, por lo que se pueden ejecutar libremente sin riesgo.

Por qué existe esto

Un asistente que razona sobre una transacción on-chain normalmente trabaja a ciegas: puede leer el código fuente del contrato, pero no puede decirte si una llamada revierte contra el estado actual, cuánto cuesta realmente el gas, ni cuál de ocho delegatecalls anidadas es la que falló. Tenderly puede responder a las tres preguntas, y su API de simulación se puede usar con una cuenta gratuita.

La parte difícil no es llamar a la API — es que una respuesta simulation_type: "full" para una transacción DeFi real suele ser más de un megabyte de JSON: un diff de estado sobre cada slot de almacenamiento tocado, un árbol de llamadas de cientos de niveles de profundidad. Entregar eso a un modelo es a la vez inasumible e inútil, porque la respuesta a "por qué revierte" son cuatro líneas enterradas en medio.

Así que el trabajo real de este servidor es el formateador: pone el resultado primero, luego el motivo del revert y el frame con mapeo de código fuente, luego los eventos decodificados, y luego el árbol de llamadas como un diagrama ASCII indentado — y siempre indica cuándo ha truncado algo, porque un límite silencioso se lee como "eso era todo".

Related MCP server: evmscope

Inicio rápido

Requiere Node.js 22.12 o superior.

1. Obtén las credenciales de Tenderly

Las tres provienen de una cuenta gratuita de Tenderly:

Ambos slugs son los slugs de URL, no los nombres mostrados — un proyecto mostrado como "Mi Proyecto" suele ser mi-proyecto. El servidor valida esto al inicio y te dice qué variable está mal en lugar de dejar que aparezca más tarde como un 404.

2. Registra el servidor con tu cliente

Claude Code

claude mcp add tenderly \
  -e TENDERLY_API_KEY=your-token \
  -e TENDERLY_ACCOUNT_SLUG=your-account \
  -e TENDERLY_PROJECT_SLUG=your-project \
  -- npx -y mcp-tenderly

Claude Desktop, Cursor o cualquier otro host MCP — añade al archivo de configuración MCP del cliente:

{
  "mcpServers": {
    "tenderly": {
      "command": "npx",
      "args": ["-y", "mcp-tenderly"],
      "env": {
        "TENDERLY_API_KEY": "your-token",
        "TENDERLY_ACCOUNT_SLUG": "your-account",
        "TENDERLY_PROJECT_SLUG": "your-project"
      }
    }
  }
}

Ejecutar desde un clon local

git clone https://github.com/py-zoid/mcp-tenderly.git
cd mcp-tenderly
npm install
npm run build

Luego apunta el cliente a la salida de la compilación, reemplazando <repo> con la ruta absoluta a tu clon:

{
  "mcpServers": {
    "tenderly": {
      "command": "node",
      "args": ["<repo>/dist/index.js"],
      "env": { "TENDERLY_API_KEY": "…", "TENDERLY_ACCOUNT_SLUG": "…", "TENDERLY_PROJECT_SLUG": "…" }
    }
  }
}

Herramientas

tenderly_simulate_transaction

Simula una transacción contra el estado de la cadena bifurcada. Devuelve éxito o revert, gas usado, el motivo del revert con un rastro de pila con mapeo de código fuente donde el contrato está verificado, eventos decodificados, transferencias de tokens y el rastro de llamadas decodificado.

Acepta network como nombre (base, arbitrum, polygon, sepolia, …) o un id de cadena numérico, los campos habituales de transacción (from, to, data, value, gas, gas_price), un block_number opcional para bifurcar desde ahí, y state_overrides para simular saldos, nonces, slots de almacenamiento o bytecode.

tenderly_simulate_bundle

Simula hasta 20 transacciones en orden contra estado compartido, de modo que cada una vea los efectos de las anteriores. Esta es la herramienta para flujos que no se pueden comprobar una transacción a la vez — aprobar y luego intercambiar, desplegar y luego inicializar, o reproducir una secuencia de explotación. Informa qué paso de la secuencia se rompió.

tenderly_get_simulation

Busca una simulación guardada por id y renderiza su resultado y el rastro de llamadas completo. Úsala para profundizar en un rastro que fue truncado, para extraer el diff de estado que se omite por defecto, o para inspeccionar una simulación creada anteriormente o desde la interfaz de Tenderly.

Una cosa que vale la pena saber, porque da forma a cómo se comporta esta herramienta: el registro de simulación guardada de Tenderly almacena solo metadatos — entradas, gas, estado, mensaje de error. El rastro de llamadas no se conserva. Así que el rastro se reproduce re-ejecutando las entradas registradas en el bloque registrado, lo cual es fiel (mismo fork, mismo resultado) pero cuesta una simulación contra tu límite de tasa. La reproducción no se guarda, por lo que no consume cuota de simulaciones almacenadas. Pasa reconstruct_trace: false para una búsqueda barata solo de metadatos.

tenderly_list_simulations

Lista las simulaciones guardadas recientes en el proyecto, una por línea, para encontrar un id.

Controlar el tamaño de la salida

Cada herramienta de lectura acepta los mismos controles de salida. Los valores por defecto están ajustados para mantener una respuesta típica asequible:

Un rastro completo de Tenderly intercala opcodes de almacenamiento y registro con llamadas reales — una transferencia simple de USDC produce una docena de SLOADs alrededor de cuatro llamadas reales, y una transacción DeFi produce cientos. Si se dejan, consumen el presupuesto de marcos y sacan de la salida las llamadas que explican un revert, así que están ocultos por defecto y se informa del recuento. Los marcos de funciones internas de Solidity (JUMPDEST) se conservan: son los que te permiten seguir un revert a través de una biblioteca o proxy.

Notas sobre el plan gratuito

Este servidor usa deliberadamente solo los endpoints REST de simulación v1 que funcionan en un plan gratuito: /simulate, /simulate-bundle, /simulations y /simulations/{id}. Nunca toca la Web3 Gateway, DevNets, Virtual TestNets, Alertas ni la API de Acciones — esos son de pago o están protegidos por OAuth, y recurrir a ellos haría que el servidor fallara de forma confusa para exactamente los usuarios a los que se dirige.

Dos cosas que saber sobre la cuota:

• Las simulaciones guardadas consumen cuota. Por defecto las simulaciones se guardan, porque una URL del panel vale mucho al depurar. Establece TENDERLY_SAVE_SIMULATIONS=false, o pasa save: false por llamada, para mantenerlas efímeras.

• Los límites de tasa producen un 429. El cliente reintenta estos con retroceso, respetando Retry-After, y luego informa del límite claramente en lugar de colgarse.

Configuración opcional

Modelo de seguridad y confianza

Las simulaciones nunca se transmiten. Cada llamada es de solo lectura contra un fork de Tenderly. No se firma ni se envía ninguna transacción, y el servidor no tiene claves más allá de tu token de acceso de Tenderly.

Un solo host de salida. El servidor solo habla con api.tenderly.co. No se contacta con nada más, y no se recopila telemetría.

Tu token de acceso no aparece en la salida. Se envía solo como cabecera X-Access-Key, nunca se registra en ningún nivel de registro, y se excluye de mensajes de error y rutas. Una prueba verifica que no está presente ni en stdout ni en stderr.

La salida de simulación se trata como entrada no confiable. Esta es la que vale la pena entender, porque es fácil pasarla por alto. Los nombres de contratos, símbolos de tokens, nombres de funciones, cadenas decodificadas, líneas de código fuente verificadas y motivos de revert están controlados por quien desplegó el contrato — y el punto de este servidor es apuntarlo a contratos que aún no confías. Un contrato puede revert() con cualquier cadena que quiera, que aterriza en la posición más prominente de la salida.

Así que todo ese texto se pasa por un saneador antes de renderizar: el espacio en blanco se colapsa a una sola línea, se eliminan los caracteres de ancho cero y de anulación bidireccional, y la longitud se limita con el truncado indicado. Eso evita que los datos hostiles de la cadena forjen un encabezado de markdown, un elemento de lista o cualquier otra cosa que pudiera leerse como instrucciones para un modelo en lugar de como datos. Es una defensa estructural, no un intento de detectar intención maliciosa — el texto no confiable simplemente no puede escapar del campo al que pertenece. Las cadenas de revert ordinarias no se ven afectadas.

Esto no hace que la salida de un contrato hostil sea verdadera, solo inerte. Trata un resultado de simulación como un informe sobre código no confiable, que es lo que es.

Solución de problemas

El servidor sale inmediatamente con un mensaje de configuración. Eso es por diseño — se niega a arrancar en lugar de fallar dentro de tu primera llamada de herramienta. El mensaje nombra la variable culpable. El código de salida es 78 (EX_CONFIG).

401 o 403. El token debe ser un Token de acceso de Configuración de cuenta, no un secreto de proyecto ni una clave RPC, y debe pertenecer a una cuenta con acceso a TENDERLY_ACCOUNT_SLUG.

404. Casi siempre un problema de slug: nombre mostrado en lugar de slug, o cuenta/proyecto pegado en una variable.

Sin motivo de revert en un fallo. El contrato probablemente no está verificado, o usó un error personalizado. El rastro de llamadas aún identifica el marco que falla, y se muestra el selector para que puedas buscarlo.

Todo parece vacío. Vuelve a ejecutar con include_raw_response: true para ver lo que Tenderly devolvió realmente.

Los registros del servidor van a stderr como JSON — consulta la vista de registros del servidor de tu cliente MCP. La clave de API nunca se registra.

Desarrollo

npm install        # also installs the git hooks via core.hooksPath
npm run verify     # everything CI runs: format, lint, types, unit, stdio smoke
npm test           # unit tests only
npm run test:smoke # builds, then drives dist/index.js over real stdio

npm run verify es exactamente lo que ejecuta CI — el YAML del flujo de trabajo solo invoca .github/scripts/verify.sh, así que no hay nada que no puedas reproducir localmente.

Consulta CLAUDE.md para la arquitectura y las decisiones de diseño que vale la pena conocer antes de cambiar nada.

Licencia

MIT