AgentKit: @ton/mcp

The @ton/mcp server enables AI agents to operate TON wallets and perform common blockchain operations through the Model Context Protocol (MCP) or CLI using agent skills. It handles private keys and signing internally, so agents interact only with high-level intents and confirmation flows. The server is built on top of WalletKit.

The latest alpha release is available on npm. Run it locally with:

npx -y @ton/mcp@alpha

To set it up, follow the quick start guide.

Features

• Balance queries: check Toncoin and jetton (token) balances, view transaction history
• Transfers: send Toncoin, jettons, and NFTs
• Assets: list, inspect, and manage popular jettons and NFTs
• Swaps: get quotes for token swaps through DEX aggregators
• DNS: resolve TON DNS domains and perform reverse lookups
• Agentic wallets: create, import, and manage self-custody agentic wallets
• Multiple transports: standard I/O (default), multi-session HTTP server, and serverless (AWS Lambda, Vercel, or custom integrations)

Quick start

There are two ways to set up @ton/mcp:

To start using @ton/mcp in agentic wallets mode:

Runtime modes

@ton/mcp supports two runtime modes:

• Agentic wallets mode (default) - operates with self-custody wallets for autonomous AI agents.
• Single-wallet mode (optional) - operates with a single in-memory wallet.

Agentic wallets mode

Agentic wallets are self-custody wallets designed for autonomous agents. The user retains the owner key, and the agent holds a separate operator key. This split-key design gives agents access to transfers, swaps, and other on-chain operations without exposing the root credentials.

Agentic wallets mode is the default. When neither MNEMONIC nor PRIVATE_KEY is set, the server loads wallets from a local config registry at ~/.config/ton/config.json or the path in TON_CONFIG_PATH.

In this mode the server provides additional tools for multi-wallet management, agentic wallet onboarding, operator key rotation, and wallet import. Wallet-scoped tools accept an optional selector parameter: wallet ID, name, or address. When omitted, the current active wallet is used.

# Start in agentic wallets mode (default)
npx @ton/mcp@alpha

# Start with a custom config path
TON_CONFIG_PATH=/path/to/config.json npx @ton/mcp@alpha

Single-wallet mode

Single-wallet mode starts the server with one in-memory wallet derived from a mnemonic or private key. This mode is useful for one-off tasks or for operating a single known wallet.

Set MNEMONIC or PRIVATE_KEY as an environment variable to activate this mode:

# First, securely set either a MNEMONIC="<WORD_1> <WORD_2> ... <WORD_24>"
# or a PRIVATE_KEY="<HEX_PRIVATE_KEY>"

# Then, launch the server
npx @ton/mcp@alpha

The default TON wallet version in the single-wallet mode is v5r1. Override it with WALLET_VERSION:

# First, securely set either a MNEMONIC or a PRIVATE_KEY
# Then, use a diffent wallet version
WALLET_VERSION=v4r2 npx @ton/mcp@alpha

Transport modes

The @ton/mcp server supports two transport modes:

• Standard I/O (stdio, default)
• HTTP, which can also be run serverless

Standard I/O

Standard IO is the default transport. The server reads MCP requests from stdin and writes responses to stdout. Most MCP clients, including Claude Desktop and Cursor, can use this transport. They spawn the server process and interact over standard streams.

npx @ton/mcp@alpha

HTTP

HTTP mode starts a multi-session HTTP server. Each MCP client session gets its own server transport, so multiple clients can initialize and reconnect independently.

# Start on the default port (3000)
npx @ton/mcp@alpha --http

# Start on a custom port
npx @ton/mcp@alpha --http 8080

# Start on a custom host and port
npx @ton/mcp@alpha --http 8080 --host 127.0.0.1

The MCP endpoint is available at http://<HOST>:<PORT>/mcp. Point the MCP client to this URL to connect.

Serverless

The package exports a @ton/mcp/serverless entry point for deployment as a serverless function on AWS Lambda, Vercel, Cloudflare Workers, and similar platforms. In serverless mode, credentials are passed via request headers rather than environment variables.

Serverless mode operates in single-wallet mode only and always uses the v5r1 TON wallet version. It does not use the wallet registry, nor does it expose wallet management or onboarding tools.

import { createServerlessHandler } from '@ton/mcp/serverless';
export const handler = createServerlessHandler();

import { createServerlessHandler } from '@ton/mcp/serverless';
export default createServerlessHandler();

import { createServerlessHandler } from '@ton/mcp/serverless';
const handle = createServerlessHandler();
const response = await handle({
  method: 'POST',
  url: '/mcp',
  headers: {
    'MNEMONIC': '<WORD_1> <WORD_2> ... <WORD_24>',
    'NETWORK': 'mainnet',
  },
  body: {},
});

Available tools

Common tools

• Wallet management:
  • get_wallet - returns the current wallet address and network: mainnet or testnet.
