Hyperion MCP Server SDK Guide

Complete SDK guide for integrating with the Hyperion MCP Server via Smithery

📋 Table of Contents

• Quick Start

• Installation

• Authentication

• Available Tools

• Usage Examples

• Error Handling

• Best Practices

🚀 Quick Start

Basic Setup

import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js"
import { Client } from "@modelcontextprotocol/sdk/client/index.js"

// Construct server URL with authentication
const url = new URL("https://server.smithery.ai/@cuongpo/hyperion-mcp-server/mcp")
url.searchParams.set("api_key", "36e96d01-a9dd-4e4c-a705-bbe239a712ea")
url.searchParams.set("profile", "notable-sparrow-IsrW6Y")
const serverUrl = url.toString()

const transport = new StreamableHTTPClientTransport(serverUrl)

// Create MCP client
const client = new Client({
  name: "My Hyperion App",
  version: "1.0.0"
})

await client.connect(transport)

// List available tools
const tools = await client.listTools()
console.log(`Available tools: ${tools.map(t => t.name).join(", ")}`)

📦 Installation

Prerequisites

• Node.js 18+

• npm or yarn package manager

Install MCP SDK

npm install @modelcontextprotocol/sdk

TypeScript Support (Optional)

npm install -D typescript @types/node

🔐 Authentication

The Hyperion MCP Server is hosted on Smithery and requires authentication:

// Your Smithery credentials
const API_KEY = "36e96d01-a9dd-4e4c-a705-bbe239a712ea"
const PROFILE = "notable-sparrow-IsrW6Y"

// Construct authenticated URL
const url = new URL("https://server.smithery.ai/@cuongpo/hyperion-mcp-server/mcp")
url.searchParams.set("api_key", API_KEY)
url.searchParams.set("profile", PROFILE)

🛠️ Available Tools

The Hyperion MCP Server provides 18 comprehensive tools for blockchain interactions:

💼 Wallet Management

create_wallet

Create a new Hyperion wallet with generated mnemonic phrase.

Parameters:

• name (optional): Wallet name

Example:

const result = await client.callTool('create_wallet', {
  name: 'MyWallet'
})

import_wallet

Import existing wallet using private key or mnemonic phrase.

Parameters:

• privateKey (optional): Private key to import

• mnemonic (optional): Mnemonic phrase to import

• name (optional): Wallet name

Example:

const result = await client.callTool('import_wallet', {
  mnemonic: 'your twelve word mnemonic phrase here...',
  name: 'ImportedWallet'
})

list_wallets

List all available wallets.

Parameters: None

Example:

const result = await client.callTool('list_wallets', {})

set_current_wallet

Set the current active wallet for transactions.

Parameters:

• address (required): Wallet address to set as current

Example:

const result = await client.callTool('set_current_wallet', {
  address: '0x742d35Cc6634C0532925a3b8D4C9db96C4b4d4d4'
})

get_current_wallet

Get current active wallet information.

Parameters: None

Example:

const result = await client.callTool('get_current_wallet', {})

💰 Balance & Transactions

get_balance

Get balance of wallet address (native tMETIS or ERC20 tokens).

Parameters:

• address (required): Wallet address to check

• tokenAddress (optional): ERC20 token contract address

Examples:

// Get native tMETIS balance
const nativeBalance = await client.callTool('get_balance', {
  address: '0x742d35Cc6634C0532925a3b8D4C9db96C4b4d4d4'
})

// Get ERC20 token balance
const tokenBalance = await client.callTool('get_balance', {
  address: '0x742d35Cc6634C0532925a3b8D4C9db96C4b4d4d4',
  tokenAddress: '0x1234567890123456789012345678901234567890'
})

send_transaction

Send native tokens or ERC20 tokens to another address.

Parameters:

• to (required): Recipient address

• amount (required): Amount to send (in token units, not wei)

• tokenAddress (optional): ERC20 token contract address

• gasLimit (optional): Gas limit

• gasPrice (optional): Gas price

Examples:

// Send native tMETIS
const nativeTx = await client.callTool('send_transaction', {
  to: '0x742d35Cc6634C0532925a3b8D4C9db96C4b4d4d4',
  amount: '1.5'
})

// Send ERC20 tokens
const tokenTx = await client.callTool('send_transaction', {
  to: '0x742d35Cc6634C0532925a3b8D4C9db96C4b4d4d4',
  amount: '100',
  tokenAddress: '0x1234567890123456789012345678901234567890'
})

get_transaction

Get transaction details by hash.

