mcp-tenderly

AI 어시스턴트에게 EVM 트랜잭션을 시뮬레이션하고 왜 되돌아가는지(revert) 디버깅할 수 있는 능력을 제공하는 MCP 서버입니다. Tenderly의 무료 티어 시뮬레이션 API를 사용합니다.

"이 트랜잭션이 작동할까?" 또는 "왜 실패했을까?"라고 물어보면, 추측이 아닌 실제 포크된 체인 상태에 기반한 답변을 얻을 수 있습니다 — 디코딩된 호출 추적, 되돌림 이유, 정확한 소스 라인까지.

어떤 것도 브로드캐스트되지 않습니다. 시뮬레이션은 포크에 대해 읽기 전용이므로 자유롭게 실행해도 안전합니다.

왜 존재하는가

온체인 트랜잭션에 대해 추론하는 어시스턴트는 일반적으로 맹목적으로 작업합니다. 계약 소스는 읽을 수 있지만, 현재 상태에 대해 호출이 되돌아가는지, 실제 가스 비용이 얼마인지, 또는 여덟 개의 중첩된 delegatecall 중 어느 것이 실패했는지 알 수 없습니다. Tenderly는 이 세 가지를 모두 답할 수 있으며, 시뮬레이션 API는 무료 계정에서 사용할 수 있습니다.

어려운 부분은 API를 호출하는 것이 아닙니다 — 실제 DeFi 트랜잭션에 대한 simulation_type: "full" 응답은 종종 1메가바이트가 넘는 JSON입니다. 모든 접촉된 저장 슬롯에 대한 상태 차이, 수백 프레임 깊이의 호출 트리. 그것을 모델에 전달하는 것은 비용도 너무 많이 들고 쓸모도 없습니다. "왜 이게 되돌아갔는지"에 대한 답은 그 안에 묻힌 네 줄이기 때문입니다.

그래서 이 서버의 진짜 작업은 포맷터입니다. 결과를 먼저 보여주고, 그 다음 되돌림 이유와 소스 매핑된 프레임, 디코딩된 이벤트, 들여쓰기된 ASCII 다이어그램으로 된 호출 트리를 보여줍니다 — 그리고 무언가를 잘라냈을 때 항상 명시합니다. 조용한 제한은 "그게 전부였다"로 읽히기 때문입니다.

Related MCP server: evmscope

빠른 시작

Node.js 22.12 이상이 필요합니다.

1. Tenderly 자격 증명 얻기

세 가지 모두 무료 Tenderly 계정에서 얻을 수 있습니다:

두 슬러그 모두 URL 슬러그이며 표시 이름이 아닙니다 — "My Project"로 표시된 프로젝트는 일반적으로 my-project입니다. 서버는 시작 시 이를 검증하고, 나중에 404로 표면화되게 두지 않고 어떤 변수가 잘못되었는지 알려줍니다.

2. 클라이언트에 서버 등록

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 또는 기타 MCP 호스트 — 클라이언트의 MCP 구성 파일에 추가:

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

로컬 클론에서 실행

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

그런 다음 클라이언트를 빌드 출력으로 지정하고, <repo>를 클론의 절대 경로로 바꿉니다:

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

도구

tenderly_simulate_transaction

포크된 체인 상태에 대해 하나의 트랜잭션을 시뮬레이션합니다. 성공 또는 되돌림, 사용된 가스, 계약이 검증된 경우 소스 매핑된 스택 추적이 포함된 되돌림 이유, 디코딩된 이벤트, 토큰 전송, 디코딩된 호출 추적을 반환합니다.

network를 이름(base, arbitrum, polygon, sepolia, …) 또는 숫자 체인 ID로 받고, 일반적인 트랜잭션 필드(from, to, data, value, gas, gas_price), 선택적 block_number(포크 기준), 그리고 잔액, 논스, 저장 슬롯 또는 바이트코드를 위조하기 위한 state_overrides를 받습니다.

