SUN MCP Server

An MCP server for AI-driven DeFi operations on the TRON network through the SUN.IO / SUNSWAP ecosystem.

Contents

• Overview
• Quick Start
  • Official Hosted MCP (Read-Only)
  • Local Hosted MCP
    • Configuration
      • Wallet Configuration
      • Network Configuration
    • Verify
  • Example Prompts
• Client Integration Guide
  • Claude Desktop
  • Cursor
  • Production HTTP Deployment
• API & Tools Reference
  • Supported SUN.IO API Domains
  • Wallet & Portfolio
  • Price & Quote
  • Swap
  • V2 Liquidity
  • V3 Liquidity
  • V4 Liquidity
  • Generic Contract
  • Auto-Compute Features
• Troubleshooting
• Security Considerations

Overview

Connect any AI client to the TRON DeFi ecosystem through a single MCP endpoint. With @bankofai/sun-mcp-server, your AI agent can:

• Query — token prices, pool stats, liquidity positions, farming rewards, protocol metrics
• Quote — swap routes and price impact across SUNSwap V2, V3, and V4
• Execute — token swaps, liquidity add/remove, position management (wallet required)
• Contract — read from or write to arbitrary TRON smart contracts

The server supports stdio (local) and Streamable HTTP (remote) transports. Without a wallet configured, it runs in read-only mode — safe for exploration and data queries.

Quick Start

Official Hosted MCP (Read-Only)

The fastest way to try SUN MCP Server — no installation, no configuration. BankOfAI hosts a public read-only instance.

Point your client to the official endpoint:

claude mcp add --transport http sun-mcp-server https://sun-mcp-server.bankofai.io/mcp

This gives you access to all read-only tools: token prices, pool data, positions, quoting, and more. No wallet is configured on the hosted instance, so write operations (swaps, liquidity) are not available.

curl example — call the getPrice tool via MCP JSON-RPC:

curl -X POST https://sun-mcp-server.bankofai.io/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "getPrice",
      "arguments": {
        "tokenAddress": "TKkeiboTkxXKJpbmVFbv4a8ov5rAfRDMf9"
      }
    }
  }'

Response (SSE format):

event: message
data: {
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"msg\":\"SUCCESS\",\"code\":0,\"data\":{\"TKkeiboTkxXKJpbmVFbv4a8ov5rAfRDMf9\":{\"quote\":{\"USD\":{\"price\":\"37.513242926312\"}}}},\"status\":{\"error_code\":0}}"
      }
    ]
  },
  "jsonrpc": "2.0",
  "id": 1
}

No local installation needed. Works with any MCP client that supports Streamable HTTP.

Local Hosted MCP

Run the server locally with full capabilities — including write operations if you configure a wallet.

Install:

npm install -g @bankofai/sun-mcp-server

Configuration

Wallet Configuration

Without a wallet, the server works in read-only mode — you can query prices, pools, positions, and more.

Wallets are managed through agent-wallet file-backed configuration. Install and configure agent-wallet first. This repository no longer reads or maps legacy TRON_PRIVATE_KEY, TRON_MNEMONIC, or TRON_MNEMONIC_ACCOUNT_INDEX wallet variables.

Note See agent-wallet for wallet file formats, local setup, and the full set of SDK-supported AGENT_WALLET_* options.

Network Configuration

• TRON_NETWORK — optional network override, defaults to mainnet
• TRON_GRID_API_KEY — optional TronGrid API key for higher-rate mainnet access
• TRON_RPC_URL — optional custom TRON RPC endpoint

Example:

export TRON_NETWORK=mainnet
export TRON_GRID_API_KEY="<YOUR_TRONGRID_API_KEY_HERE>"
export TRON_RPC_URL=https://your-tron-rpc.example

stdio — the MCP client spawns and manages the server process automatically. No manual server management needed.

# Read-only (no wallet)
claude mcp add sun-mcp-server sun-mcp-server

# With wallet and runtime settings
claude mcp add sun-mcp-server sun-mcp-server \
  -e AGENT_WALLET_PRIVATE_KEY=your_private_key

Environment variables passed via -e are injected into the server process. Claude starts the server when it needs SUN.IO tools, and stops it when done.

You can also skip the global install and use npx:

claude mcp add sun-mcp-server -- npx -y @bankofai/sun-mcp-server

Streamable HTTP — run a persistent HTTP server, useful for sharing one endpoint across a team or deploying in Docker / Kubernetes.

# Start the server
sun-mcp-server --transport streamable-http --host 127.0.0.1 --port 8080 --mcpPath /mcp

# Register it with your MCP client
claude mcp add --transport http sun-mcp-server http://127.0.0.1:8080/mcp

For external access (e.g. from other machines or containers), bind to 0.0.0.0 instead of 127.0.0.1.

Verify

Confirm the server is registered:

claude mcp list

You should see sun-mcp-server in the output. Now just chat with Claude — see Example Prompts below.

Example Prompts

Market data (read-only, no wallet needed):

