Adjusted docs for new wallet mode on MCP

Author: codebycarson

.yarn/install-state.gz

@@ -21,16 +21,38 @@ icon: "robot"
 
 ## Quick Start
 
-Add the Sei MCP Server to your AI assistant with this configuration:
+<Note>
+**Secure by Default**: The MCP server runs in **read-only mode** by default. Wallet tools are disabled until you explicitly configure a private key.
+</Note>
+
+### Basic Setup (Read-Only)
+
+Start with read-only blockchain data access:
+
+```json
+{
+  "mcpServers": {
+    "sei": {
+      "command": "npx",
+      "args": ["-y", "@sei-js/mcp-server"]
+    }
+  }
+}
+```
+
+### Full Setup (With Wallet)
+
+To enable transactions and wallet tools, add the wallet mode flag and private key:
 
 ```json
 {
   "mcpServers": {
     "sei": {
       "command": "npx",
-      "args": ["@sei-js/mcp-server"],
+      "args": ["-y", "@sei-js/mcp-server"],
       "env": {
-        "PRIVATE_KEY": "your_private_key_here"
+        "WALLET_MODE": "private-key",
+        "PRIVATE_KEY": "0x123..."
       }
     }
   }
@@ -46,7 +68,8 @@ Add the Sei MCP Server to your AI assistant with this configuration:
 The Model Context Protocol is an open standard that connects AI systems with custom prompts, tools and data sources (context). It enables:
 
 - **Real-time blockchain data access** - Get current balances, transaction history, and network status directly from Sei
-- **Full execution and write operations** - Deploy contracts, execute transactions, and interact with smart contracts
+- **Secure by default** - Runs in read-only mode until you explicitly enable wallet tools
+- **Full execution and write operations** - Deploy contracts, execute transactions, and interact with smart contracts (with wallet configured)
 - **Up-to-date documentation access** - Search and understand the latest Sei documentation and guides
 - **Specialized blockchain capabilities** - Access Sei-specific features like precompiles and native token operations
 

docs/mcp-server/introduction.mdx

@@ -20,14 +20,15 @@ icon: "download"
         Click "Add new Global MCP server" and add this configuration to mcp.json:
 
         <CodeGroup>
-        ```json mcp.json
+        ```json
         {
           "mcpServers": {
-            "sei-mcp-server": {
+            "sei": {
               "command": "npx",
               "args": ["-y", "@sei-js/mcp-server"],
               "env": {
-                "PRIVATE_KEY": "your_private_key_here"
+                "WALLET_MODE": "private-key",
+                "PRIVATE_KEY": "0x123..."
               }
             }
           }
@@ -58,14 +59,15 @@ icon: "download"
         Add the Sei MCP Server to your configuration:
 
         <CodeGroup>
-        ```json Configuration
+        ```json
         {
           "mcpServers": {
             "sei": {
               "command": "npx",
               "args": ["-y", "@sei-js/mcp-server"],
               "env": {
-                "PRIVATE_KEY": "your_private_key_here"
+                "WALLET_MODE": "private-key",
+                "PRIVATE_KEY": "0x123..."
               }
             }
           }
@@ -92,14 +94,15 @@ icon: "download"
         Open Settings → Developer → Edit Config and add:
 
         <CodeGroup>
-        ```json Claude Config
+        ```json
         {
           "mcpServers": {
             "sei": {
               "command": "npx",
               "args": ["-y", "@sei-js/mcp-server"],
               "env": {
-                "PRIVATE_KEY": "your_private_key_here"
+                "WALLET_MODE": "private-key",
+                "PRIVATE_KEY": "0x123..."
               }
             }
           }
@@ -126,7 +129,11 @@ icon: "download"
 
       <Step title="Add Server">
         ```bash
+        # Read-only mode (default)
         claude mcp add sei-mcp-server npx @sei-js/mcp-server
