Agentic MCP server: @ton/mcp

The @ton/mcp server enables AI agents to operate TON wallets and perform common blockchain operations through the Model Context Protocol (MCP). 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, and serverless (AWS Lambda, Vercel, or custom integrations)

Quick start

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

Install skills (recommended)

Skills give an agent instructions on how to launch and use @ton/mcp on its own. No manual MCP client configuration is required. This approach works best with agents that support the skills specification.

Run the following command to install the skills for @ton/mcp:

npx skills add ton-connect/kit/packages/mcp

After installation, agents can launch and manage @ton/mcp on their own. No further configuration is needed. The server starts in agentic wallets mode by default.

Configure MCP client manually

Register @ton/mcp as a server in Claude Desktop, Cursor, Windsurf, or another MCP client. Use this approach when the agent does not support skills or when finer control over server configuration is needed.

Add the following block to the MCP client configuration file:

{
  "mcpServers": {
    "ton": {
      "command": "npx",
      "args": ["-y", "@ton/mcp@alpha"]
    }
  }
}

The server starts in agentic wallets mode by default. For single-wallet mode, add MNEMONIC or PRIVATE_KEY to the env object.

See environment variables for the full list of configuration options.

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

1. Create

   To create a first agentic wallet, ask the agent to “create an agentic wallet” and follow the instructions.

   The process goes as follows:

   1. The agent generates private keys for a new wallet and suggests opening the dashboard.
   2. On the dashboard, the user should connect their regular mainnet or testnet TON wallet: it will be the owner of an agentic wallet.
   3. Agentic wallet gets deployed from the dashboard.
   4. User provides the address of the deployed agentic wallet to the agent.
   5. Agent imports the wallet and becomes able to sign transactions using its operator key.

   The user can revoke access or withdraw funds at any time from the dashboard.

2. Fund

   An agentic wallet is a TON contract that needs Toncoin to operate. There are three ways to fund it:

   1. During creation: use the “Initial TON deposit” field on the deployment page.
   2. From the dashboard: use the Fund button to transfer Toncoin, jettons, or NFTs.
   3. Directly: use a wallet app like Tonkeeper to transfer assets to the agentic wallet address directly.

   To check the balance, ask the agent: “What is my agent balance?”

3. Use

   Once setup is complete, ask agent to perform desired actions. For example:

   • Send 1 TON to UQB.._WALLET_ADDRESS - sign and send a transfer from the agentic wallet.
   • Swap 5 TON for USDT - get a quote and execute a swap.
   • Resolve the contract address of this DNS domain: DOMAIN_NAME.ton - obtain the wallet address of the domain owner.
   • Show my NFTs - query all NFTs owned by the wallet.
   • Check my balance - current Toncoin and jetton balances. Do not use this data for any calculations, as it becomes outdated quickly.
   • Get my last transactions - list of several latest events initiated by the wallet.
   • Import agentic wallet - reinstate a wallet previously managed by another agent.
4. Observe and manage

   Web dashboard allows to see all agentic wallets in one place. Monitor transactions, fund and withdraw assets, grant and revoke accesses, rotate operator keys without redeploying the wallets.

Runtime modes

@ton/mcp supports two runtime modes:

• Agentic wallets mode (default) - operates with self-custody wallets for autonomous AI agents.
• Single-wallet mode - 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 three transport modes:

• Standard I/O (stdio, default)
• HTTP
• 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.

Header	Description
MNEMONIC	Space-separated 24-word mnemonic phrase.
PRIVATE_KEY	Hex-encoded 32-byte or 64-byte private key (paired with the public key). Takes priority over MNEMONIC.
NETWORK	Either mainnet (default) or testnet.
TONCENTER_KEY	Optional API key for higher rate limits.

AWS Lambda

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

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

NETWORK · string · default: "mainnet"

TON network and default env override target for TONCENTER_API_KEY. Use mainnet for production and testnet for development and testing.

Defaults to mainnet.

TONCENTER_API_KEY · string

API key for TON Center. Raises the default rate limit from 1 request per second to the limit of the selected plan. Without a key, the server uses a built-in shared key suitable for low-volume development and experiments.

For production workloads, obtain a dedicated key.

AGENTIC_CALLBACK_BASE_URL · string

Optional public base URL for agentic onboarding callbacks

AGENTIC_CALLBACK_HOST · string

Host for the local callback server in stdio mode. Defaults to 127.0.0.1.

AGENTIC_CALLBACK_PORT · string

Port for the local callback server in stdio mode. Defaults to a random free port.

Agentic wallets

TON_CONFIG_PATH · string · default: "~/.config/ton/config.json"

Config path for agentic wallets mode. Defaults to ~/.config/ton/config.json.

Single-wallet

MNEMONIC · string

Space-separated 24-word mnemonic phrase for the single-wallet mode.

Alternative to PRIVATE_KEY.

PRIVATE_KEY · string

Hex-encoded private key for the single-wallet mode. Can be given either 32-byte standalone or 64-byte when paired with the public key.

Alternative to MNEMONIC. Takes priority over it.

WALLET_VERSION · string · default: "v5r1"

TON wallet version to use in the single-wallet mode: v5r1, v4r2, or agentic.

Defaults to v5r1.

AGENTIC_WALLET_ADDRESS · string

Address of the agentic wallet in the single-wallet mode. Required for WALLET_VERSION set to agentic, unless derived from initial params.

AGENTIC_WALLET_NFT_INDEX · uint256

Optional index of the agentic wallet NFT contract.

Defaults to none.

AGENTIC_COLLECTION_ADDRESS · string

Agentic collection address override for single-wallet mode.

Defaults to EQByQ19qvWxW7VibSbGEgZiYMqilHY5y1a_eeSL2VaXhfy07 on the mainnet.

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