Universal EVM Interfacing Nexus (U-EIN)

This advanced Model Context Protocol (MCP) nexus acts as an abstraction layer, offering a consolidated interface for interaction across numerous EVM-compliant ledgers. It empowers intelligent agents to interface uniformly with Ethereum, Polygon, Arbitrum, Optimism, Base, and a sprawling collection of other chains.

📋 Structural Outline

• Introduction
• Core Capabilities
• Network Coverage
• System Prerequisites
• Deployment Procedure
• Operational Configuration
• Execution Guide
• Interface Specification
• Actionable Tools
• Data Endpoints
• Safety Protocols
• Source Directory Layout
• Contribution Guidelines
• Legal Notice

🔭 Introduction

The U-EIN leverages the MCP specification to expose robust blockchain functionalities to consuming AI entities. It abstracts complexity across multiple domains:

• Extraction of ledger metrics (e.g., account balances, transaction records, block headers).
• Execution of smart contract methods.
• Facilitation of asset transfers (native currency, ERC-20, ERC-721, ERC-1155).
• Retrieval of token metadata and ownership records.
• Native support for over thirty EVM substrates.
• Automated ENS Resolution: All inputs expecting Ethereum addresses inherently accept human-friendly names (e.g., 'vitalik.eth'), which are dynamically translated to their cryptographic equivalents.

All functionalities are presented through standardized MCP tooling, ensuring easy discoverability and utilization by agents. Any tool function accepting an address automatically handles ENS name lookups.

✨ Core Capabilities

Ledger Data Access

• Multi-Substrate Compatibility: Support spanning 30+ EVM networks.
• Chain Metadata: Access to crucial data like the current block height, chain identifier, and RPC endpoints.
• Block Retrieval: Fetching data by height, hash, or the most recent block.
• Transaction Insight: Deep inspection of transaction status and decoded event logs from receipts.
• Account Valuation: Querying native coin balances and balances for all standardized token types.
• Human-Address Abstraction: Seamless use of ENS identifiers like 'vitalik.eth' in place of raw 0x addresses.

Token Management

• Fungible Tokens (ERC-20)
• Fetching token metrics (nomenclature, ticker, precision, total supply).
• Verifying individual or total token holdings.
• Initiating token dispersal between accounts.

• Granting spending authority to external contracts.

• Non-Fungible Tokens (ERC-721)

• Retrieving collection and unique item metadata.
• Validating asset custodianship.
• Transferring digital collectibles.

• Obtaining token URI paths and quantifying owned items.

• Multi-Token Standard (ERC-1155)

• Querying specific token quantities and associated metadata.
• Dispersing specified quantities of fungible/non-fungible items.
• Accessing token metadata links.

Contract Interaction Layer

• State Reading: Executing contract view/pure methods to read data.
• State Writing: Dispatching transactions that alter contract state, requiring private key authorization for signing.
• Identity Verification: Distinguishing between externally owned accounts (EOAs) and contract addresses.
• Event Log Harvesting: Filtering and retrieving historical or real-time event data.

Transaction Orchestration

• Native Coin Transfers: Sending primary assets across all supported chains.
• Fee Projection: Estimating computational expenditure (gas) for transaction planning.
• Confirmation Tracking: Monitoring transaction finality and receipt acquisition.
• Failure Reporting: Robust error diagnostics with descriptive feedback.

🌐 Network Coverage

Primary Mainnets

• Ethereum (ETH)
• Optimism (OP)
• Arbitrum (ARB)
• Arbitrum Nova
• Base
• Polygon (MATIC)
• Polygon zkEVM
• Avalanche (AVAX)
• Binance Smart Chain (BSC)
• zkSync Era
• Linea
• Celo
• Gnosis (xDai)
• Fantom (FTM)
• Filecoin (FIL)
• Moonbeam
• Moonriver
• Cronos
• Scroll
• Mantle
• Manta
• Blast
• Fraxtal
• Mode
• Metis
• Kroma
• Zora
• Aurora
• Canto

Auxiliary Testnets

• Sepolia
• Optimism Sepolia
• Arbitrum Sepolia
• Base Sepolia
• Polygon Amoy
• Avalanche Fuji
• BSC Testnet
• zkSync Sepolia
• Linea Sepolia
• Scroll Sepolia
• Mantle Sepolia
• Manta Sepolia
• Blast Sepolia
• Fraxtal Testnet
• Mode Testnet
• Metis Sepolia
• Kroma Sepolia
• Zora Sepolia
• Celo Alfajores
• Goerli
• Holesky

🛠️ System Prerequisites

• Runtime Environment: Bun version 1.0.0 or later.
• Alternative Runtime: Node.js version 18.0.0 or newer (if Bun is not utilized).

📦 Deployment Procedure

bash

Obtain the source code repository

git clone https://github.com/yourusername/mcp-evm-server.git cd mcp-evm-server

Install dependencies using Bun's manager

bun install

Alternative: Using npm

npm install

⚙️ Operational Configuration

The gateway employs the following default initialization parameters:

