MCP Server Setup

This guide explains how to set up and configure the Somnia MCP server to interact with the Somnia blockchain.

Prerequisites

• Node.js 18+ or Bun runtime
• Access to Somnia network RPC endpoints
• Private key for transaction operations (optional, for transfers)
• VS Code, Cursor, or any editor that supports MCP

MCP Client Configuration

VS Code / Cursor Setup

1. Open your VS Code or Cursor settings
2. Search for “MCP” or navigate to the MCP settings section
3. Add the following configuration to your MCP servers:

{
  "mcpServers": {
    "somnia": {
      "command": "bunx",
      "args": ["-y", "@bunland/somnia-mpc"]
    }
  }
}

This configuration uses the published npm module, so no local installation is required.

Alternative Editors

For other editors that support MCP (like Claude Desktop), add the same configuration to their respective MCP configuration files.

Environment Configuration

For transaction operations, create a .env file in your project directory (where your MCP configuration is located) and add your configuration:

# Required for transaction operations
PRIVATE_KEY=your_private_key_here

# Optional: Custom RPC endpoints
SOMNIA_MAINNET_RPC=https://mainnet.somnia.network
SOMNIA_TESTNET_RPC=https://testnet.somnia.network

Configuration Details

The MCP server uses the following default configuration:

• Default Network: Somnia Testnet
• Supported Networks: All Somnia networks (Mainnet, Testnet, etc.)
• RPC Endpoints: Automatically configured for each network

Running the Server

The server will be automatically started by your MCP-compatible editor when configured.

Testing the Setup

Once configured, you can test the MCP server by:

1. Opening a new chat in your MCP-compatible editor
2. Asking the AI to interact with Somnia blockchain data
3. Using commands like “Check the balance of address 0x…” or “Get the latest block on Somnia”

Security Considerations

• Private Key: Never expose your private key in client-side code
• Network Selection: Use testnet for development and testing
• Gas Estimation: Always estimate gas before sending transactions
• Address Validation: Verify addresses before performing operations

Troubleshooting

Common Issues

• Network Connection Failed: Check RPC endpoints and network connectivity
• Invalid Address: Ensure addresses are properly formatted (0x prefix)
• Insufficient Funds: Check account balance before transfers
• Contract Not Found: Verify contract address and network

Error Messages

All tools return structured error messages with:

• Error type
• Descriptive message
• Context information (when available)

Next Steps

Once set up, you can:

• Query blockchain data
• Check balances and transaction history
• Interact with smart contracts
• Perform token transfers (with private key configured)

For detailed tool usage, see the MCP Tools Overview.