Skip to main content
Model Context Protocol (MCP) is an open-source standard for connecting AI applications to external systems, tools, and data sources. MCP servers expose specific capabilities to AI applications through standardized protocol interfaces.

​
Search documentation

Documentation generates and exposes a remote MCP server as a search tool for AI applications to query. Access it at https://docs.ton.org/mcp. Use the contextual menu at the top of this page to copy the MCP server URL or follow a deep link to connect from Cursor or VS Code directly. For Claude Code, run the following command: 
claude mcp add --transport http TonDocs https://docs.ton.org/mcp
For OpenCode, use the following configuration:
opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "jira": {
      "type": "remote",
      "url": "https://docs.ton.org/mcp",
      "enabled": true
    }
  }
}

​
Perform blockchain operations with @ton/mcp

The @ton/mcp server enables agents to operate with TON wallets and perform many common blockchain operations. It manages dangerous parts like private keys and signing, allowing agents to handle intents and confirmation flows safely. The server is built on top of WalletKit. The latest alpha release is available on npm. Run it locally with the following command, passing CLI flags as needed. 
# Latest alpha version
npx @ton/mcp@alpha

​
Features

  • Balance queries: check Toncoin and jetton (token) balances, view transaction history
  • Transfers: send Toncoin, jettons, and NFTs to any TON address
  • Assets: list, inspect, and manage popular jettons or NFTs
  • Swaps: get quotes for token swaps via DEX aggregators
  • DNS: resolve TON DNS-compatible domains and perform reverse-lookup for addresses
  • Work with multiple stored wallets, active wallet selection, and local config-backed management tools
  • Agentic sub-wallet deployments: deploy additional agentic wallets from a root wallet
  • Multiple transports: standard I/O (default), multi-session HTTP server, and serverless

​
Quick start

The @ton/mcp supports two runtime modes. If neither MNEMONIC nor PRIVATE_KEY environment variables are set, the server starts in the registry mode, reading from a local config registry found at ~/.config/ton/config.json or at TON_CONFIG_PATH, if available. Otherwise, server starts with one in-memory wallet in the single-wallet mode. 
# Run as stdio MCP server in registry mode
# MNEMONIC and PRIVATE_KEY are both unset
npx @ton/mcp@alpha

# Run in registry mode with a custom config path
TON_CONFIG_PATH=/path/to/config.json npx @ton/mcp@alpha

# Run as stdio MCP server with mnemonic
MNEMONIC="word1 word2 ..." npx @ton/mcp@alpha

# Run as HTTP server (port 3000)
npx @ton/mcp@alpha --http

# Run as HTTP server on custom port
npx @ton/mcp@alpha --http 8080

# Run with custom agentic wallet contract
PRIVATE_KEY="0x.._YOUR_PRIVATE_KEY" \
WALLET_VERSION="agentic" \
AGENTIC_WALLET_ADDRESS="EQ.._WALLET_ADDRESS" \
npx @ton/mcp@alpha

​
Usage with MCP clients

For Claude or Cursor, add: 
{
  "mcpServers": {
    "ton": {
      "command": "npx",
      "args": ["-y", "@ton/mcp@alpha"],
      "env": {
        "TON_CONFIG_PATH": "/absolute/path/to/config.json"
      }
    }
  }
}
For HTTP mode, start the server and point the MCP client to the endpoint: 
npx @ton/mcp@alpha --http 3000
# MCP endpoint: http://localhost:3000/mcp
HTTP mode keeps a separate MCP session (transport) per client session ID, so multiple clients can initialize and reconnect independently.

​
Environment variables

VariableDefaultDescription
NETWORKmainnetTON network and default env override target for TONCENTER_API_KEY. Use mainnet for production and testnet for development and testing.
MNEMONICSpace-separated 24-word mnemonic phrase for single-wallet mode
PRIVATE_KEYHex-encoded private key: 32-byte seed or 64-byte (private + public key), alternative to mnemonic
WALLET_VERSIONv5r1Wallet version to use in single-wallet mode (v5r1, v4r2, or agentic)
AGENTIC_WALLET_ADDRESSAgentic wallet address (required for WALLET_VERSION=agentic, unless derived from init params)
AGENTIC_WALLET_NFT_INDEXAgentic wallet NFT index or subwallet ID (uint256, optional)
AGENTIC_COLLECTION_ADDRESSEQByQ19qvWxW7VibSbGEgZiYMqilHY5y1a_eeSL2VaXhfy07Agentic collection address override for single-wallet mode
TONCENTER_API_KEYAPI key for TON Center (optional, for higher rate limits)
TON_CONFIG_PATH~/.config/ton/config.jsonConfig path for registry mode
AGENTIC_CALLBACK_BASE_URLOptional public base URL for agentic onboarding callbacks
AGENTIC_CALLBACK_HOST127.0.0.1Host for the local callback server in stdio mode
AGENTIC_CALLBACK_PORTrandom free portPort for the local callback server in stdio mode