XDC AI MCP Infrastructure

XDC Network MCP Server

The XDC Network MCP Server is a comprehensive Model Context Protocol (MCP) server designed for smart contract interactions on the XDC Network. It provides wallet integration, contract deployment tools, security auditing capabilities, and seamless blockchain interactions through both local and remote deployments.

Key Features

  • 🔗 Wallet Integration: MetaMask and browser-based wallet connections

  • 📄 Smart Contract Tools: Deploy, interact, and audit contracts

  • 🛠️ Development Tools: Foundry integration with templates

  • 🌐 Network Support: XDC Network (Chain ID: 50) with RPC failover

  • 🔒 Security Features: Automated contract auditing and verification

  • 📱 Cross-Platform: Local stdio and remote HTTP/SSE transport support

Quick Start

# Clone and install
git clone https://github.com/your-org/xdc-mcp-server
cd xdc-mcp-server
npm install && npm run build

# Run the server
./build/index.js

Architecture

The MCP server supports two transport mechanisms:

  • Local (stdio): For development and local MCP clients

  • Remote (HTTP/SSE): For web-based clients and remote connections

Getting Started

Prerequisites

  • Node.js 18+ installed

  • MetaMask or compatible wallet

  • XDC Network configured in wallet (Chain ID: 50)

Installation

Local Development

# Clone the repository
git clone https://github.com/your-org/xdc-mcp-server
cd xdc-mcp-server

# Install dependencies
npm install

# Build the project
npm run build

# Run the server
./build/index.js

Remote Deployment

The server supports both Vercel and Railway deployments with HTTP/SSE transport for remote MCP client connections.

Vercel Deployment:

# Deploy to Vercel
vercel --prod

# Configure environment variables in Vercel dashboard

Railway Deployment:

# Install Railway CLI
npm install -g @railway/cli

# Login and deploy
railway login
railway init
railway up

API Reference

Network Tools

get_network_info

Get current XDC network information and statistics.

Parameters: None

Returns:

  • Network name and chain ID

  • Current block number

  • Gas price information

  • RPC endpoint status

Example:

{
  "network": "XDC Network",
  "chainId": 50,
  "currentBlock": 12345678,
  "gasPrice": "1.2 Gwei"
}

get_balance

Check XDC balance for any address.

Parameters:

  • address (string): XDC address to check (supports both xdc and 0x formats)

Returns:

  • Address balance in XDC

  • Formatted balance display

Example:

get_balance(address="xdc123...abc")
# Returns: "Balance: 10.5 XDC"

get_transaction_status

Get detailed transaction information and status.

Parameters:

  • txHash (string): Transaction hash

Returns:

  • Transaction status (success/failed/pending)

  • Block confirmation details

  • Gas usage and fees

  • From/to addresses

Wallet Tools

connect_wallet

Connect MetaMask or compatible wallet via browser relay.

Parameters:

  • force_new_session (boolean, optional): Force new connection

  • wait_for_connection (boolean, optional): Wait for connection completion

Returns:

  • Connection status

  • Wallet address

  • Browser link for connection

Usage:

connect_wallet()
# Opens browser link for MetaMask connection
# Displays QR code for mobile wallets

wallet_status

Check current wallet connection status and balance.

Parameters: None

Returns:

  • Connection status

  • Wallet address

  • XDC balance

  • Network information

disconnect_wallet

Disconnect current wallet session.

Parameters: None

Returns:

  • Disconnection confirmation

  • Session cleanup status

transfer_xdc

Transfer XDC tokens to another address.

Parameters:

  • to (string): Recipient address

  • amount (string): Amount in XDC

Returns:

  • Transaction hash

  • Transfer confirmation

  • Gas fees used

Example:

transfer_xdc(to="xdc456...def", amount="1.5")
# Transfers 1.5 XDC to recipient

sign_message

Sign a message for testing wallet connectivity.

Parameters:

  • message (string, optional): Custom message to sign

Returns:

  • Signed message

  • Signature hash

  • Signer address

Smart Contract Tools

get_contract_info

Get comprehensive information about any smart contract.

Parameters:

  • address (string): Contract address (xdc or 0x format)

Returns:

  • Contract balance and transaction count

  • Token information (if ERC20)

  • Source code verification status

  • ABI information

  • Function list

Example:

get_contract_info(address="xdc123...abc")
# Returns detailed contract analysis

interact_with_token

Interact with ERC20 tokens - check balances, transfer, approve.

Parameters:

  • tokenAddress (string): Token contract address

  • action (enum): "balance", "transfer", "approve", "allowance", "info"

  • targetAddress (string, optional): Target address for operations

  • amount (string, optional): Amount for transfers/approvals

  • spenderAddress (string, optional): Spender for allowance checks

