Setup & Installation

Install and configure the @embarkai/mcp server so your AI agent can interact with the blockchain.

Prerequisites

Node.js 18+
An embarkAI API key (get one at dashboard.embarkai.io )

Installation

Option 1: Run directly with npx (recommended)

No installation needed. Most MCP clients support running the server via npx:


npx -y @embarkai/mcp

Option 2: Install globally


npm install -g @embarkai/mcp

Then run:


embarkai-mcp

Option 3: Add as a project dependency


npm install @embarkai/mcp

Environment variables

The MCP server reads its configuration from environment variables.

Variable	Required	Default	Description
`EMBARK_API_KEY`	Yes	—	Your embarkAI API key for authenticating with the TSS service
`EMBARK_WALLET_ID`	Yes	—	The wallet identifier to operate on
`EMBARK_CHAIN_ID`	No	`2030232745`	Initial chain ID (defaults to Lumia Beam testnet)
`EMBARK_KEYSHARE_DIR`	No	`./data/keyshares`	Directory for persistent keyshare storage on disk
`EMBARK_KEYSHARE_PASSWORD`	Yes	—	Password to encrypt keyshares on disk
`EMBARK_WALLET_BACKUP_PASSWORD`	No	—	Password for restoring keyshares from the vault backup service
`EMBARK_DEBUG`	No	`false`	Set to `true` to enable verbose debug logging

Keyshare storage modes

File-based: Set EMBARK_KEYSHARE_PASSWORD to persist encrypted keyshares to the directory specified by EMBARK_KEYSHARE_DIR. Back up that directory together with the password.
Memory-only: If EMBARK_KEYSHARE_PASSWORD is not set, the keyshare lives only in memory and is lost when the server restarts. The wallet still exists on the embarkAI side, so it is not re-created: it keeps reporting its address and balance but can no longer sign, and any funds on it become inaccessible. Use this mode only for throwaway testing.

Quick start

Create a .env file:


EMBARK_API_KEY=your_api_key_here
EMBARK_WALLET_ID=your_wallet_id_here
EMBARK_CHAIN_ID=2030232745
EMBARK_KEYSHARE_PASSWORD=a_strong_password

Run the server:


npx -y @embarkai/mcp

The server starts on stdio transport — it reads JSON-RPC messages from stdin and writes responses to stdout. MCP clients (Claude Desktop, Cursor, etc.) handle this automatically.

Verifying the connection

After configuring your MCP client, ask the AI agent:

“What is my wallet address?”

If the server is configured correctly, the agent will call get_wallet_info and return your smart wallet address, owner address, and active chain.

You can also test with:

“What chains are supported?”

This calls list_supported_chains and requires no wallet operations, making it a reliable connectivity check.

Next steps

Claude Desktop — Configure the server in Claude Desktop
Cursor — Configure the server in Cursor IDE
Custom Agents — Use @embarkai/mcp programmatically
Tools Reference — Full documentation for all 7 tools