Parameters:

• hash (required): Transaction hash

Example:

const result = await client.callTool('get_transaction', {
  hash: '0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890'
})

estimate_gas

Estimate gas cost for a transaction.

Parameters:

• to (required): Recipient address

• value (optional): Value to send (in ether)

• data (optional): Transaction data

Example:

const result = await client.callTool('estimate_gas', {
  to: '0x742d35Cc6634C0532925a3b8D4C9db96C4b4d4d4',
  value: '1.0'
})

🔗 Blockchain Queries

get_block

Get block information by number or hash.

Parameters:

• blockNumber (optional): Block number

• blockHash (optional): Block hash

Examples:

// Get block by number
const blockByNumber = await client.callTool('get_block', {
  blockNumber: 12345
})

// Get block by hash
const blockByHash = await client.callTool('get_block', {
  blockHash: '0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890'
})

get_network_info

Get current network information and status.

Parameters: None

Example:

const result = await client.callTool('get_network_info', {})

📄 Smart Contract Interactions

call_contract

Call a smart contract method (read-only).

Parameters:

• contractAddress (required): Smart contract address

• methodName (required): Method name to call

• parameters (optional): Method parameters array

• abi (optional): Contract ABI array

Example:

const result = await client.callTool('call_contract', {
  contractAddress: '0x1234567890123456789012345678901234567890',
  methodName: 'balanceOf',
  parameters: ['0x742d35Cc6634C0532925a3b8D4C9db96C4b4d4d4']
})

send_contract_transaction

Send a transaction to a smart contract method.

Parameters:

• contractAddress (required): Smart contract address

• methodName (required): Method name to call

• parameters (optional): Method parameters array

• abi (optional): Contract ABI array

• value (optional): Ether value to send

• gasLimit (optional): Gas limit

• gasPrice (optional): Gas price

Example:

const result = await client.callTool('send_contract_transaction', {
  contractAddress: '0x1234567890123456789012345678901234567890',
  methodName: 'transfer',
  parameters: ['0x742d35Cc6634C0532925a3b8D4C9db96C4b4d4d4', '1000000000000000000']
})

🪙 ERC20 Token Tools

deploy_erc20_token

Deploy a new ERC20 token contract.

Parameters:

• name (required): Token name (e.g., "My Token")

• symbol (required): Token symbol (e.g., "MTK")

• initialSupply (required): Initial token supply

• decimals (optional): Token decimals (default: 18)

• mintable (optional): Whether token should be mintable (default: false)

• gasLimit (optional): Gas limit

• gasPrice (optional): Gas price

Example:

const result = await client.callTool('deploy_erc20_token', {
  name: 'My Token',
  symbol: 'MTK',
  decimals: 18,
  initialSupply: '1000000',
  mintable: true
})

get_token_info

Get information about an ERC20 token.

Parameters:

• tokenAddress (required): ERC20 token contract address

Example:

const result = await client.callTool('get_token_info', {
  tokenAddress: '0x1234567890123456789012345678901234567890'
})

mint_tokens

Mint tokens (only for mintable tokens).

Parameters:

• tokenAddress (required): ERC20 token contract address

• to (required): Address to mint tokens to

• amount (required): Amount of tokens to mint

• gasLimit (optional): Gas limit

• gasPrice (optional): Gas price

Example:

const result = await client.callTool('mint_tokens', {
  tokenAddress: '0x1234567890123456789012345678901234567890',
  to: '0x742d35Cc6634C0532925a3b8D4C9db96C4b4d4d4',
  amount: '1000'
})

🎨 ERC721 NFT Tools

deploy_erc721_token

Deploy a new ERC721 token contract (NFT).

Parameters:

• name (required): Token name (e.g., "My NFT")

• symbol (required): Token symbol (e.g., "NFT")

• bytecode (required): Compiled contract bytecode (0x...)

• gasLimit (optional): Gas limit for deployment

• gasPrice (optional): Gas price for deployment

Example:

const result = await client.callTool('deploy_erc721_token', {
  name: 'My NFT Collection',
  symbol: 'MYNFT',
  bytecode: '0x608060405234801561001057600080fd5b50...' // Your compiled contract bytecode
})

Note: You need to provide the compiled bytecode for the ERC721 contract. The server includes a reference implementation (HyperionERC721) that extends OpenZeppelin's ERC721URIStorage with minting capabilities.

📝 Usage Examples

Complete Wallet Setup and Transaction Flow

import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js"
import { Client } from "@modelcontextprotocol/sdk/client/index.js"

