Viper Messenger

Posts · March 18, 2026

TON + Codex = <3

What is @ton/mcp?

@ton/mcp is a Model Context Protocol server built on top of WalletKit. It gives AI agents access to your TON wallet without exposing raw private keys to the model — the server handles signing and confirmation flows.

What you can do with it:

Quick start

Go to ton-codex-mcp repo.

1. Run the MCP server

node scripts/ton-mcp-stdio.mjs --http 3001

Or using npx directly:

# With mnemonic
MNEMONIC="word1 word2 ..." npx @ton/mcp@alpha --http 3001

The server exposes an MCP endpoint at http://localhost:3001/mcp.

2. Add the MCP server to Codex CLI

codex mcp add --url http://localhost:3001/mcp ton-wallet

3. Run Codex

codex

That's it. Codex now has access to your TON wallet through the MCP protocol.

Example commands

Check your balance

show my wallet balance
Called ton-wallet.get_balance({})
  └ {"success": true, "address": "UQCSm2q2mFmTY8L73KFJAzk-AV-sqOsogh4YwSvpR8cRW6jt",
     "balance": "1.987803165 TON", "balanceNano": "1987803165"}

Swap tokens on DeDust

exchange on DeDust 0.1 TON to EQBlqsm144Dq6SjbPI4jjZvA1hqTIP3CvHovbIfW_t-SCALE (DUST) token
• I'll fetch a swap quote on DeDust for 0.1 TON first.

• Called
  └ ton-wallet.get_swap_quote({"amount":"0.1","fromToken":"TON",
    "toToken":"EQBlqsm144Dq6SjbPI4jjZvA1hqTIP3CvHovbIfW_t-SCALE"})

Other MCP clients

@ton/mcp works with any MCP-compatible client. For Claude or Cursor, add this to your config:

{
  "mcpServers": {
    "ton": {
      "command": "npx",
      "args": ["-y", "@ton/mcp@alpha"],
      "env": {
        "MNEMONIC": "word1 word2 ..."
      }
    }
  }
}

For Claude Code specifically:

claude mcp add --transport http TonDocs https://docs.ton.org/mcp

Resources

First published March 18, 2026 on the old Viper Foundation blog; moved here November 19, 2026. All posts