tenderly_simulate_bundle

최대 20개의 트랜잭션을 공유 상태에 대해 순서대로 시뮬레이션하여 각각 이전 트랜잭션의 효과를 볼 수 있습니다. 이는 한 번에 하나씩 확인할 수 없는 흐름을 위한 도구입니다 — 승인 후 스왑, 배포 후 초기화, 또는 익스플로잇 시퀀스 재생. 시퀀스에서 어떤 단계가 깨졌는지 보고합니다.

tenderly_get_simulation

저장된 시뮬레이션을 ID로 조회하고 결과와 전체 호출 추적을 렌더링합니다. 잘린 추적을 더 깊이 파고들거나, 기본적으로 생략된 상태 차이를 가져오거나, 이전에 생성되었거나 Tenderly UI에서 만든 시뮬레이션을 검사하는 데 사용하세요.

이 도구의 동작을 결정짓는 한 가지 알아둘 점: Tenderly의 저장된 시뮬레이션 레코드는 메타데이터만 저장합니다 — 입력, 가스, 상태, 오류 메시지. 호출 추적은 보관되지 않습니다. 따라서 추적은 기록된 블록에서 기록된 입력을 재생하여 재현되며, 이는 충실합니다(동일한 포크, 동일한 결과) 하지만 요율 제한에 대해 한 번의 시뮬레이션을 소모합니다. 재생은 저장되지 않으므로 저장된 시뮬레이션 할당량을 소비하지 않습니다. 저렴한 메타데이터 전용 조회를 위해 reconstruct_trace: false를 전달하세요.

tenderly_list_simulations

프로젝트의 최근 저장된 시뮬레이션을 한 줄씩 나열하여 ID를 찾습니다.

출력 크기 제어

모든 읽기 도구는 동일한 출력 제어를 받습니다. 기본값은 일반적인 응답을 저렴하게 유지하도록 조정되어 있습니다:

전체 Tenderly 추적은 저장 및 로그 opcode를 실제 호출과 섞습니다 — 단순한 USDC 전송은 네 개의 실제 호출 주위에 수십 개의 SLOAD를 생성하고, DeFi 트랜잭션은 수백 개를 생성합니다. 그대로 두면 프레임 예산을 소비하고 되돌림을 설명하는 호출을 출력 밖으로 밀어내므로 기본적으로 숨겨지고 개수가 보고됩니다. 내부 Solidity 함수 프레임(JUMPDEST)은 유지됩니다: 그것들은 라이브러리나 프록시를 통해 되돌림을 추적할 수 있게 해줍니다.

무료 티어 참고 사항

이 서버는 의도적으로 무료 플랜에서 작동하는 v1 시뮬레이션 REST 엔드포인트만 사용합니다: /simulate, /simulate-bundle, /simulations 및 /simulations/{id}. Web3 Gateway, DevNets, Virtual TestNets, Alerts 또는 Actions API는 절대 접촉하지 않습니다 — 그것들은 유료이거나 OAuth로 보호되며, 접근하면 대상 사용자에게 혼란스럽게 실패할 수 있습니다.

할당량에 대해 알아야 할 두 가지:

• 저장된 시뮬레이션은 할당량을 소비합니다. 기본적으로 시뮬레이션은 저장됩니다. 디버깅할 때 대시보드 URL은 매우 가치가 있기 때문입니다. TENDERLY_SAVE_SIMULATIONS=false로 설정하거나 호출별로 save: false를 전달하여 일시적으로 유지하세요.

• 요율 제한은 429를 생성합니다. 클라이언트는 백오프로 재시도하고 Retry-After를 존중한 다음, 멈추지 않고 제한을 명확히 보고합니다.

선택적 구성

보안 및 신뢰 모델

시뮬레이션은 절대 브로드캐스트하지 않습니다. 모든 호출은 Tenderly 포크에 대해 읽기 전용입니다. 트랜잭션은 서명되거나 전송되지 않으며, 서버는 Tenderly 액세스 토큰 외에 키를 보유하지 않습니다.