Actions:

Token Info:

interact_with_token(tokenAddress="xdc123...abc", action="info")
# Returns: name, symbol, decimals, total supply

Check Balance:

interact_with_token(tokenAddress="xdc123...abc", action="balance", targetAddress="xdc456...def")
# Returns: token balance for address

Transfer Tokens:

interact_with_token(tokenAddress="xdc123...abc", action="transfer", targetAddress="xdc456...def", amount="100")
# Transfers 100 tokens to recipient

Development Tools

init_foundry_project

Initialize a new Foundry project with XDC Network configuration.

Parameters:

  • project_name (string, optional): Project name

  • force (boolean, optional): Force initialization in non-empty directory

Returns:

  • Setup commands to run

  • Foundry configuration

  • Environment setup instructions

write_smart_contract

Generate smart contract code from templates.

Parameters:

  • contractName (string): Name of the contract

  • template (enum): "erc20", "nft", "simple", "custom"

  • customCode (string, optional): Custom Solidity code

  • tokenName (string, optional): Token name for ERC20

  • tokenSymbol (string, optional): Token symbol for ERC20

  • initialSupply (string, optional): Initial supply for ERC20

Templates:

ERC20 Token:

write_smart_contract(
  contractName="MyToken",
  template="erc20",
  tokenName="My Token",
  tokenSymbol="MTK",
  initialSupply="1000000"
)

NFT Contract:

write_smart_contract(
  contractName="MyNFT",
  template="nft"
)

Simple Storage:

write_smart_contract(
  contractName="SimpleStorage",
  template="simple"
)

forge_build

Compile smart contracts using Foundry.

Parameters:

  • optimization (boolean, optional): Enable optimization

  • optimization_runs (number, optional): Optimization runs

Returns:

  • Build commands

  • Compilation status

  • Output directory information

forge_test

Run smart contract tests.

Parameters:

  • match_test (string, optional): Run specific test pattern

  • verbose (boolean, optional): Verbose output

Returns:

  • Test results

  • Coverage information

  • Pass/fail status

forge_deploy

Deploy smart contracts to XDC Network.

Parameters:

  • contractName (string): Contract to deploy

  • network (enum): "xdc_mainnet", "xdc_testnet", "localhost"

  • constructorArgs (array, optional): Constructor arguments

  • verify (boolean, optional): Verify on explorer

  • gasLimit (string, optional): Gas limit

Returns:

  • Deployed contract address

  • Transaction hash

  • Verification status

Configuration

Network Settings

The server is pre-configured for XDC Network with multiple RPC endpoints for reliability:

const XDC_NETWORK = {
  name: "XDC Network",
  chainId: 50,
  rpcUrl: "https://rpc.ankr.com/xdc",
  fallbackRpcs: [
    "https://erpc.xinfin.network",
    "https://xdc.blockpi.network/v1/rpc/public",
    "https://rpc1.xinfin.network"
  ],
  currency: "XDC",
  decimals: 18
};

Environment Variables

For deployment, configure these environment variables:

# Port for HTTP server
PORT=3000

# Private key for contract deployment (optional)
PRIVATE_KEY=your_private_key_here

# Custom RPC endpoints (optional)
XDC_MAINNET_RPC=https://rpc.ankr.com/xdc
XDC_TESTNET_RPC=https://erpc.apothem.network

Examples

Basic Workflow

1. Connect Wallet

connect_wallet()
# Follow browser link to connect MetaMask

2. Check Network Status

get_network_info()
# Verify XDC Network connection

3. Check Balance

wallet_status()
# View connected wallet balance

4. Transfer XDC

transfer_xdc(to="xdc456...def", amount="1.0")
# Send 1 XDC to recipient

Smart Contract Development

1. Initialize Project

init_foundry_project(project_name="MyDApp")
# Get setup commands for Foundry

2. Create Contract

write_smart_contract(
  contractName="MyToken",
  template="erc20",
  tokenName="My Token",
  tokenSymbol="MTK"
)

3. Build Contract

forge_build()
# Compile contracts

4. Deploy Contract

forge_deploy(
  contractName="MyToken",
  network="xdc_mainnet"
)

Token Interactions

1. Get Token Info

interact_with_token(
  tokenAddress="xdc123...abc",
  action="info"
)

2. Check Token Balance

interact_with_token(
  tokenAddress="xdc123...abc",
  action="balance"
)

3. Transfer Tokens

interact_with_token(
  tokenAddress="xdc123...abc",
  action="transfer",
  targetAddress="xdc456...def",
  amount="100"
)