• Default Ledger Identifier: 1 (Ethereum Mainnet)
• Listening Port: 3001
• Binding Interface: 0.0.0.0 (Allows external interface binding)

These values are static definitions within the code. Modifications require editing:

• Chain specifications: src/core/chains.ts
• Server binding: src/server/http-server.ts

🚀 Execution Guide

Direct Execution via npx (No Local Install Needed)

The U-EIN can be launched directly without prior repository cloning, using npx:

bash

Execute in standard input/output mode (suitable for CLI tools)

npx @mcpdotdirect/evm-mcp-server

Execute in listening HTTP server mode

npx @mcpdotdirect/evm-mcp-server --http

Local Server Startup

Initiate the server using stdio for embedding within command-line utilities:

bash

Launch stdio instance

bun start

Development mode with hot reloading

bun dev

Alternatively, start the HTTP listener which supports Server-Sent Events (SSE) for front-end clients:

bash

Launch HTTP listener

bun start:http

Development mode with hot reloading for HTTP

bun dev:http

Client Connectivity

Integrate with this MCP gateway using any client library compliant with the Model Context Protocol. For diagnostic purposes, the MCP Inspector is recommended.

Integration within Cursor IDE

To establish a persistent link with the U-EIN within Cursor:

1. Access Cursor Settings (the cogwheel icon).
2. Navigate to the 'Features' panel.
3. Locate the 'MCP Servers' segment.
4. Select 'Add new MCP server'.

5. Input the following parameters:

6. Server identifier: unified-evm-context-gateway

7. Type: command

8. Command: npx @mcpdotdirect/evm-mcp-server

9. Confirm the addition.

Once configured, the gateway will be available for activation/deactivation in the server list, enabling direct blockchain interactions within the IDE environment.

Utilizing Project-Scoped Configuration (mcp.json)

For shareable and version-controlled setup definitions, create an .cursor/mcp.json file at the root of your repository:

{ "mcpServers": { "evm-gateway-stdio": { "command": "npx", "args": ["-y", "@mcpdotdirect/evm-mcp-server"] }, "evm-gateway-http": { "command": "npx", "args": ["-y", "@mcpdotdirect/evm-mcp-server", "--http"] } } }

Placing this file in the .cursor directory allows Cursor to automatically recognize and offer these configurations upon project opening. This is ideal for:

1. Standardizing team MCP setups.
2. Integrating the setup into source control.
3. Managing distinct configurations per project.

Example: HTTP Mode with SSE Endpoint

For web-based clients requiring real-time updates via Server-Sent Events (SSE) from the HTTP instance:

{ "mcpServers": { "evm-gateway-sse": { "url": "http://localhost:3001/sse" } } }

This bypasses command execution by connecting directly to the designated SSE path, suitable for:

• Browser-based applications querying the MCP service.
• Environments where executing external binaries is restricted.
• Sharing a centralized gateway resource.

Example Workflow: Querying Balance via ENS in Cursor

After setting up the configuration via mcp.json:

1. Create a script file, for instance, ledger_check.ts:

javascript // ledger-check.ts async function main() { try { // Requesting ETH balance for a human-readable name on the default network console.log("Assessing ETH holdings for vitalik.eth...");

// Cursor can execute requests like: "Fetch the ETH balance for vitalik.eth on Ethereum Mainnet"
// The U-EIN handles the name resolution transparently.

// This leverages the AI agent's ability to issue complex blockchain operations
// through natural language, powered by the unified gateway.

} catch (error) { console.error("Operation Failure:", error.message); } }

main();

1. With the file active in Cursor, prompt the assistant to:

2. "Determine the present ETH value held by vitalik.eth."

3. "Look up the market quote for USDC on the Arbitrum network."

4. "Identify the most recent transaction hash on Polygon."

5. The U-EIN manages the underlying RPC communications, transforming the natural language request into verifiable on-chain actions.

Connecting via Claude CLI

For users employing the Claude command-line interface:

bash

Register the gateway

claude mcp add unified-evm-context-gateway npx @mcpdotdirect/evm-mcp-server

Launch Claude with the new gateway enabled

claude

Code Example: Native Balance Retrieval with ENS

javascript // Illustrative use of the underlying MCP client library against the HTTP endpoint const client = new McpClient("http://localhost:3001");