+        
+        # Wallet-enabled mode
+        claude mcp add sei-mcp-server-wallet npx @sei-js/mcp-server --env WALLET_MODE=private-key PRIVATE_KEY=0x123...
         ```
       </Step>
 
@@ -142,24 +149,82 @@ icon: "download"
   </Tab>
 </Tabs>
 
-## Private Key Setup
+## Wallet Connection
+
+<Note>
+**Wallet Tools Disabled by Default**
+
+For security, the MCP server runs in **read-only mode** by default. Only blockchain data tools are available without wallet configuration.
+</Note>
+
+### Default Behavior (Read-Only)
+
+Without wallet configuration, you can:
+- ✅ Check balances and account data
+- ✅ Read smart contract data
+- ✅ Get network and block information
+- ✅ Search documentation
+- ❌ Send transactions or transfer tokens
+- ❌ Deploy or write to contracts
+- ❌ Approve token spending
+
+### Enabling Wallet Tools
+
+To unlock transaction capabilities, add your private key to the configuration:
 
 <Warning>
 Use a dedicated test wallet with minimal funds. Never use your main wallet's private key.
 </Warning>
 
-Export your private key from your wallet:
-
 <Steps>
-  <Step title="Access Wallet Settings">
-    Look for "Export Private Key" or "Show Private Key" in wallet settings
+  <Step title="Get Private Key">
+    Export your private key from your wallet:
+    - Look for "Export Private Key" or "Show Private Key" in wallet settings
+    - Ensure the key starts with `0x`
+    - Fund the wallet with small amounts for testing
   </Step>
 
-  <Step title="Verify Format">
-    Ensure the key starts with `0x`
+  <Step title="Add to Configuration">
+    Add the `PRIVATE_KEY` environment variable to your MCP configuration:
+    
+    ```json
+    {
+      "mcpServers": {
+        "sei": {
+          "command": "npx",
+          "args": ["-y", "@sei-js/mcp-server"],
+          "env": {
+            "WALLET_MODE": "private-key",
+            "PRIVATE_KEY": "0x123...."
+          }
+        }
+      }
+    }
+    ```
   </Step>
 
-  <Step title="Fund Wallet">
-    Fund the wallet with small amounts for testing
+  <Step title="Restart & Verify">
+    Restart your AI assistant and verify wallet tools are available:
+    
+    **Ask your AI:** "What's my wallet address?"
+    
+    If configured correctly, you'll get your wallet address. If not, you'll see an error message.
   </Step>
-</Steps>
+</Steps>
+
+### Security Best Practices
+
+<CardGroup cols={2}>
+  <Card title="Test Wallet Only" icon="shield-check">
+    Use a dedicated wallet for testing, not your main holdings
+  </Card>
+  <Card title="Minimal Funds" icon="coins">
+    Keep only small amounts needed for testing transactions
+  </Card>
+  <Card title="Secure Storage" icon="lock">
+    Never commit private keys to version control
+  </Card>
+  <Card title="Regular Rotation" icon="arrows-rotate">
+    Rotate test wallet keys periodically
+  </Card>
+</CardGroup>

docs/mcp-server/setup.mdx

@@ -4,18 +4,35 @@ description: "Complete reference of 28 MCP tools for blockchain operations"
 icon: "wrench"
 ---
 
-The Sei MCP Server provides 28 tools for blockchain operations. Ask your AI assistant using natural language or the exact tool names below.
+The Sei MCP Server provides 28 tools for blockchain operations. **By default, wallet tools are disabled** and only read-only tools are available. [Enable wallet tools](/mcp-server/setup#wallet-connection) to unlock transaction capabilities.
 
-## Core Operations
+<Note>
+**Wallet Tools Disabled by Default**
+
+For security, wallet-dependent tools require explicit configuration. Only read-only blockchain data tools are available by default.
+</Note>
+
+## Read-Only Tools (Always Available)
+
+These tools work without wallet connection and are available by default:
 
 | Tool | Purpose | Example Usage |
 |------|---------|---------------|
-| `get_address_from_private_key` | Get wallet address | "What's my wallet address?" |
 | `get_balance` | Check SEI balance | "What's my SEI balance?" |
-| `transfer_sei` | Send SEI tokens | "Send 1 SEI to 0x742d..." |
 | `is_contract` | Check if address is contract | "Is 0x3894... a contract?" |
 | `estimate_gas` | Estimate transaction gas cost | "How much gas for this transaction?" |
 
+## Wallet Tools (Require Configuration) 🔐
+
+<Warning>
+These tools require [wallet configuration](/mcp-server/setup#wallet-connection) and are **disabled by default** for security.
+</Warning>
+
+| Tool | Purpose | Example Usage |
+|------|---------|---------------|
+| `get_address_from_private_key` | Get wallet address | "What's my wallet address?" |
+| `transfer_sei` | Send SEI tokens | "Send 1 SEI to 0x742d..." |
+
 ## Network & Blockchain Data
 
 | Tool | Purpose | Example Usage |
@@ -27,40 +44,68 @@ The Sei MCP Server provides 28 tools for blockchain operations. Ask your AI assi
 | `get_transaction` | Get transaction details | "Analyze transaction 0xabc..." |
 | `get_transaction_receipt` | Get transaction receipt | "Get receipt for 0xabc..." |
 
-## Token Management (ERC-20)
+## Token Management
+
+### Read-Only Token Tools
 
 | Tool | Purpose | Example Usage |
 |------|---------|---------------|
 | `get_token_info` | Get ERC-20 token details | "Get info for token 0x3894..." |
 | `get_token_balance` | Check token balance | "What's my USDC balance?" |
 | `get_erc20_balance` | Check ERC-20 balance | "Check ERC20 balance for 0x742d..." |
 | `get_token_balance_erc20` | Get ERC-20 token balance | "Get token balance for address" |
+
+### Wallet-Required Token Tools 🔐
+
+| Tool | Purpose | Example Usage |
+|------|---------|---------------|
 | `transfer_token` | Send ERC-20 tokens | "Send 100 USDC to 0x742d..." |
 | `transfer_erc20` | Transfer ERC-20 tokens | "Transfer tokens to address" |
 | `approve_token_spending` | Approve token spending | "Approve 1000 USDC for 0xDEX..." |
 
 ## NFT Operations (ERC-721)
 
+### Read-Only NFT Tools
+
 | Tool | Purpose | Example Usage |
 |------|---------|---------------|
 | `get_nft_info` | Get NFT details | "Get info for NFT token 123" |
 | `check_nft_ownership` | Verify NFT ownership | "Do I own NFT token 123?" |
-| `transfer_nft` | Transfer NFT | "Transfer NFT token 123 to 0x742d..." |
 | `get_nft_balance` | Count NFTs owned | "How many NFTs do I own?" |
 
+### Wallet-Required NFT Tools 🔐
+
+| Tool | Purpose | Example Usage |
+|------|---------|---------------|
+| `transfer_nft` | Transfer NFT | "Transfer NFT token 123 to 0x742d..." |
+
 ## Multi-Token Operations (ERC-1155)
 
+### Read-Only ERC-1155 Tools
+
 | Tool | Purpose | Example Usage |
 |------|---------|---------------|
 | `get_erc1155_balance` | Get ERC-1155 token balance | "Check my ERC1155 token balance" |
 | `get_erc1155_token_uri` | Get ERC-1155 metadata URI | "Get metadata for token ID 123" |
+
+### Wallet-Required ERC-1155 Tools 🔐
+
+| Tool | Purpose | Example Usage |
+|------|---------|---------------|
 | `transfer_erc1155` | Transfer ERC-1155 tokens | "Transfer ERC1155 token to address" |
 
 ## Smart Contract Operations
 
+### Read-Only Contract Tools
+
 | Tool | Purpose | Example Usage |
 |------|---------|---------------|
 | `read_contract` | Read contract data | "Read balanceOf from contract 0x3894..." |
+
+### Wallet-Required Contract Tools 🔐
+
+| Tool | Purpose | Example Usage |
+|------|---------|---------------|
 | `write_contract` | Execute contract function | "Call contract function with params" |
 | `deploy_contract` | Deploy new smart contract | "Deploy my token contract" |
 
@@ -70,11 +115,43 @@ The Sei MCP Server provides 28 tools for blockchain operations. Ask your AI assi
 |------|---------|---------------|
 | `search_sei_js_docs` | Search Sei-JS documentation | "How do I use precompiles with Viem?" |
 
+## Enabling Wallet Tools
+
+To use wallet-required tools (🔐), you must configure a wallet connection:
+
+<Steps>
+  <Step title="Set Private Key">
+    Add your private key to the MCP server configuration:
+    
+    ```json
+    {
+      "mcpServers": {
+        "sei": {
+          "command": "npx",
+          "args": ["-y", "@sei-js/mcp-server"],
+          "env": {
+            "WALLET_MODE": "private-key",
+            "PRIVATE_KEY": "0x123..."
+          }
+        }
+      }
+    }
+    ```
+  </Step>
+  
+  <Step title="Restart MCP Server">
+    Restart your AI assistant (Claude Desktop, Cursor, etc.) to activate wallet tools.
+  </Step>
+</Steps>
+
+[See full setup guide →](/mcp-server/setup#wallet-connection)
+
 ## Security Notes
 
 <Warning>
-The MCP server requires a `PRIVATE_KEY` environment variable for transaction signing. Ensure this key is:
+**Wallet tools require a private key for transaction signing. Ensure this key is:**
 - Kept secure and never shared
-- Only used with funds you can afford to lose
+- Only used with funds you can afford to lose  
 - Properly backed up before use
+- From a dedicated wallet, not your main holdings
 </Warning>