> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ton.org/llms.txt
> Use this file to discover all available pages before exploring further.

<AgentInstructions>

## Submitting Feedback

If you encounter incorrect, outdated, or confusing documentation on this page, submit feedback:

POST https://docs.ton.org/feedback

```json
{
  "path": "/ecosystem/ai/mcp",
  "feedback": "Description of the issue"
}
```

Only submit feedback when you have something specific and actionable to report.

</AgentInstructions>

# Agentic MCP server: @ton/mcp

export const Aside = ({type = "note", title = "", icon = "", iconType = "regular", children}) => {
  const asideVariants = ["note", "tip", "caution", "danger"];
  const asideComponents = {
    note: {
      outerStyle: "border-sky-500/20 bg-sky-50/50 dark:border-sky-500/30 dark:bg-sky-500/10",
      innerStyle: "text-sky-900 dark:text-sky-200",
      calloutType: "note",
      icon: <svg width="14" height="14" viewBox="0 0 14 14" fill="currentColor" xmlns="http://www.w3.org/2000/svg" className="w-4 h-4 text-sky-500" aria-label="Note">
          <path fill-rule="evenodd" clip-rule="evenodd" d="M7 1.3C10.14 1.3 12.7 3.86 12.7 7C12.7 10.14 10.14 12.7 7 12.7C5.48908 12.6974 4.0408 12.096 2.97241 11.0276C1.90403 9.9592 1.30264 8.51092 1.3 7C1.3 3.86 3.86 1.3 7 1.3ZM7 0C3.14 0 0 3.14 0 7C0 10.86 3.14 14 7 14C10.86 14 14 10.86 14 7C14 3.14 10.86 0 7 0ZM8 3H6V8H8V3ZM8 9H6V11H8V9Z"></path>
        </svg>
    },
    tip: {
      outerStyle: "border-emerald-500/20 bg-emerald-50/50 dark:border-emerald-500/30 dark:bg-emerald-500/10",
      innerStyle: "text-emerald-900 dark:text-emerald-200",
      calloutType: "tip",
      icon: <svg width="11" height="14" viewBox="0 0 11 14" fill="currentColor" xmlns="http://www.w3.org/2000/svg" className="text-emerald-600 dark:text-emerald-400/80 w-3.5 h-auto" aria-label="Tip">
          <path d="M3.12794 12.4232C3.12794 12.5954 3.1776 12.7634 3.27244 12.907L3.74114 13.6095C3.88471 13.8248 4.21067 14 4.46964 14H6.15606C6.41415 14 6.74017 13.825 6.88373 13.6095L7.3508 12.9073C7.43114 12.7859 7.49705 12.569 7.49705 12.4232L7.50055 11.3513H3.12521L3.12794 12.4232ZM5.31288 0C2.52414 0.00875889 0.5 2.26889 0.5 4.78826C0.5 6.00188 0.949566 7.10829 1.69119 7.95492C2.14321 8.47011 2.84901 9.54727 3.11919 10.4557C3.12005 10.4625 3.12175 10.4698 3.12261 10.4771H7.50342C7.50427 10.4698 7.50598 10.463 7.50684 10.4557C7.77688 9.54727 8.48281 8.47011 8.93484 7.95492C9.67728 7.13181 10.1258 6.02703 10.1258 4.78826C10.1258 2.15486 7.9709 0.000106649 5.31288 0ZM7.94902 7.11267C7.52078 7.60079 6.99082 8.37878 6.6077 9.18794H4.02051C3.63739 8.37878 3.10743 7.60079 2.67947 7.11294C2.11997 6.47551 1.8126 5.63599 1.8126 4.78826C1.8126 3.09829 3.12794 1.31944 5.28827 1.3126C7.2435 1.3126 8.81315 2.88226 8.81315 4.78826C8.81315 5.63599 8.50688 6.47551 7.94902 7.11267ZM4.87534 2.18767C3.66939 2.18767 2.68767 3.16939 2.68767 4.37534C2.68767 4.61719 2.88336 4.81288 3.12521 4.81288C3.36705 4.81288 3.56274 4.61599 3.56274 4.37534C3.56274 3.6515 4.1515 3.06274 4.87534 3.06274C5.11719 3.06274 5.31288 2.86727 5.31288 2.62548C5.31288 2.38369 5.11599 2.18767 4.87534 2.18767Z"></path>
        </svg>
    },
    caution: {
      outerStyle: "border-amber-500/20 bg-amber-50/50 dark:border-amber-500/30 dark:bg-amber-500/10",
      innerStyle: "text-amber-900 dark:text-amber-200",
      calloutType: "warning",
      icon: <svg className="flex-none w-5 h-5 text-amber-400 dark:text-amber-300/80" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2" aria-label="Warning">
          <path stroke-linecap="round" stroke-linejoin="round" d="M12 9v2m0 4h.01m-6.938 4h13.856c1.54 0 2.502-1.667 1.732-3L13.732 4c-.77-1.333-2.694-1.333-3.464 0L3.34 16c-.77 1.333.192 3 1.732 3z"></path>
        </svg>
    },
    danger: {
      outerStyle: "border-red-500/20 bg-red-50/50 dark:border-red-500/30 dark:bg-red-500/10",
      innerStyle: "text-red-900 dark:text-red-200",
      calloutType: "danger",
      icon: <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512" fill="currentColor" className="text-red-600 dark:text-red-400/80 w-4 h-4" aria-label="Danger">
          <path d="M17.1 292c-12.9-22.3-12.9-49.7 0-72L105.4 67.1c12.9-22.3 36.6-36 62.4-36l176.6 0c25.7 0 49.5 13.7 62.4 36L494.9 220c12.9 22.3 12.9 49.7 0 72L406.6 444.9c-12.9 22.3-36.6 36-62.4 36l-176.6 0c-25.7 0-49.5-13.7-62.4-36L17.1 292zm41.6-48c-4.3 7.4-4.3 16.6 0 24l88.3 152.9c4.3 7.4 12.2 12 20.8 12l176.6 0c8.6 0 16.5-4.6 20.8-12L453.4 268c4.3-7.4 4.3-16.6 0-24L365.1 91.1c-4.3-7.4-12.2-12-20.8-12l-176.6 0c-8.6 0-16.5 4.6-20.8 12L58.6 244zM256 128c13.3 0 24 10.7 24 24l0 112c0 13.3-10.7 24-24 24s-24-10.7-24-24l0-112c0-13.3 10.7-24 24-24zM224 352a32 32 0 1 1 64 0 32 32 0 1 1 -64 0z"></path>
        </svg>
    }
  };
  let variant = type;
  let gotInvalidVariant = false;
  if (!asideVariants.includes(type)) {
    gotInvalidVariant = true;
    variant = "danger";
  }
  const iconVariants = ["regular", "solid", "light", "thin", "sharp-solid", "duotone", "brands"];
  if (!iconVariants.includes(iconType)) {
    iconType = "regular";
  }
  return <>
      <div className={`callout my-4 px-5 py-4 overflow-hidden rounded-2xl flex gap-3 border ${asideComponents[variant].outerStyle}`} data-callout-type={asideComponents[variant].calloutType}>
        <div className="mt-0.5 w-4" data-component-part="callout-icon">
          {}
          {icon === "" ? asideComponents[variant].icon : <Icon icon={icon} iconType={iconType} size={14} />}
        </div>
        <div className={`text-sm prose min-w-0 w-full ${asideComponents[variant].innerStyle}`} data-component-part="callout-content">
          {gotInvalidVariant ? <p>
              <span className="font-bold">
                Invalid <code>type</code> passed!
              </span>
              <br />
              <span className="font-bold">Received: </span>
              {type}
              <br />
              <span className="font-bold">Expected one of: </span>
              {asideVariants.join(", ")}
            </p> : <>
              {title && <p className="font-bold">{title}</p>}
              {children}
            </>}
        </div>
      </div>
    </>;
};