async function hyperionExample() {
  // Setup client
  const url = new URL("https://server.smithery.ai/@cuongpo/hyperion-mcp-server/mcp")
  url.searchParams.set("api_key", "36e96d01-a9dd-4e4c-a705-bbe239a712ea")
  url.searchParams.set("profile", "notable-sparrow-IsrW6Y")

  const transport = new StreamableHTTPClientTransport(url.toString())
  const client = new Client({
    name: "Hyperion Demo App",
    version: "1.0.0"
  })

  await client.connect(transport)

  try {
    // 1. Create a new wallet
    console.log("Creating wallet...")
    const wallet = await client.callTool('create_wallet', {
      name: 'Demo Wallet'
    })
    console.log(wallet.content[0].text)

    // 2. Get network info
    console.log("Getting network info...")
    const networkInfo = await client.callTool('get_network_info', {})
    console.log(networkInfo.content[0].text)

    // 3. Check balance (will be 0 for new wallet)
    console.log("Checking balance...")
    const balance = await client.callTool('get_balance', {
      address: 'YOUR_WALLET_ADDRESS_HERE'
    })
    console.log(balance.content[0].text)

    // 4. Deploy an ERC20 token
    console.log("Deploying ERC20 token...")
    const tokenDeploy = await client.callTool('deploy_erc20_token', {
      name: 'Demo Token',
      symbol: 'DEMO',
      decimals: 18,
      initialSupply: '1000000',
      mintable: true
    })
    console.log(tokenDeploy.content[0].text)

  } catch (error) {
    console.error('Error:', error)
  }
}

hyperionExample()

ERC20 Token Management

async function tokenManagement() {
  // ... setup client as above ...

  try {
    // Deploy a mintable token
    const deployment = await client.callTool('deploy_erc20_token', {
      name: 'Utility Token',
      symbol: 'UTIL',
      decimals: 18,
      initialSupply: '1000000',
      mintable: true
    })

    // Extract contract address from deployment result
    const contractAddress = 'DEPLOYED_CONTRACT_ADDRESS'

    // Get token information
    const tokenInfo = await client.callTool('get_token_info', {
      tokenAddress: contractAddress
    })
    console.log('Token Info:', tokenInfo.content[0].text)

    // Mint additional tokens
    const mintResult = await client.callTool('mint_tokens', {
      tokenAddress: contractAddress,
      to: '0x742d35Cc6634C0532925a3b8D4C9db96C4b4d4d4',
      amount: '50000'
    })
    console.log('Mint Result:', mintResult.content[0].text)

    // Transfer tokens
    const transferResult = await client.callTool('send_transaction', {
      to: '0x742d35Cc6634C0532925a3b8D4C9db96C4b4d4d4',
      amount: '1000',
      tokenAddress: contractAddress
    })
    console.log('Transfer Result:', transferResult.content[0].text)

  } catch (error) {
    console.error('Token management error:', error)
  }
}

ERC721 NFT Management

async function nftManagement() {
  // ... setup client as above ...

  try {
    // Deploy an ERC721 contract
    // Note: You need to compile the contract first and get the bytecode
    const deployment = await client.callTool('deploy_erc721_token', {
      name: 'My Art Collection',
      symbol: 'ART',
      bytecode: '0x608060405234801561001057600080fd5b50...' // Your compiled bytecode
    })
    console.log('NFT Contract Deployed:', deployment.content[0].text)

    // Extract contract address from deployment result
    const contractAddress = 'DEPLOYED_NFT_CONTRACT_ADDRESS'

    // Mint an NFT using contract interaction
    const mintResult = await client.callTool('send_contract_transaction', {
      contractAddress: contractAddress,
      methodName: 'mint',
      parameters: [
        '0x742d35Cc6634C0532925a3b8D4C9db96C4b4d4d4', // recipient
        'https://ipfs.io/ipfs/QmYourMetadataHash' // tokenURI
      ]
    })
    console.log('NFT Minted:', mintResult.content[0].text)

    // Check NFT ownership
    const owner = await client.callTool('call_contract', {
      contractAddress: contractAddress,
      methodName: 'ownerOf',
      parameters: ['0'] // tokenId
    })
    console.log('NFT Owner:', owner.content[0].text)

    // Get token URI
    const tokenURI = await client.callTool('call_contract', {
      contractAddress: contractAddress,
      methodName: 'tokenURI',
      parameters: ['0'] // tokenId
    })
    console.log('Token URI:', tokenURI.content[0].text)

  } catch (error) {
    console.error('NFT management error:', error)
  }
}