아웃바운드 호스트는 하나입니다. 서버는 api.tenderly.co에만 통신합니다. 다른 곳은 접촉하지 않으며, 텔레메트리는 수집되지 않습니다.

액세스 토큰은 출력에 남지 않습니다. X-Access-Key 헤더로만 전송되며, 어떤 로그 레벨에서도 기록되지 않고, 오류 메시지와 경로에서 제외됩니다. 테스트는 stdout과 stderr 모두에 없음을 확인합니다.

시뮬레이션 출력은 신뢰할 수 없는 입력으로 취급됩니다. 이것은 놓치기 쉬우므로 이해할 가치가 있습니다. 계약 이름, 토큰 기호, 함수 이름, 디코딩된 문자열, 검증된 소스 라인, 되돌림 이유는 모두 계약을 배포한 사람이 제어합니다 — 그리고 이 서버의 목적은 아직 신뢰하지 않는 계약을 가리키는 것입니다. 계약은 원하는 어떤 문자열로도 revert()할 수 있으며, 이는 출력에서 가장 눈에 띄는 위치에 놓입니다.

따라서 모든 그러한 텍스트는 렌더링 전에 살균기를 통과합니다: 공백은 한 줄로 축소되고, 제로 너비 및 양방향 재정의 문자는 제거되며, 길이는 명시된 잘림으로 제한됩니다. 이는 적대적인 체인 데이터가 마크다운 제목, 목록 항목 또는 모델에게 데이터가 아닌 지침으로 읽힐 수 있는 다른 것을 위조하는 것을 방지합니다. 이는 구조적 방어이며 악의적인 의도를 감지하려는 시도가 아닙니다 — 신뢰할 수 없는 텍스트는 단순히 속한 필드를 벗어날 수 없습니다. 일반적인 되돌림 문자열은 영향을 받지 않습니다.

이것은 적대적인 계약의 출력을 진실로 만들지 않고 단지 불활성으로 만듭니다. 시뮬레이션 결과를 신뢰할 수 없는 코드에 대한 보고서로 취급하세요. 그것이 바로 그것입니다.

문제 해결

서버가 구성 메시지와 함께 즉시 종료됩니다. 이는 설계된 것입니다 — 첫 번째 도구 호출에서 실패하는 대신 시작을 거부합니다. 메시지는 문제가 있는 변수를 명명합니다. 종료 코드는 78(EX_CONFIG)입니다.

401 또는 403. 토큰은 계정 설정의 액세스 토큰이어야 하며, 프로젝트 비밀 또는 RPC 키가 아니어야 하고, TENDERLY_ACCOUNT_SLUG에 대한 액세스 권한이 있는 계정에 속해야 합니다.

404. 거의 항상 슬러그 문제입니다: 표시 이름 대신 슬러그, 또는 account/project가 하나의 변수에 붙여넣어진 경우.

실패 시 되돌림 이유 없음. 계약이 검증되지 않았거나 사용자 정의 오류를 사용했을 가능성이 있습니다. 호출 추적은 여전히 실패한 프레임을 식별하며, 선택기가 표시되어 조회할 수 있습니다.

모든 것이 비어 보입니다. include_raw_response: true로 다시 실행하여 Tenderly가 실제로 반환한 것을 확인하세요.

서버 로그는 stderr에 JSON으로 기록됩니다 — MCP 클라이언트의 서버 로그 보기를 확인하세요. API 키는 절대 기록되지 않습니다.

개발

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는 CI가 실행하는 것과 정확히 동일합니다 — 워크플로 YAML은 .github/scripts/verify.sh만 호출하므로 로컬에서 재현할 수 없는 것은 없습니다.

아키텍처와 변경 전에 알아야 할 설계 결정은 CLAUDE.md를 참조하세요.

라이선스

MIT