The [`@ton/mcp` server][mcp-repo] enables AI agents to operate TON wallets and perform common blockchain operations through the [Model Context Protocol (MCP)][mcp-spec] or CLI using [agent skills][skills-spec]. 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](/ecosystem/walletkit/overview).

The latest alpha release is available on [npm][mcp-npm]. Run it locally with:

```bash theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
npx -y @ton/mcp@alpha
```

To set it up, follow the [quick start guide](#quick-start).

<Aside type="caution">
  `@ton/mcp` is currently in <Badge size="xs">alpha</Badge>. It is safe for use in mainnet, but APIs, behaviors, and [underlying wallet contracts][wallets] may change between releases. Pin a specific version for production use and check the [changelog][changelog] before upgrading.
</Aside>

## 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][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`:

<AccordionGroup>
  <Accordion title="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][skills-spec].

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

    ```bash theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
    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](#agentic-wallets-mode) by default.
  </Accordion>

  <Accordion title="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:

    ```json theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
    {
      "mcpServers": {
        "ton": {
          "command": "npx",
          "args": ["-y", "@ton/mcp@alpha"]
        }
      }
    }
    ```

    The server starts in [agentic wallets mode](#agentic-wallets-mode) by default. For [single-wallet mode](#single-wallet-mode), add `MNEMONIC` or `PRIVATE_KEY` to the `env` object.

    See [environment variables](#environment-variables) for the full list of configuration options.
  </Accordion>
</AccordionGroup>

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

<Steps>
  <Step title="Create" noAnchor="true">
    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](https://agents.ton.org/).
    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 can then sign transactions using its operator key.

    The user can revoke access or withdraw funds at any time from the dashboard.
  </Step>

  <Step title="Fund" noAnchor="true">
    An agentic wallet is a TON contract. 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 <kbd>Fund</kbd> 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?"
  </Step>

  <Step title="Use" noAnchor="true">
    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.
  </Step>

  <Step title="Observe and manage" noAnchor="true">
    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.
  </Step>
</Steps>

## Runtime modes

`@ton/mcp` supports two runtime modes:

* [Agentic wallets mode](#agentic-wallets-mode) (default) - operates with self-custody wallets for autonomous AI agents.
* [Single-wallet mode](#single-wallet) - operates with a single in-memory wallet.

### Agentic wallets mode

[Agentic wallets][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.

```bash theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
# 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:

```bash theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
# 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
```

<Aside type="danger" title="Funds at risk">
  `MNEMONIC` and `PRIVATE_KEY` grant full control of the wallet. Store these values in environment variables or a secrets manager. Do not commit them to Git or other source control systems. Do not pass them inline in shell commands.
</Aside>

The default TON wallet version in the single-wallet mode is [`v5r1`][wallets-comparison]. Override it with `WALLET_VERSION`:

```bash theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
# 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](#standard-i%2Fo) (stdio, default)
* [HTTP](#http), which can also be run [serverless](#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.

```bash theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
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.

```bash theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
# 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.

<Aside type="danger" title="Funds at risk">
  Serverless headers carry wallet credentials in every request. Use HTTPS in production to prevent credential interception. Restrict access to the serverless endpoint with authentication or network-level controls.
</Aside>

Serverless mode operates in [single-wallet mode](#single-wallet-mode) only and always uses the [`v5r1` TON wallet version][wallets-comparison]. 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.                                                                 |

<CodeGroup>
  ```typescript title="AWS Lambda" theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
  import { createServerlessHandler } from '@ton/mcp/serverless';
  export const handler = createServerlessHandler();
  ```

  ```typescript title="Vercel" theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
  import { createServerlessHandler } from '@ton/mcp/serverless';
  export default createServerlessHandler();
  ```

  ```typescript title="Custom integration" theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
  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: {},
  });
  ```
</CodeGroup>

## Available tools

### Common tools

<Aside type="caution" title="Confirm before sending">
  All transfer tools move real funds. The agent confirms every transfer with the user before executing. After sending, the default flow polls `get_transaction_status` until the transaction completes or fails.
</Aside>

* 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

<ParamField path="NETWORK" type="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`.
</ParamField>

