ValueRouter MCP Server

A Model Context Protocol (MCP) server that provides AI agents with comprehensive cross-chain USDC bridging capabilities through ValueRouter. This server enables AI agents to seamlessly bridge USDC across multiple blockchain networks including Ethereum, Solana, Sui, and Cosmos ecosystem chains.

Features

Multi-Chain Support: Bridge USDC across 15+ blockchain networks
Real-Time Quotes: Get accurate bridging quotes with fees and timing estimates
Transaction Simulation: Prepare bridge transactions without execution
Status Tracking: Monitor bridge transaction progress in real-time
Balance Queries: Check user token balances across all supported chains
Fee Estimation: Calculate bridge fees and gas costs

Supported Chains

Mainnet

Ethereum (Chain ID: 1)
Arbitrum One (Chain ID: 42161)
Optimism (Chain ID: 10)
Polygon (Chain ID: 137)
Avalanche C-Chain (Chain ID: 43114)
Base (Chain ID: 8453)
Solana (Chain ID: 'solana')
Sui (Chain ID: 'sui')
Noble (Chain ID: 'noble-1')
Osmosis (Chain ID: 'osmosis-1')
Evmos (Chain ID: 'evmos_9001-2')
Sei (Chain ID: 'pacific-1')
Coreum (Chain ID: 'coreum-mainnet-1')
dYdX (Chain ID: 'dydx-mainnet-1')

Testnet

Goerli (Chain ID: 5)
Sepolia (Chain ID: 11155111)
Solana Devnet (Chain ID: 'solana-devnet')
Sui Testnet (Chain ID: 'sui-testnet')
Noble Testnet (Chain ID: 'grand-1')
Avalanche Fuji (Chain ID: 43113)
Arbitrum Goerli (Chain ID: 421613)
Optimism Goerli (Chain ID: 420)
Polygon Mumbai (Chain ID: 80001)

Installation

npm install @valuerouter/mcp-server

Usage

Starting the Server

npx @valuerouter/mcp-server

Environment Variables

Create a .env file in your project root:

# RPC URLs (replace with your API keys)
ETHEREUM_RPC_URL=https://mainnet.infura.io/v3/YOUR_INFURA_KEY
ARBITRUM_RPC_URL=https://arb1.arbitrum.io/rpc
OPTIMISM_RPC_URL=https://mainnet.optimism.io
POLYGON_RPC_URL=https://polygon-rpc.com
AVALANCHE_RPC_URL=https://api.avax.network/ext/bc/C/rpc
BASE_RPC_URL=https://mainnet.base.org
SOLANA_RPC_URL=https://api.mainnet-beta.solana.com
SUI_RPC_URL=https://fullnode.mainnet.sui.io:443

# Optional: API keys for better performance
ALCHEMY_API_KEY=your_alchemy_key
INFURA_API_KEY=your_infura_key
QUICKNODE_API_KEY=your_quicknode_key

Available Tools

1. `get_supported_chains`

Get all supported chains for USDC bridging.

Parameters:

includeTestnets (boolean, optional): Include testnet chains (default: false)

Example:

{
  "name": "get_supported_chains",
  "arguments": {
    "includeTestnets": false
  }
}

Response:

{
  "chains": [
    {
      "chainId": 1,
      "name": "Ethereum",
      "symbol": "ETH",
      "decimals": 18,
      "explorerUrl": "https://etherscan.io",
      "isTestnet": false,
      "networkType": "mainnet",
      "usdcAddress": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"
    }
  ],
  "count": 14
}

2. `get_supported_tokens`

Get supported tokens for bridging.

Parameters:

chainId (number|string, optional): Specific chain ID to get tokens for
includeTestnets (boolean, optional): Include testnet tokens (default: false)

Example:

{
  "name": "get_supported_tokens",
  "arguments": {
    "chainId": 1,
    "includeTestnets": false
  }
}

3. `get_bridge_quote`

Get a quote for bridging USDC between chains.

Parameters:

fromChainId (number|string): Source chain ID
toChainId (number|string): Destination chain ID
fromToken (object): Source token details
toToken (object): Destination token details
amount (string): Amount to bridge in smallest unit (wei, lamports, etc.)
slippageBps (number, optional): Slippage tolerance in basis points (default: 100)
userAddress (string, optional): User address for better quote accuracy

Example:

{
  "name": "get_bridge_quote",
  "arguments": {
    "fromChainId": 1,
    "toChainId": 42161,
    "fromToken": {
      "address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
      "chainId": 1,
      "symbol": "USDC",
      "name": "USD Coin",
      "decimals": 6
    },
    "toToken": {
      "address": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
      "chainId": 42161,
      "symbol": "USDC",
      "name": "USD Coin",
      "decimals": 6
    },
    "amount": "1000000",
    "slippageBps": 100
  }
}