Smart Contract Interaction

async function contractInteraction() {
  // ... setup client as above ...

  const contractAddress = '0x1234567890123456789012345678901234567890'

  try {
    // Read-only contract call
    const balance = await client.callTool('call_contract', {
      contractAddress: contractAddress,
      methodName: 'balanceOf',
      parameters: ['0x742d35Cc6634C0532925a3b8D4C9db96C4b4d4d4']
    })
    console.log('Contract Balance:', balance.content[0].text)

    // Write contract transaction
    const transaction = await client.callTool('send_contract_transaction', {
      contractAddress: contractAddress,
      methodName: 'approve',
      parameters: ['0x742d35Cc6634C0532925a3b8D4C9db96C4b4d4d4', '1000000000000000000']
    })
    console.log('Transaction Result:', transaction.content[0].text)

  } catch (error) {
    console.error('Contract interaction error:', error)
  }
}

⚠️ Error Handling

Common Error Types

async function handleErrors() {
  try {
    const result = await client.callTool('send_transaction', {
      to: '0x742d35Cc6634C0532925a3b8D4C9db96C4b4d4d4',
      amount: '1000'
    })
  } catch (error) {
    if (error.message.includes('insufficient funds')) {
      console.error('Not enough balance for transaction')
    } else if (error.message.includes('invalid address')) {
      console.error('Invalid recipient address')
    } else if (error.message.includes('gas')) {
      console.error('Gas estimation failed or gas limit too low')
    } else {
      console.error('Unknown error:', error.message)
    }
  }
}

Retry Logic

async function withRetry(operation, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await operation()
    } catch (error) {
      if (i === maxRetries - 1) throw error
      console.log(`Attempt ${i + 1} failed, retrying...`)
      await new Promise(resolve => setTimeout(resolve, 1000 * (i + 1)))
    }
  }
}

// Usage
const result = await withRetry(() =>
  client.callTool('get_balance', {
    address: '0x742d35Cc6634C0532925a3b8D4C9db96C4b4d4d4'
  })
)

🎯 Best Practices

1. Connection Management

class HyperionClient {
  constructor(apiKey, profile) {
    this.apiKey = apiKey
    this.profile = profile
    this.client = null
  }

  async connect() {
    if (this.client) return this.client

    const url = new URL("https://server.smithery.ai/@cuongpo/hyperion-mcp-server/mcp")
    url.searchParams.set("api_key", this.apiKey)
    url.searchParams.set("profile", this.profile)

    const transport = new StreamableHTTPClientTransport(url.toString())
    this.client = new Client({
      name: "Hyperion App",
      version: "1.0.0"
    })

    await this.client.connect(transport)
    return this.client
  }

  async disconnect() {
    if (this.client) {
      await this.client.close()
      this.client = null
    }
  }
}

2. Environment Configuration

// config.js
export const config = {
  smithery: {
    apiKey: process.env.SMITHERY_API_KEY || "36e96d01-a9dd-4e4c-a705-bbe239a712ea",
    profile: process.env.SMITHERY_PROFILE || "notable-sparrow-IsrW6Y"
  },
  hyperion: {
    testnet: {
      rpcUrl: "https://hyperion-testnet.metisdevops.link",
      chainId: 133717,
      explorerUrl: "https://hyperion-testnet-explorer.metisdevops.link"
    }
  }
}

3. Type Safety (TypeScript)

interface WalletInfo {
  address: string
  mnemonic?: string
  name?: string
}

interface TransactionResult {
  hash: string
  status: 'pending' | 'confirmed' | 'failed'
  explorerUrl?: string
}

interface TokenInfo {
  name: string
  symbol: string
  decimals: number
  totalSupply: string
  address: string
}

class TypedHyperionClient {
  async createWallet(name?: string): Promise<WalletInfo> {
    const result = await this.client.callTool('create_wallet', { name })
    // Parse and return typed result
    return this.parseWalletResult(result)
  }

  async sendTransaction(
    to: string,
    amount: string,
    tokenAddress?: string
  ): Promise<TransactionResult> {
    const result = await this.client.callTool('send_transaction', {
      to,
      amount,
      tokenAddress
    })
    return this.parseTransactionResult(result)
  }
}

4. Gas Optimization