<ParamField path="TONCENTER_API_KEY" type="string">
  API key for [TON Center](/ecosystem/api/toncenter/introduction). 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](/ecosystem/api/toncenter/get-api-key).
</ParamField>

<ParamField path="AGENTIC_CALLBACK_BASE_URL" type="string">
  Optional public base URL for agentic onboarding callbacks
</ParamField>

<ParamField path="AGENTIC_CALLBACK_HOST" type="string">
  Host for the local callback server in stdio mode. Defaults to `127.0.0.1`.
</ParamField>

<ParamField path="AGENTIC_CALLBACK_PORT" type="string">
  Port for the local callback server in stdio mode. Defaults to a random free port.
</ParamField>

### Agentic wallets

<ParamField path="TON_CONFIG_PATH" type="string" default="~/.config/ton/config.json">
  Config path for agentic wallets mode. Defaults to `~/.config/ton/config.json`.
</ParamField>

### Single-wallet

<ParamField path="MNEMONIC" type="string">
  Space-separated 24-word mnemonic phrase for the single-wallet mode.

  Alternative to `PRIVATE_KEY`.
</ParamField>

<ParamField path="PRIVATE_KEY" type="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.
</ParamField>

<ParamField path="WALLET_VERSION" type="string" default="v5r1">
  TON wallet version to use in the single-wallet mode: [`v5r1`, `v4r2`][wallets-comparison], or [`agentic`][wallets].

  Defaults to `v5r1`.
</ParamField>

<ParamField path="AGENTIC_WALLET_ADDRESS" type="string">
  Address of the agentic wallet in the single-wallet mode. Required for `WALLET_VERSION` set to `agentic`, unless derived from initial params.
</ParamField>

<ParamField path="AGENTIC_WALLET_NFT_INDEX" type="uint256">
  Optional index of the agentic wallet NFT contract.

  Defaults to none.
</ParamField>

<ParamField path="AGENTIC_COLLECTION_ADDRESS" type="string" default="EQByQ19qvWxW7VibSbGEgZiYMqilHY5y1a_eeSL2VaXhfy07">
  Agentic collection address override for single-wallet mode.

  Defaults to `EQByQ19qvWxW7VibSbGEgZiYMqilHY5y1a_eeSL2VaXhfy07` on the mainnet.
</ParamField>

## Library usage

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

```typescript theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
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:

```typescript theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
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][wallets]
* [`@ton/mcp` on GitHub][mcp-repo]

[mcp-repo]: https://github.com/ton-connect/kit/tree/main/packages/mcp

[mcp-npm]: https://www.npmjs.com/package/@ton/mcp?activeTab=versions

[mcp-spec]: https://modelcontextprotocol.io/

[skills-spec]: https://agentskills.io/specification

[wallets]: /ecosystem/ai/wallets

[wallets-comparison]: /standard/wallets/comparison#comparison-table

[changelog]: https://github.com/ton-connect/kit/blob/main/packages/mcp/CHANGELOG.md