Response:

{
  "fromChainId": 1,
  "toChainId": 42161,
  "fromAmount": "1000000",
  "toAmount": "999500",
  "toAmountMin": "998501",
  "bridgeFee": "500",
  "gasFee": "10000000000000000",
  "totalFee": "10000000000000500",
  "estimatedTime": "480",
  "priceImpact": "0.01",
  "route": {
    "steps": [
      {
        "type": "bridge",
        "chainId": 1,
        "fromToken": {...},
        "toToken": {...},
        "amount": "1000000",
        "protocol": "ValueRouter"
      }
    ]
  },
  "validUntil": 1703958743123
}

4. `execute_bridge`

Execute a bridge transaction (simulation only).

Parameters:

fromChainId (number|string): Source chain ID
toChainId (number|string): Destination chain ID
fromToken (object): Source token details
toToken (object): Destination token details
amount (string): Amount to bridge
recipientAddress (string): Recipient address on destination chain
userAddress (string): User address initiating the transaction
slippageBps (number, optional): Slippage tolerance in basis points
memo (string, optional): Memo for Cosmos chains

Example:

{
  "name": "execute_bridge",
  "arguments": {
    "fromChainId": 1,
    "toChainId": 42161,
    "fromToken": {
      "address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
      "chainId": 1,
      "symbol": "USDC",
      "name": "USD Coin",
      "decimals": 6
    },
    "toToken": {
      "address": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
      "chainId": 42161,
      "symbol": "USDC",
      "name": "USD Coin",
      "decimals": 6
    },
    "amount": "1000000",
    "recipientAddress": "0x742d35Cc6634C0532925a3b8D45c07F9624f8b4c",
    "userAddress": "0x742d35Cc6634C0532925a3b8D45c07F9624f8b4c",
    "slippageBps": 100
  }
}

Response:

{
  "transactionHash": "simulated-1703958743123-abc123def",
  "fromChainId": 1,
  "toChainId": 42161,
  "status": "pending",
  "explorerUrl": "https://etherscan.io/tx/simulated-1703958743123-abc123def",
  "estimatedCompletionTime": "600",
  "trackingId": "simulated-1703958743123-abc123def",
  "warning": "This is a simulation only. To execute the transaction, use the returned transaction data with your wallet.",
  "simulationOnly": true
}

5. `get_transaction_status`

Get the status of a bridge transaction.

Parameters:

transactionHash (string): Transaction hash to check status for
fromChainId (number|string): Source chain ID
toChainId (number|string): Destination chain ID

Example:

{
  "name": "get_transaction_status",
  "arguments": {
    "transactionHash": "simulated-1703958743123-abc123def",
    "fromChainId": 1,
    "toChainId": 42161
  }
}

Response:

{
  "transactionHash": "simulated-1703958743123-abc123def",
  "fromChainId": 1,
  "toChainId": 42161,
  "status": "attesting",
  "steps": [
    {
      "name": "Simulation",
      "status": "completed",
      "timestamp": 1703958773123
    },
    {
      "name": "Bridge Scanning",
      "status": "completed",
      "timestamp": 1703958803123
    },
    {
      "name": "Circle Attestation",
      "status": "processing",
      "timestamp": 1703958863123
    }
  ],
  "fromTxHash": "simulated-1703958743123-abc123def"
}

6. `get_user_balance`

Get user token balance on a specific chain.

Parameters:

chainId (number|string): Chain ID to check balance on
tokenAddress (string): Token contract address
userAddress (string): User address to check balance for

Example:

{
  "name": "get_user_balance",
  "arguments": {
    "chainId": 1,
    "tokenAddress": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
    "userAddress": "0x742d35Cc6634C0532925a3b8D45c07F9624f8b4c"
  }
}

Response:

{
  "chainId": 1,
  "tokenAddress": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
  "balance": "1000000000",
  "decimals": 6,
  "symbol": "USDC",
  "formattedBalance": "1000.0"
}

7. `estimate_bridge_fees`

Estimate fees for a bridge transaction.

Parameters:

fromChainId (number|string): Source chain ID
toChainId (number|string): Destination chain ID
amount (string): Amount to bridge
tokenAddress (string, optional): Token address (defaults to USDC)

Example:

{
  "name": "estimate_bridge_fees",
  "arguments": {
    "fromChainId": 1,
    "toChainId": 42161,
    "amount": "1000000"
  }
}

Response:

{
  "bridgeFee": "500",
  "gasFee": "10000000000000000",
  "totalFee": "10000000000000500"
}

Error Handling

All tools return structured error responses when something goes wrong:

{
  "error": "Unsupported chain: 999",
  "code": "UNSUPPORTED_CHAIN",
  "details": "Chain ID 999 is not supported by ValueRouter"
}