async function optimizeGas() {
  // Always estimate gas before sending transactions
  const gasEstimate = await client.callTool('estimate_gas', {
    to: '0x742d35Cc6634C0532925a3b8D4C9db96C4b4d4d4',
    value: '1.0'
  })

  // Add 20% buffer to gas estimate
  const gasLimit = Math.floor(parseInt(gasEstimate.gasUsed) * 1.2).toString()

  // Send transaction with optimized gas
  const result = await client.callTool('send_transaction', {
    to: '0x742d35Cc6634C0532925a3b8D4C9db96C4b4d4d4',
    amount: '1.0',
    gasLimit: gasLimit
  })
}

5. Batch Operations

async function batchOperations() {
  const addresses = [
    '0x742d35Cc6634C0532925a3b8D4C9db96C4b4d4d4',
    '0x123d35Cc6634C0532925a3b8D4C9db96C4b4d123',
    '0x456d35Cc6634C0532925a3b8D4C9db96C4b4d456'
  ]

  // Check multiple balances concurrently
  const balancePromises = addresses.map(address =>
    client.callTool('get_balance', { address })
  )

  const balances = await Promise.all(balancePromises)
  balances.forEach((balance, index) => {
    console.log(`Address ${addresses[index]}: ${balance.content[0].text}`)
  })
}

🔒 Security Considerations

1. API Key Management

// ❌ DON'T: Hardcode API keys
const apiKey = "36e96d01-a9dd-4e4c-a705-bbe239a712ea"

// ✅ DO: Use environment variables
const apiKey = process.env.SMITHERY_API_KEY

// ✅ DO: Use secure key management
import { getSecret } from './secure-config.js'
const apiKey = await getSecret('SMITHERY_API_KEY')

2. Input Validation

function validateAddress(address) {
  if (!address || typeof address !== 'string') {
    throw new Error('Address is required and must be a string')
  }
  if (!/^0x[a-fA-F0-9]{40}$/.test(address)) {
    throw new Error('Invalid Ethereum address format')
  }
  return address.toLowerCase()
}

function validateAmount(amount) {
  if (!amount || isNaN(parseFloat(amount))) {
    throw new Error('Amount must be a valid number')
  }
  if (parseFloat(amount) <= 0) {
    throw new Error('Amount must be greater than 0')
  }
  return amount
}

3. Rate Limiting

class RateLimiter {
  constructor(maxRequests = 10, windowMs = 60000) {
    this.maxRequests = maxRequests
    this.windowMs = windowMs
    this.requests = []
  }

  async checkLimit() {
    const now = Date.now()
    this.requests = this.requests.filter(time => now - time < this.windowMs)

    if (this.requests.length >= this.maxRequests) {
      const oldestRequest = Math.min(...this.requests)
      const waitTime = this.windowMs - (now - oldestRequest)
      await new Promise(resolve => setTimeout(resolve, waitTime))
    }

    this.requests.push(now)
  }
}

const rateLimiter = new RateLimiter()

async function rateLimitedCall(toolName, params) {
  await rateLimiter.checkLimit()
  return await client.callTool(toolName, params)
}

📚 Additional Resources

Network Information

• Hyperion Testnet RPC: https://hyperion-testnet.metisdevops.link

• Chain ID: 133717

• Currency: tMETIS (Test METIS)

• Explorer: https://hyperion-testnet-explorer.metisdevops.link

Useful Links

• Smithery Platform

• MCP SDK Documentation

• Hyperion MCP Server Repository

• Hyperion Testnet Faucet

Tool Summary

Category	Tools	Count
Wallet Management	create_wallet, import_wallet, list_wallets, set_current_wallet, get_current_wallet	5
Balance & Transactions	get_balance, send_transaction, get_transaction, estimate_gas	4
Blockchain Queries	get_block, get_network_info	2
Smart Contracts	call_contract, send_contract_transaction	2
ERC20 Tokens	deploy_erc20_token, get_token_info, mint_tokens	3
ERC721 NFTs	deploy_erc721_token	1
Total		18

Example Applications

1. DeFi Dashboard: Track balances, transactions, and token holdings

2. Token Launchpad: Deploy and manage ERC20 tokens

3. NFT Marketplace: Deploy ERC721 contracts and mint NFTs

4. Wallet Manager: Create and manage multiple wallets

5. Smart Contract Interface: Interact with deployed contracts

6. Transaction Monitor: Track and analyze blockchain transactions

7. Digital Art Platform: Create and manage NFT collections

🤝 Support

For issues, questions, or contributions:

• GitHub Issues: Report bugs or request features

• Documentation: Complete API reference

• Smithery Support: Platform documentation

---

Happy building with Hyperion MCP Server! 🚀