diff --git a/content/onboarding/ai/mcp.mdx b/content/onboarding/ai/mcp.mdx index 66f4babb6..929ff5f00 100644 --- a/content/onboarding/ai/mcp.mdx +++ b/content/onboarding/ai/mcp.mdx @@ -11,7 +11,9 @@ The latest alpha release is available on [npm][mcp-npm]. Run it locally with: npx -y @ton/mcp@alpha ``` -To set it up, follow the [quick start guide](#quick-start). +To set it up, see [Installation](#installation). + +To get started with using skills, see the [quick start guide](/onboarding/ai/quick-start). `@ton/mcp` is currently in alpha. 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. @@ -31,100 +33,44 @@ To set it up, follow the [quick start guide](#quick-start). - 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 +## Installation There are two ways to set up `@ton/mcp`: - - - 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 - 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. - - - - 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 - { - "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. +### Install skills (recommended) - See [environment variables](#environment-variables) for the full list of configuration options. - - +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]. -To start using `@ton/mcp` in agentic wallets mode: +To install the skills for `@ton/mcp`, run the following command: - - - ### 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](https://agents.ton.org/). - 1. On the dashboard, the user should connect their regular mainnet or testnet TON wallet: it will be the owner of an agentic wallet. - 1. Agentic wallet gets deployed from the dashboard. - 1. User provides the address of the deployed agentic wallet to the agent. - 1. 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. - - - - ### Fund +```bash +npx skills add ton-connect/kit/packages/mcp +``` - An agentic wallet is a TON contract. There are three ways to fund it: +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. - 1. During creation: use the "Initial Gram deposit" field on the deployment page. - 1. From the dashboard: use the Fund button to transfer Gram, jettons, or NFTs. - 1. Directly: use a wallet app to transfer assets to the agentic wallet address directly. +To quickly get started with agentic wallets, see [Quick start](/onboarding/ai/quick-start). - To check the balance, ask the agent: "What is my agent balance?" - +### Configure the client manually - - ### Use +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. - Once setup is complete, ask agent to perform desired actions. For example: +Add the following block to the MCP client configuration file: - - `Send 1 GRAM to UQB.._WALLET_ADDRESS` - sign and send a transfer from the agentic wallet. - - `Swap 5 GRAM 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 Gram 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. - +```json +{ + "mcpServers": { + "ton": { + "command": "npx", + "args": ["-y", "@ton/mcp@alpha"] + } + } +} +``` - - ### Observe and manage +By default, the server starts in [agentic wallets mode](#agentic-wallets-mode). For the [single-wallet mode](#single-wallet-mode), add `MNEMONIC` or `PRIVATE_KEY` to the `env` object. - 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. - - +See [environment variables](#environment-variables) for the full list of configuration options. ## Runtime modes @@ -137,7 +83,7 @@ To start using `@ton/mcp` in 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`. +The 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. @@ -151,7 +97,7 @@ 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. +The 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: diff --git a/content/onboarding/ai/meta.json b/content/onboarding/ai/meta.json index c8302f350..4bbef976c 100644 --- a/content/onboarding/ai/meta.json +++ b/content/onboarding/ai/meta.json @@ -4,6 +4,7 @@ "defaultOpen": true, "pages": [ "overview", + "quick-start", "mcp", "wallets" ] diff --git a/content/onboarding/ai/quick-start.mdx b/content/onboarding/ai/quick-start.mdx new file mode 100644 index 000000000..fedb21eed --- /dev/null +++ b/content/onboarding/ai/quick-start.mdx @@ -0,0 +1,109 @@ +--- +title: "Quick start: Create an agentic wallet" +sidebarTitle: "Quick start" +--- + +The easiest way to get started with AI on TON is creating an [agentic wallet](/onboarding/ai/wallets). + +This guide explains how to do the following: + +- Install skills for TON MCP server ([@ton/mcp](/onboarding/ai/mcp)) +- Prompt an AI agent to create an agentic wallet on TON +- Manage agentic wallets + + + * Agentic wallets are self-custody wallets designed for autonomous AI agents on TON. They are implemented as [smart contracts](/foundations/glossary#smart-contract). + * TON MCP server is a middleware acting as a bridge between an AI model and TON Blockchain. + * Skills are instructions on how to launch and use TON MCP independently: no manual configuration is required. This approach works best with agents that support the [skills specification][skills-spec]. + + +## Prerequisites + +Before starting, meet the following prerequisites: + +- Install an autonomous AI agent such as Claude Code or Codex. +- Create a wallet on TON — for example, using [wallet.ton.org](/onboarding/wallet-apps/web). +- Fund the wallet with Gram. The recommended network is **mainnet**. + +Your regular wallet on TON will be the owner of the agentic wallet. + +## 1. Install skills + +To install skills for `@ton/mcp`, run the following command: + +```bash +npx skills add ton-connect/kit/packages/mcp +``` + +There are two options available: + +- Run the command anywhere and select the **Global** scope during installation. +- Run it in the agent's folder and select **Project**. + + + Alternatively, you can [configure the MCP client manually](/onboarding/ai/mcp#configure-the-client-manually). Use this approach when the agent does not support skills or when finer control over server configuration is needed. + + +## 2. Create an agentic wallet + +To create a first agentic wallet, follow this flow: + +1. Ask the agent to `create an agentic wallet`. +1. The agent will generate private keys and suggest opening the [web dashboard](https://agents.ton.org/). +1. On the dashboard, connect your regular TON wallet by clicking Connect. +1. In the **Initial Gram deposit** field, set the amount of Gram to deposit from the main wallet. +1. Deploy the agentic wallet by clicking Deploy + First Fund. +1. Once the deployment is complete, copy the wallet's address from the dashboard. +1. Provide the address to your AI agent and ask to `import the wallet`. + +After importing the wallet, the agent will be able to sign transactions using its operator key. + +Note that you can create multiple agentic wallets and [manage them](#5-manage-wallets) from the dashboard. + +## 3. Fund the wallet + +There are three ways to fund an agentic wallet: + +- During creation: use the **Initial Gram deposit** field on the deployment page. +- From the [web dashboard](https://agents.ton.org/): click Fund to transfer Gram, jettons, or NFTs. +- Directly: use a wallet app like [wallet.ton.org](/onboarding/wallet-apps/web) to transfer assets to the agentic wallet address. + +To check the balance, ask the agent: `What is my agent balance?` + +## 4. Use the wallet with AI + +Once setup is complete, you can ask the AI agent to manage assets and wallets: + +- Get wallet balances +- Send Gram and jettons +- Swap assets, manage NFTs, buy/sell Backed's xStocks +- Create and import more agentic wallets +- List wallets and switch between them +- Rotate operator keys + +For example, use prompts like this: + +- `Send 1 Gram to UQB.._WALLET_ADDRESS` — Sign and send a transfer from the agentic wallet. +- `Swap 5 Gram 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` — Get current Gram 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. + +## 5. Manage wallets + +You can see all agentic wallets and manage them from the [web dashboard](https://agents.ton.org/): + +- Monitor transactions +- Fund and withdraw funds +- Grant and revoke access +- Rotate operator keys without redeploying the wallets + +## Next steps + +Learn more about TON MCP server and ways to use it: [@ton/mcp](/onboarding/ai/mcp). + +Learn more about agentic wallets: [Agentic wallets](/onboarding/ai/wallets). + +[skills-spec]: https://agentskills.io/specification diff --git a/content/onboarding/ai/wallets.mdx b/content/onboarding/ai/wallets.mdx index c382e5cb6..8c9f2a664 100644 --- a/content/onboarding/ai/wallets.mdx +++ b/content/onboarding/ai/wallets.mdx @@ -49,7 +49,9 @@ Connect an existing TON wallet to access the dashboard. ## Get started -The recommended way to create and use agentic wallets is through [`@ton/mcp`](/onboarding/ai/mcp). The [`@ton/mcp` quick start](/onboarding/ai/mcp#quick-start) guide covers the full setup flow and gives common usage examples. +The recommended way to create and use agentic wallets is through [`@ton/mcp`](/onboarding/ai/mcp). + +The [Quick start](/onboarding/ai/quick-start) guide covers the full setup flow and gives common usage examples. ## FAQ