@embarkai/mcp API

API reference for the MCP server package (@embarkai/mcp 0.2.4).

The @embarkai/mcp package exposes an MCP-compatible server that lets AI agents manage embarkAI smart wallets over the Model Context Protocol.


import { createMcpServer, startMcpServer, resolveConfig, ChainManager } from '@embarkai/mcp'
import type { McpConfig } from '@embarkai/mcp'

Server Functions

createMcpServer

Creates an MCP server instance without starting a transport. It builds a ChainManager (loading or creating the wallet keyshare) and registers all tools.


function createMcpServer(config: McpConfig): Promise<McpServer>

Use this when you need to attach a custom transport (e.g. SSE, WebSocket).

startMcpServer

Creates a server and immediately connects it to the stdio transport.


function startMcpServer(config?: McpConfig): Promise<void>

When config is omitted, resolveConfig() is called automatically to read values from environment variables.

resolveConfig

Builds an McpConfig from environment variables. Throws if EMBARK_API_KEY or EMBARK_WALLET_ID is missing, or if EMBARK_CHAIN_ID is not a number.


function resolveConfig(): McpConfig

McpConfig


interface McpConfig {
  apiKey: string
  walletId: string
  chainId: number
  keyshareDir: string
  keysharePassword?: string
  walletBackupPassword?: string
  debug: boolean
}

Field	Env Variable	Default	Description
`apiKey`	`EMBARK_API_KEY`	— (required)	Project API key from the Dashboard
`walletId`	`EMBARK_WALLET_ID`	— (required)	Identifier of the server wallet the agent controls
`chainId`	`EMBARK_CHAIN_ID`	`2030232745` (Lumia Beam)	Chain the server starts on; can be changed at runtime with `switch_chain`
`keyshareDir`	`EMBARK_KEYSHARE_DIR`	`./data/keyshares`	Directory for encrypted keyshare files
`keysharePassword`	`EMBARK_KEYSHARE_PASSWORD`	—	Enables the encrypted file storage (`FileKeyshareStorage`). Without it the keyshare lives in memory and is lost when the process exits
`walletBackupPassword`	`EMBARK_WALLET_BACKUP_PASSWORD`	—	Password for ShareVault backup and restore
`debug`	`EMBARK_DEBUG`	`false` (`"true"` enables)	Verbose logging in the underlying `ServerWalletManager`

ChainManager

Holds one ServerWalletManager per chain and the active chain the tools operate on. Exported for programmatic use; the server creates it for you.


class ChainManager {
  activeChainId: number
 
  static create(config: McpConfig): Promise<ChainManager>
 
  getManager(chainId?: number): ServerWalletManager
  getOrCreateWallet(walletId: string, chainId?: number): Promise<ServerWallet>
  getReadClient(chainId?: number): PublicReadClient
  getActiveChainConfig(): ChainConfig
  switchChain(chainId: number): { previousChainId: number; activeChain: ChainConfig }
  getAllChainConfigs(): ChainConfig[]
}

create() picks FileKeyshareStorage when keysharePassword is set and MemoryKeyshareStorage otherwise. Every method defaults chainId to activeChainId.

Built-in Tools

The MCP server registers seven tools that AI agents can invoke.

Tool	Description	Parameters
`get_wallet_info`	Returns `walletId`, `smartAccountAddress`, `ownerAddress` and the active chain (`id`, `name`, `nativeCurrency`, `blockExplorerUrl`)	none
`get_balance`	Native or ERC-20 balance for an address	`address?` (defaults to the wallet’s smart account), `tokenAddress?`
`transfer`	Sends native currency or ERC-20 tokens from the wallet	`to`, `amount` (human-readable, e.g. `"1.5"`), `tokenAddress?`
`read_contract`	Calls a read-only contract function	`address`, `abi` (array of ABI items), `functionName`, `args?`
`get_transaction_status`	Returns the receipt of a UserOperation	`userOpHash`
`list_supported_chains`	Lists all chains the server can operate on	none
`switch_chain`	Changes the active chain for subsequent operations	`chainId`

See Tools Reference for request and response examples.

Example: Using with Claude Desktop


{
  "mcpServers": {
    "embarkai": {
      "command": "npx",
      "args": ["-y", "@embarkai/mcp"],
      "env": {
        "EMBARK_API_KEY": "your-api-key",
        "EMBARK_WALLET_ID": "your-wallet-id",
        "EMBARK_CHAIN_ID": "2030232745",
        "EMBARK_KEYSHARE_DIR": "./keyshares",
        "EMBARK_KEYSHARE_PASSWORD": "a-strong-password"
      }
    }
  }
}

Example: Programmatic Usage


import { createMcpServer } from '@embarkai/mcp'
 
const server = await createMcpServer({
  apiKey: process.env.EMBARK_API_KEY!,
  walletId: process.env.EMBARK_WALLET_ID!,
  chainId: 2030232745,
  keyshareDir: './keyshares',
  keysharePassword: process.env.EMBARK_KEYSHARE_PASSWORD,
  debug: true,
})