• Balances and history:
  • get_balance - returns the Toncoin balance of the current wallet.
  • get_balance_by_address - returns the Toncoin balance for any address.
  • get_jetton_balance - returns the balance of a specific jetton in the current wallet.
  • get_jettons - lists all jettons held by the current wallet with balances and metadata.
  • get_jettons_by_address - lists all jettons held by any address with balances and metadata. Supports pagination.
  • get_jetton_info - returns metadata for a jetton minter (master) contract: name, symbol, decimals, image, URI.
  • get_known_jettons - returns a built-in list of popular jettons on TON with addresses and metadata.
  • get_transactions - returns recent transaction history: Toncoin transfers, jetton transfers, swaps.
  • get_transaction_status - returns the status (pending, completed, or failed) and trace details for a transaction by its normalized hash.
• Transfers:
  • send_ton - sends Toncoin to an address. Amounts are in human-readable format. For example, "1.5" for 1.5 Toncoin. Returns a normalizedHash.
  • send_jetton - sends jettons to an address. Amounts are in human-readable format. Returns a normalizedHash.
  • send_nft - transfers an NFT to another address. Returns a normalizedHash.
  • send_raw_transaction - sends a raw transaction with full control over messages. Amounts are in nanoToncoin. Supports multiple messages. Returns a normalizedHash.
• Swaps:
  • get_swap_quote - returns a quote for a token swap. The response includes transaction parameters ready for send_raw_transaction. Use "TON" for native Toncoin or a jetton minter (master) contract address.
• NFTs:
  • get_nfts - lists NFTs in the current wallet with metadata, collection info, and attributes. Supports pagination.
  • get_nfts_by_address - lists NFTs held by any address. Supports pagination.
  • get_nft - returns detailed information about a specific NFT by its item contract address.
• DNS:
  • resolve_dns - resolves a TON DNS domain to a wallet address.
  • back_resolve_dns - reverse-resolves a wallet address to its associated DNS domain when one exists.

Agentic tools

• Wallet management:
  • list_wallets - lists all wallets in the local config registry.
  • get_current_wallet - returns the active wallet from the local config registry.
  • set_active_wallet - switches the active wallet in the local config registry by its ID, name, or address.
  • remove_wallet - soft-deletes a wallet from the local config registry. The wallet remains in the config file but is hidden from MCP lookups.
• Agentic wallet management:
  • agentic_validate_wallet - validates an agentic wallet address against the expected network and collection.
  • agentic_list_wallets_by_owner - lists agentic wallets owned by a given main wallet address.
  • agentic_import_wallet - imports existing agentic wallet into the local registry. If no matching pending draft exists, the wallet is read-only until agentic_rotate_operator_key completes.
  • agentic_rotate_operator_key - starts operator key rotation: generates a replacement key, persists a pending draft, and returns a dashboard URL for the on-chain change.
  • agentic_get_pending_operator_key_rotation - returns one pending operator key rotation by ID.
  • agentic_complete_rotate_operator_key - completes a key rotation after the on-chain transaction confirms and updates the stored operator key locally.
  • agentic_cancel_rotate_operator_key - cancels a pending key rotation and discards the replacement key.
• Agentic wallet onboarding:
  • agentic_start_root_wallet_setup - starts first-time root agent setup: generates operator keys, persists a pending draft, and returns a dashboard URL.
  • agentic_list_pending_root_wallet_setups - lists pending root agent onboarding drafts and their callback status.
  • agentic_get_root_wallet_setup - returns one pending onboarding draft by setup ID.
  • agentic_complete_root_wallet_setup - completes onboarding from a callback payload or a manually supplied wallet address, then imports the wallet and makes it active.
  • agentic_cancel_root_wallet_setup - cancels a pending onboarding draft and removes its state.

Environment variables

Common

Agentic wallets

Single-wallet

Library usage

The package also exports a programmatic API for building custom MCP servers:

import { createTonWalletMCP } from '@ton/mcp';
import {
  Signer,
  WalletV5R1Adapter,
  TonWalletKit,
  MemoryStorageAdapter,
  Network,
} from '@ton/walletkit';

// Mnemonic as a single string of 24 words:
// "<WORD_1> <WORD_2> ... <WORD_24>"
const MNEMONIC = process.env.MNEMONIC!;

// Initialize WalletKit
const network = Network.mainnet();
const kit = new TonWalletKit({
  networks: { [network.chainId]: {} },
  storage: new MemoryStorageAdapter(),
});
await kit.waitForReady();

// Create a wallet from a mnemonic
const signer = await Signer.fromMnemonic(MNEMONIC.split(' '), { type: 'ton' });
const walletAdapter = await WalletV5R1Adapter.create(signer, {
  client: kit.getApiClient(network),
  network,
});
const wallet = await kit.addWallet(walletAdapter);

// Create the MCP server object
const server = await createTonWalletMCP({ wallet });

Agentic wallets mode:

import { createTonWalletMCP } from '@ton/mcp';

// A key for higher RPS limits
const TONCENTER_API_KEY = process.env.TONCENTER_API_KEY!;

// Create the MCP server object
const server = await createTonWalletMCP({
  networks: {
    mainnet: { apiKey: TONCENTER_API_KEY },
  },
});

See also

• Agentic wallets
• @ton/mcp on GitHub