How to Use the Etherscan MCP in Mastra AI

Build resilient web3 workflows in Mastra AI that automatically retry failed Etherscan queries and handle rate limits.

See Vinkius in Action

Works with every AI agent you already use

…and any MCP-compatible client

MCP Servers - Free for Subscribers

Connect Etherscan MCP to Mastra AI

Create your Vinkius account to connect Etherscan to Mastra AI and route execution through our secure gateway. The platform manages server hosting, runtime updates, and security layers. Configuration requires no manual server provisioning.

GDPR Free for Subscribers

Setup Etherscan with Mastra AI

Ask AI about this MCP

ChatGPT

Claude

Perplexity

Conditional On-Chain Workflows

Gas spikes break automated transactions, which is why this MCP Server provides live network conditions. Before executing a trade, your Mastra AI agent checks `get_gas_oracle` and `get_block_number` to evaluate chain congestion. If the base fee is too high, the workflow engine branches. It pauses, waits for a new block, and retries the gas check with exponential backoff. You stop wasting ETH on failed transactions because the agent actually respects network conditions.

Automated Contract Verification

Deploying contracts programmatically requires immediate verification, and these tools handle the compilation checks. Your Mastra agent can take a newly deployed address and immediately fire `verify_source_code` with the raw compiler output. If the verification fails due to Etherscan indexing delays, Mastra catches the error. The built-in retry logic waits a few seconds and tries again. Once verified, it pulls the `get_abi` to confirm the interface matches your local build.

Deep Transaction Audits

Tracing stolen funds means digging through internal calls, a task this server simplifies. Your agent uses `get_tx_list_internal` and `get_logs` to map out exactly where the ETH went across complex DeFi routing contracts. When an RPC node drops the connection mid-query, Mastra doesn't crash. It picks up the pagination right where it left off. You get the full history without babysitting the script.

Setup guide

Set up Etherscan MCP in Mastra AI

Prerequisites

Node.js 18+ and a TypeScript project
@mastra/mcp + @mastra/core packages
Active Vinkius subscription with a valid endpoint token

1

Install dependencies
Run npm install @mastra/mcp @mastra/core plus your preferred model provider (e.g. @ai-sdk/openai).
2

Configure the MCPClient
Create an MCPClient with your Vinkius endpoint as a URL object. Replace [YOUR_TOKEN_HERE] with your token from cloud.vinkius.com.
3

Discover and inject tools
Call mcpClient.listTools() and spread the result into your agent's tools object. All Etherscan tools become native Mastra tools.
4

Run with any model
Swap openai("gpt-4o") for any AI SDK-compatible provider. Call agent.generate() and the agent routes tool calls through MCP automatically.

agent.ts

import { MCPClient } from "@mastra/mcp";
import { Agent } from "@mastra/core/agent";
import { openai } from "@ai-sdk/openai";

const mcpClient = new MCPClient({
  id: "etherscan-mcp-client",
  servers: {
    "etherscan-mcp": {
      url: new URL(
        "https://edge.vinkius.com/[YOUR_TOKEN_HERE]/mcp"
      ),
    },
  },
});

const agent = new Agent({
  name: "Etherscan Agent",
  model: openai("gpt-4o"),
  instructions: "You have access to Etherscan tools.",
  tools: {
    ...(await mcpClient.listTools()),
  },
});

const result = await agent.generate(
  "List recent Etherscan transactions"
);
console.log(result.text);

Get your connection token →

Independent Platform Disclaimer: Vinkius is an independent platform and is not affiliated with, endorsed by, sponsored by, verified by, or otherwise authorized by Etherscan. All third-party trademarks, logos, and brand names are the property of their respective owners. Their use on this website is strictly for informational purposes to identify service compatibility and interoperability.

Why Choose Vinkius

Vinkius connects your tools to AI with real-time monitoring and automatic cost savings — all from one dashboard.

Connect Etherscan now

Real-time monitoring

Live

visibility into every interaction

Connect your favorite tools to your AI and see exactly what's happening — every request, every response, in real time.

Built-in savings

60%

lower AI costs

Vinkius compresses data between your apps and your AI automatically. Lower bills every month — no configuration required.

Single dashboard

One

place for every integration

Every tool your AI connects to, managed from a single screen. One account, complete control.

Common questions about Etherscan MCP in Mastra AI

Run npm install @mastra/mcp@latest. Instantiate an MCPClient with your Vinkius server URL. Call listTools() and spread them into your Mastra Agent configuration.

Yes. The framework automatically handles timeouts and 429 rate limits from Etherscan. It applies exponential backoff before attempting the query again.

You can configure requireToolApproval for sensitive actions. Though these are read-only data tools, you might want a human to review the output of a massive `get_tx_list` pull before proceeding.

The client auto-detects the transport protocol. It connects to the Vinkius endpoint via Streamable HTTP or SSE automatically based on the server configuration.

Your authentication tokens never touch persistent storage. When your agent requests `get_address_token_balance`, the Vinkius zero-trust architecture injects the credentials in memory. The sandbox is destroyed the moment the workflow completes.

Use it with your favorite AI tools

Connect this server to Cursor, Claude, VS Code, and more.

OpenAI Agents SDK sdk-python

Google ADK sdk-python

Pydantic AI sdk-python

Vercel AI SDK sdk-typescript