Common error codes:

UNSUPPORTED_CHAIN: Chain is not supported
INVALID_TOKEN: Token address is invalid
INSUFFICIENT_BALANCE: User has insufficient balance
QUOTE_ERROR: Failed to get quote
BRIDGE_ERROR: Failed to prepare bridge transaction
STATUS_ERROR: Failed to get transaction status
BALANCE_ERROR: Failed to get balance

Chain-Specific Notes

Ethereum & EVM Chains

Use 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE for native ETH
Gas fees are in wei (18 decimals)
Bridge fees are 0.05% (5 basis points)

Solana

Use So11111111111111111111111111111111111111112 for native SOL
Gas fees are in lamports (9 decimals)
Requires WSOL wrapping for bridging

Sui

Use 0x2::sui::SUI for native SUI
Gas fees are in MIST (9 decimals)
Supports Move-based tokens

Cosmos Chains

Use denomination strings like uusdc, uosmo, etc.
Gas fees vary by chain
Supports IBC transfers

Integration Examples

Basic Bridge Flow

// 1. Get supported chains
const chains = await callTool('get_supported_chains', {})

// 2. Get user balance
const balance = await callTool('get_user_balance', {
  chainId: 1,
  tokenAddress: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
  userAddress: '0x742d35Cc6634C0532925a3b8D45c07F9624f8b4c'
})

// 3. Get bridge quote
const quote = await callTool('get_bridge_quote', {
  fromChainId: 1,
  toChainId: 42161,
  fromToken: {
    address: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
    chainId: 1,
    symbol: 'USDC',
    name: 'USD Coin',
    decimals: 6
  },
  toToken: {
    address: '0xaf88d065e77c8cC2239327C5EDb3A432268e5831',
    chainId: 42161,
    symbol: 'USDC',
    name: 'USD Coin',
    decimals: 6
  },
  amount: '1000000'
})

// 4. Execute bridge (simulation)
const bridge = await callTool('execute_bridge', {
  fromChainId: 1,
  toChainId: 42161,
  fromToken: quote.fromToken,
  toToken: quote.toToken,
  amount: '1000000',
  recipientAddress: '0x742d35Cc6634C0532925a3b8D45c07F9624f8b4c',
  userAddress: '0x742d35Cc6634C0532925a3b8D45c07F9624f8b4c'
})

// 5. Track transaction status
const status = await callTool('get_transaction_status', {
  transactionHash: bridge.transactionHash,
  fromChainId: 1,
  toChainId: 42161
})

Security Considerations

Simulation Only: The execute_bridge tool only simulates transactions and returns transaction data. It does not execute real transactions.
Address Validation: All addresses are validated before processing
Amount Validation: Amounts are validated to prevent overflow errors
RPC Security: Use secure RPC endpoints and API keys
Rate Limiting: Implement rate limiting for production use

Development

Building

npm run build

Testing

npm run test

Linting

npm run lint

Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests
Submit a pull request

License

MIT License - see LICENSE file for details

Support

For support and questions:

GitHub Issues: ValueRouter MCP Server Issues
Discord: ValueRouter Community
Documentation: ValueRouter Docs

Changelog

See CHANGELOG.md for release history.

ValueRouter MCP Server

README Documentation

ValueRouter MCP Server

Features

Supported Chains

Mainnet

Testnet

Installation

Usage

Starting the Server

Environment Variables

Available Tools

1. `get_supported_chains`

2. `get_supported_tokens`

3. `get_bridge_quote`

4. `execute_bridge`

5. `get_transaction_status`

6. `get_user_balance`

7. `estimate_bridge_fees`

Error Handling

Chain-Specific Notes

Ethereum & EVM Chains

Solana

Sui

Cosmos Chains

Integration Examples

Basic Bridge Flow

Security Considerations

Development

Building

Testing

Linting

Contributing

License

Support

Changelog

Quick Actions

Key Features

ValueRouter MCP Server

README Documentation

ValueRouter MCP Server

Features

Supported Chains

Mainnet

Testnet

Installation

Usage

Starting the Server

Environment Variables

Available Tools

1. get_supported_chains

2. get_supported_tokens

3. get_bridge_quote

4. execute_bridge

5. get_transaction_status

6. get_user_balance

7. estimate_bridge_fees

Error Handling

Chain-Specific Notes

Ethereum & EVM Chains

Solana

Sui

Cosmos Chains

Integration Examples

Basic Bridge Flow

Security Considerations

Development

Building

Testing

Linting

Contributing

License

Support

Changelog

Quick Actions

Key Features

1. `get_supported_chains`

2. `get_supported_tokens`

3. `get_bridge_quote`

4. `execute_bridge`

5. `get_transaction_status`

6. `get_user_balance`

7. `estimate_bridge_fees`