• "Get the current price of SUN and JST on TRON."
• "List the most liquid SUNSwap pools for USDT."
• "Show my V3 and V4 positions for wallet T...."

Quoting (read-only):

• "Quote a swap from 100 USDT to TRX on SUNSwap."
• "Quote the best exact-input route for 500 USDT to SUN."

Wallet & execution (requires wallet):

• "Get balances for my active wallet on TRON."
• "Swap 100 USDT to TRX on SUNSwap."
• "Mint a V3 position between these two ticks."
• "Increase liquidity for this V4 position."

Contract interaction:

• "Read the slot0 state from this SUNSwap pool contract."

Client Integration Guide

The Quick Start examples use Claude Code. If you use a different MCP client, follow the patterns below.

Claude Desktop

Add to your MCP configuration file (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

stdio (recommended):

{
  "mcpServers": {
    "sun-mcp-server": {
      "command": "sun-mcp-server",
      "args": [],
      "env": {
        "TRON_NETWORK": "mainnet"
      }
    }
  }
}

Remote HTTP (if using a hosted or self-hosted HTTP endpoint):

{
  "mcpServers": {
    "sun-mcp-server": {
      "url": "http://127.0.0.1:8080/mcp"
    }
  }
}

Cursor

Add to .cursor/mcp.json in your project root:

stdio:

{
  "mcpServers": {
    "sun-mcp-server": {
      "command": "sun-mcp-server",
      "args": [],
      "env": {
        "TRON_NETWORK": "mainnet"
      }
    }
  }
}

Remote HTTP:

{
  "mcpServers": {
    "sun-mcp-server": {
      "url": "http://127.0.0.1:8080/mcp"
    }
  }
}

Production HTTP Deployment

If you are deploying the server for shared or production use, consider adding:

• TLS termination via reverse proxy (Nginx, Caddy, Cloudflare)
• Authentication at the proxy or gateway layer
• Request logging and rate limiting
• Secret injection through your deployment platform instead of .env files

API & Tools Reference

Category	Tools	Wallet Required	Description
SUN.IO API	Dynamic (from OpenAPI spec)	No	Protocol, token, pool, pair, price, position, farm data
Wallet & Portfolio	get_wallet_address, get_balances	Yes	Wallet address and TRX/TRC20 balances
Price & Quote	get_token_price, quote_exact_input	No	Spot prices and smart-router quoting
Swap	swap, swap_exact_input	Quote: No / Execute: Yes	Route discovery and token swaps
V2 Liquidity	v2_add_liquidity, v2_remove_liquidity	Yes	Classic LP add/remove
V3 Liquidity	v3_mint_position, v3_increase_liquidity, v3_decrease_liquidity, v3_collect	Yes	Concentrated liquidity positions
V4 Liquidity	v4_mint_position, v4_increase_liquidity, v4_decrease_liquidity, v4_collect	Yes	V4 position management and fee collection
Generic Contract	read_contract, send_contract	Read: No / Send: Yes	Direct TRON contract interaction

All custom tool names are prefixed with sunswap_ (e.g. sunswap_swap, sunswap_v3_mint_position).

---

Supported SUN.IO API Domains

The server dynamically generates read-only tools from the bundled SUN.IO OpenAPI spec. The default spec includes:

Domain	Tool	Endpoint	Description
Transactions	scanTransactions	GET /apiv2/transactions/scan	Scan swap/add/withdraw activity with pagination
Tokens	getTokens	GET /apiv2/tokens	Fetch tokens by address and protocol
	searchTokens	GET /apiv2/tokens/search	Fuzzy token search by keyword
Protocols	getProtocol	GET /apiv2/protocols	Protocol snapshot data
	getVolHistory	GET /apiv2/protocols/history/vol	Protocol volume history
	getLiqHistory	GET /apiv2/protocols/history/liq	Protocol liquidity history
	getUsersCountHistory	GET /apiv2/protocols/history/usersCount	Protocol users history
	getTransactionsHistory	GET /apiv2/protocols/history/transactions	Protocol transaction count history
	getPoolsCountHistory	GET /apiv2/protocols/history/poolsCount	Protocol pool count history
Prices	getPrice	GET /apiv2/price	Token price by address
Positions	getUserPositions	GET /apiv2/positions/user	User liquidity positions
	getPoolUserPositionTick	GET /apiv2/positions/tick	Pool tick-level position details
Pools	getPools	GET /apiv2/pools	Fetch pools by address, token, or protocol
	searchPools	GET /apiv2/pools/search	Pool search
	searchCountPools	GET /apiv2/pools/search/count	Pool search count
	getTopApyPoolList	GET /apiv2/pools/top_apy_list	Top APY pools (paginated)
	getPoolHooks	GET /apiv2/pools/hooks	Pool hooks list
	getPoolVolHistory	GET /apiv2/pools/history/vol	Pool volume history
	getPoolLiqHistory	GET /apiv2/pools/history/liq	Pool liquidity history
Pairs	getPairsFromEntity	GET /apiv2/pairs	Token pair entity query
Farms	getFarms	GET /apiv2/farms	Farming pool list
	getFarmTransactions	GET /apiv2/farms/transactions	Farm transaction scanning
	getFarmPositions	GET /apiv2/farms/positions/user	User farming positions

The exact set of tools depends on the loaded OpenAPI spec and any configured whitelist/blacklist filters.

Wallet & Portfolio

Key tools:

• sunswap_get_wallet_address — returns the active TRON wallet address
• sunswap_get_balances — returns TRX and TRC20 token balances for the active wallet

These tools are read-only and require a configured wallet source.

Price & Quote

Key tools:

• sunswap_get_token_price — spot price lookup via SUN.IO API
• sunswap_quote_exact_input — smart-router exact-input quoting across SUNSwap V2, V3, and V4 pools

Both tools are read-only and do not require a wallet.

Swap

Key tools:

• sunswap_swap — higher-level swap that handles route computation and execution in one call
• sunswap_swap_exact_input — execute an exact-input swap via the smart router

Swap tools can operate in:

• Read-only quote mode without a wallet
• Execution mode with a configured wallet source

V2 Liquidity

Key tools:

• sunswap_v2_add_liquidity
• sunswap_v2_remove_liquidity

Use these for classic LP flows on SUNSwap V2-style pools.

V3 Liquidity

Key tools:

• sunswap_v3_mint_position
• sunswap_v3_increase_liquidity
• sunswap_v3_decrease_liquidity
• sunswap_v3_collect

These tools support concentrated liquidity workflows for SUNSwap V3-style positions.

V4 Liquidity

Key tools:

• sunswap_v4_mint_position
• sunswap_v4_increase_liquidity
• sunswap_v4_decrease_liquidity
• sunswap_v4_collect

These tools support SUNSwap V4-style position management and fee collection.

Generic Contract

Key tools:

• sunswap_read_contract
• sunswap_send_contract

Use these when you need direct TRON contract interaction outside the higher-level abstractions.

Auto-Compute Features

The higher-level SUNSwap tools automatically compute or fill in parameters so that clients can call them with minimal input. Below is what each category handles:

All write tools:

• recipient defaults to the active wallet address
• deadline defaults to 30 minutes from now
• Transactions are built, signed, and broadcast in a single call

V3 Mint (sunswap_v3_mint_position):

• If tick range is omitted, defaults to ±50 × tickSpacing around the current price
• Supports single-sided input — provide only amount0 or amount1
• Slippage tolerance defaults to 95%

V4 Mint (sunswap_v4_mint_position):

• If tick range is omitted, defaults to ±100 × tickSpacing around the current price
• Slippage tolerance defaults to 5%

Swap tools:

• sunswap_swap handles route discovery, quoting, and execution as one operation
• sunswap_swap_exact_input accepts a pre-computed route or finds the best one automatically

This reduces client-side orchestration and keeps the MCP interface simpler than raw contract calls.

Troubleshooting

Write tools fail with "no wallet configured" You are running in read-only mode. Set exactly one wallet source (AGENT_WALLET_PRIVATE_KEY, AGENT_WALLET_MNEMONIC, or AGENT_WALLET_PASSWORD) and restart the server.

Server rejects startup with "conflicting wallet modes" More than one wallet source is set. Remove the extras so that only one of the three wallet environment variable groups is present.

Too many tools — LLM context or token limit exceeded Use --whitelist / --blacklist (or the MCP_WHITELIST_OPERATIONS / MCP_BLACKLIST_OPERATIONS environment variables) to limit which OpenAPI tools are exposed. For example, --whitelist "getPools,getTokenPrice,GET:/apiv2/tokens/*" keeps only the tools you need.

API requests time out or return empty results Check TRON_RPC_URL and TRON_GRID_API_KEY. The default public TronGrid endpoint has rate limits. For production use, supply your own API key or a dedicated RPC endpoint.

Connection refused on Streamable HTTP Verify MCP_SERVER_HOST, MCP_SERVER_PORT, and MCP_SERVER_PATH match what your client is connecting to. If the server binds to 127.0.0.1, it will not be reachable from other machines — use 0.0.0.0 for external access.

Security Considerations

• Treat AGENT_WALLET_PRIVATE_KEY, AGENT_WALLET_MNEMONIC, and AGENT_WALLET_PASSWORD as production secrets.
• Configure exactly one wallet source at a time. The server rejects conflicting wallet modes.
• Prefer read-only deployments when you only need market data or position inspection.
• Do not expose a write-enabled Streamable HTTP deployment directly to the public internet without authentication and transport security.
• If you use AGENT_WALLET_PASSWORD, keep AGENT_WALLET_DIR on encrypted storage where possible.
• Review any custom RPC endpoint before use. A malicious or misconfigured RPC can degrade reliability or leak metadata.
• Log carefully. Avoid writing secrets, raw signed payloads, or sensitive wallet paths to logs.