Deployment Guide

Local Development

For local development with MCP clients like Cursor or Claude Desktop:

1. Build and run the server

npm run build
./build/index.js

2. Configure MCP client

Configure your MCP client to use stdio transport:

{
  "mcpServers": {
    "xdc-server": {
      "command": "/path/to/xdc-mcp-server/build/index.js"
    }
  }
}

Remote Deployment

For remote access from web clients:

Vercel Deployment

1. Configure vercel.json

{
  "functions": {
    "api/mcp/route.ts": {
      "maxDuration": 60
    }
  }
}

2. Deploy

vercel --prod

3. Configure MCP client

Configure your MCP client for HTTP transport:

{
  "mcpServers": {
    "xdc-server": {
      "url": "https://your-app.vercel.app/api/mcp"
    }
  }
}

Railway Deployment

1. Configure railway.json

{
  "build": {
    "builder": "NIXPACKS"
  },
  "deploy": {
    "startCommand": "npm start"
  }
}

2. Deploy

railway up

Security Features

Contract Auditing

The server includes automated security scanning capabilities:

  • Vulnerability Detection: Common smart contract vulnerabilities

  • Best Practice Analysis: Security pattern verification

  • Code Quality Checks: Solidity best practices

  • Dependency Analysis: Library security assessment

Transaction Security

  • Address Validation: Automatic address format verification

  • Transaction Verification: Pre-execution validation

  • Gas Estimation: Automatic gas limit calculation

  • Error Handling: Comprehensive error reporting

Wallet Security

  • Session Management: Secure wallet session handling

  • Private Key Protection: No private key storage

  • Browser Isolation: Wallet operations in browser context

  • Connection Validation: Wallet connectivity verification

Troubleshooting

Common Issues

Wallet Connection Failed

  • Cause: MetaMask not installed or wrong network

  • Solution: Install MetaMask and add XDC Network (Chain ID: 50)

  • RPC URL: https://rpc.ankr.com/xdc

Transaction Failed

  • Cause: Insufficient XDC balance for gas fees

  • Solution: Ensure wallet has XDC for transaction fees

  • Check: Use wallet_status to verify balance

Contract Interaction Failed

  • Cause: Invalid contract address or ABI

  • Solution: Verify contract address and ensure it's deployed

  • Check: Use get_contract_info to validate contract

RPC Connection Issues

  • Cause: Network connectivity or RPC endpoint down

  • Solution: Server automatically tries fallback RPCs

  • Check: Use get_network_info to verify connection

Error Codes

  • WALLET_NOT_CONNECTED: Use connect_wallet first

  • INSUFFICIENT_BALANCE: Add XDC to wallet for gas fees

  • INVALID_ADDRESS: Check address format (xdc or 0x)

  • CONTRACT_NOT_FOUND: Verify contract is deployed

  • NETWORK_ERROR: Check internet connection and RPC status

Support Resources

  • XDC Network Documentation: https://docs.xdc.org

  • XDC Explorer: https://xdc.blocksscan.io

  • MetaMask Setup: Add XDC Network manually

  • Foundry Documentation: https://book.getfoundry.sh

Advanced Usage

Custom Contract Templates

Create custom contract templates by extending the template system:

// Custom template example
contract {{contractName}} is Ownable {
    mapping(address => uint256) public balances;
    
    event Deposit(address indexed user, uint256 amount);
    
    function deposit() public payable {
        balances[msg.sender] += msg.value;
        emit Deposit(msg.sender, msg.value);
    }
}

Batch Operations

Perform multiple operations in sequence:

  1. Deploy multiple contracts

  2. Configure contract interactions

  3. Set up token approvals

  4. Execute batch transfers

Integration with External Tools

  • Hardhat Integration: Use alongside Hardhat for testing

  • Remix IDE: Deploy contracts created in Remix

  • OpenZeppelin: Leverage OpenZeppelin contracts

  • Chainlink: Integrate oracle functionality

Contributing

Development Setup

  1. Fork the repository

  2. Create feature branch: git checkout -b feature/new-tool

  3. Make changes and add tests

  4. Submit pull request with detailed description

Adding New Tools

  1. Define tool in appropriate service file

  2. Add parameter validation with Zod

  3. Implement error handling

  4. Add documentation and examples

  5. Write tests for the new functionality

Code Style

  • TypeScript: Strict type checking enabled

  • ESLint: Follow configured linting rules

  • Prettier: Consistent code formatting

  • JSDoc: Document all public functions

⚠️ Disclaimer: This software is provided as-is for educational and development purposes. Always verify transactions and contract interactions before execution. Use at your own risk in production environments.