const record = await client.invokeTool("get-balance", { address: "vitalik.eth", // ENS input is valid network: "ethereum", });

console.log(record); // Expected Output Structure: // { network: "ethereum", resolvedAddress: "0xd8dA...", balance: "3.14159..." }

📚 Interface Specification

Actionable Tools

The gateway exposes the following set of verifiable MCP actions. Address inputs are resolvable via ENS names across the entire toolset.

Tool Identifier	Purpose	Essential Input Parameters (Address inputs support ENS)
get-token-metadata	Fetch ERC-20 descriptive data	tokenAddress, network
query-token-holding	Check specific ERC-20 token quantity	tokenAddress, ownerAddress, network
dispatch-token-transfer	Send ERC-20 assets	privateKey, tokenAddress, toAddress, amount, network
grant-token-allowance	Authorize external spending (ERC-20)	privateKey, tokenAddress, spenderAddress, amount, network
retrieve-nft-details	Get NFT metadata (ERC-721)	tokenAddress, tokenId, network
verify-nft-custody	Confirm NFT ownership	tokenAddress, tokenId, ownerAddress, network
relocate-nft	Transfer ownership of an NFT	privateKey, tokenAddress, tokenId, toAddress, network
count-nfts	Determine NFT count per owner	tokenAddress, ownerAddress, network
get-erc1155-asset-uri	Fetch URI for ERC-1155 item	tokenAddress, tokenId, network
check-erc1155-quantity	Query ERC-1155 balance	tokenAddress, tokenId, ownerAddress, network
move-erc1155-assets	Transfer ERC-1155 tokens by quantity	privateKey, tokenAddress, tokenId, amount, toAddress, network

Tool Identifier	Purpose	Essential Input Parameters (Address inputs support ENS)
fetch-chain-parameters	Retrieve network operational data	network
get-native-balance	Query primary currency balance	address, network
disperse-native-coin	Send primary chain assets	privateKey, to, amount, network
examine-transaction	Retrieve full transaction record	txHash, network
read-smart-state	Execute view/pure contract functions	contractAddress, abi, functionName, args, network
invoke-smart-write	Execute state-modifying contract calls	contractAddress, abi, functionName, args, privateKey, network
assess-address-type	Determine if an address is a contract	address, network
resolve-name-to-addr	Translate ENS name to cryptographic ID	ensName, network

Data Endpoints

The system exposes ledger state via these standardized MCP resource paths. Address placeholders within URIs are subject to automatic ENS resolution.

Resource URI Template	Description
evm://{network}/ledger-meta	Metadata for a specified network
evm://chain	Ethereum Mainnet metadata (default)
evm://{network}/ledger/block/{height}	Block data indexed by sequential number
evm://{network}/ledger/block/current	Latest finalized block data
evm://{network}/asset/native/{address}/value	Native currency value held by an account
evm://{network}/transaction/{hash}	Detailed transaction execution report
evm://{network}/transaction/{hash}/receipt	Transaction final status and emitted events

Resource URI Template	Description
evm://{network}/token/{tokenAddress}	ERC-20 token metadata description
evm://{network}/token/{tokenAddress}/balance/{address}	Specific ERC-20 holding calculation
evm://{network}/asset/nft/{tokenAddress}/{tokenId}	ERC-721 unique asset information
evm://{network}/asset/nft/{tokenAddress}/{tokenId}/owner	Custodian verification for an NFT
evm://{network}/asset/erc1155/{tokenAddress}/{tokenId}/uri-link	Metadata pointer for ERC-1155 variant
evm://{network}/asset/erc1155/{tokenAddress}/{tokenId}/holding/{address}	Specific ERC-1155 quantity held by an address

🔒 Safety Protocols

• Ephemeral Keys: Signing keys required for outgoing transactions are processed transiently and are never persisted on the server.
• Access Control: Implement external authorization layers (e.g., API keys) for production deployment.
• Transport Security: Mandate HTTPS when exposing the HTTP interface externally.
• Abuse Mitigation: Integrate flow control mechanisms (rate limiting) to prevent denial-of-service attacks.
• High-Value Operations: Mandate secondary verification checkpoints for irreversible, high-capital transactions.

📁 Source Directory Layout

mcp-evm-server/ ├── src/ │ ├── index.ts # Primary entry point for stdio communication │ ├── server/ # Server instantiation modules │ │ ├── http-server.ts # HTTP listener implementation (incl. SSE) │ │ └── server.ts # General server setup utilities │ ├── core/ │ │ ├── chains.ts # Network definitions and utility mappings │ │ ├── resources.ts # MCP resource implementation logic │ │ ├── tools.ts # MCP tool function mappings │ │ ├── prompts.ts # Agent prompting templates (if applicable) │ │ └── services/ # Encapsulated blockchain execution logic │ │ ├── index.ts # Service export registry │ │ ├── balance.ts # Balance querying operations │ │ ├── transfer.ts # Asset movement primitives │ │ ├── utils.ts # Common helper functions │ │ ├── tokens.ts # Token metadata and ERC logic │ │ ├── contracts.ts # Smart contract invocation logic │ │ ├── transactions.ts # Transaction lifecycle management │ │ └── blocks.ts # Block data retrieval │ │ └── clients.ts # RPC connection handling ├── package.json ├── tsconfig.json └── README.md

🛠️ Contribution Guidelines

To enhance or extend the gateway:

1. Implement new operational primitives within the relevant file in src/core/services/.
2. Register the new action in src/core/tools.ts.
3. Register new read endpoints in src/core/resources.ts.
4. Define any new network parameters in src/core/chains.ts.
5. Adjust initial operational parameters within src/server/http-server.ts.

📄 Legal Notice

This software is distributed under the provisions of the MIT License.