Tools Reference

Complete reference for all 7 MCP tools exposed by @embarkai/mcp. Each tool is available to any MCP-compatible client once the server is running.

Wallet

`get_wallet_info`

Get information about the configured server wallet, including addresses and active chain.

Example

// Response
{
"walletId": "user-123",
"smartAccountAddress": "0x1234...abcd",
"ownerAddress": "0xabcd...1234",
"chain": {
  "id": 2030232745,
  "name": "Lumia Beam",
  "nativeCurrency": { "name": "LUMIA", "symbol": "LUMIA", "decimals": 18 },
  "blockExplorerUrl": "https://beam-explorer.lumia.org"
}
}

Balances

`get_balance`

Get native token or ERC-20 token balance for an address. Defaults to the wallet's smart account address.

Parameters

Name	Type	Required	Description
`address`	`string`	No	Address to check balance for (defaults to wallet smart account)
`tokenAddress`	`string`	No	ERC-20 token contract address (omit for native balance)

Example

// Native balance response
{
"address": "0x1234...abcd",
"balance": "1500000000000000000",
"formatted": "1.5",
"symbol": "LUMIA",
"decimals": 18,
"chain": { "id": 2030232745, "name": "Lumia Beam" }
}

// ERC-20 balance — pass tokenAddress
{
"address": "0x1234...abcd",
"balance": "1000000",
"formatted": "1.0",
"symbol": "USDC",
"decimals": 6,
"chain": { "id": 2030232745, "name": "Lumia Beam" }
}

Transfers

`transfer`

Send native tokens or ERC-20 tokens from the wallet. Amount is in human-readable format (e.g. '1.5').

Parameters

Name	Type	Required	Description
`to`	`string`	Yes	Recipient address
`amount`	`string`	Yes	Amount to send in human-readable format (e.g. "1.5")
`tokenAddress`	`string`	No	ERC-20 token contract address (omit for native transfer)

Example

// Response
{
"userOpHash": "0xabc123...",
"transactionHash": "0xdef456...",
"blockNumber": 12345678,
"success": true,
"gasUsed": "84000",
"chain": { "id": 2030232745, "name": "Lumia Beam" }
}

Smart Contract Reading

`read_contract`

Call a view/pure function on a smart contract. Provide the ABI array, function name, and optional arguments.

Parameters

Name	Type	Required	Description
`address`	`string`	Yes	Contract address
`abi`	`ABI[]`	Yes	Contract ABI (array of ABI items)
`functionName`	`string`	Yes	Function name to call
`args`	`any[]`	No	Function arguments

Example

// Example: read ERC-20 totalSupply
// Parameters:
//   address: "0xTokenAddress..."
//   abi: [{"type":"function","name":"totalSupply","inputs":[],"outputs":[{"type":"uint256"}],"stateMutability":"view"}]
//   functionName: "totalSupply"

// Response
{
"result": "1000000000000000000000000",
"chain": { "id": 2030232745, "name": "Lumia Beam" }
}

Transaction Status

`get_transaction_status`

Check the status of a previously submitted user operation by its hash.

Parameters

Name	Type	Required	Description
`userOpHash`	`string`	Yes	User operation hash to check

Example

// Confirmed transaction
{
"status": "confirmed",
"transactionHash": "0xdef456...",
"blockNumber": 12345678,
"success": true,
"gasUsed": "84000"
}

// Pending transaction
{
"status": "pending",
"userOpHash": "0xabc123..."
}

Chain Management

`list_supported_chains`

List all blockchain networks supported by EmbarkAI, showing which one is currently active.

Example

// Response
{
"chains": [
  {
    "id": 994873017,
    "name": "Lumia Prisma",
    "nativeCurrency": { "name": "LUMIA", "symbol": "LUMIA", "decimals": 18 },
    "blockExplorerUrl": "https://explorer.lumia.org",
    "isActive": false
  },
  {
    "id": 2030232745,
    "name": "Lumia Beam",
    "nativeCurrency": { "name": "LUMIA", "symbol": "LUMIA", "decimals": 18 },
    "blockExplorerUrl": "https://beam-explorer.lumia.org",
    "isActive": true
  },
  {
    "id": 11155111,
    "name": "Sepolia",
    "nativeCurrency": { "name": "Ether", "symbol": "ETH", "decimals": 18 },
    "blockExplorerUrl": "https://sepolia.etherscan.io",
    "isActive": false
  }
],
"activeChainId": 2030232745
}

`switch_chain`

Switch the active blockchain network. All subsequent operations will use this chain.

Parameters

Name	Type	Required	Description
`chainId`	`number`	Yes	Target chain ID to switch to

Example

// Response
{
"previousChainId": 2030232745,
"activeChain": {
  "id": 994873017,
  "name": "Lumia Prisma",
  "nativeCurrency": { "name": "LUMIA", "symbol": "LUMIA", "decimals": 18 },
  "blockExplorerUrl": "https://explorer.lumia.org"
}
}

Error handling

All tools return errors in a consistent format with isError: true:


{
  "error": "Chain 999 is not supported"
}

Common errors:

Missing API key — EMBARK_API_KEY environment variable is not set
Invalid chain ID — The requested chain is not supported
Insufficient balance — Not enough tokens for the transfer
Invalid address — The provided address is not a valid Ethereum address