mcp-server-stu

An MCP server for the stUSDT protocol across TRON and Ethereum. It provides read-only access to protocol metadata, market metrics, rebase data, account state, user earnings, user operations, and user transfer history.

Scope

Current implementation covers:

• Network discovery and session defaults for TRON and Ethereum
• Protocol market dashboard and total balance metrics
• Rebase APY, APY history, and rebase history
• Account lookup, account snapshot compatibility handling, and unstake queue lookup
• Personal dashboard data, including overview, earning chart, earning history, operations, and transfers
• CSV exports for earning history, operations, and transfers
• Structured MCP tool schemas packaged with the server
• Backend error normalization into stable STU_E_* error codes
• SSRF guard, request timeout handling, JSON logging, and HTTP health checks

Supported Networks

| Network | Chain | Notes | |---|---|---| | mainnet | tron | Default stUSDT TRON API | | mainnet | ethereum | Default stUSDT Ethereum API |

Prerequisites

• Node.js 20+
• An MCP-compatible client such as Claude Desktop, Claude Code, Codex, or Cursor

Installation

npm install mcp-server-stu

For one-off use through npx:

npx -y mcp-server-stu

Client Configuration

Claude Desktop

Add the following config to:

~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "mcp-server-stu": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-server-stu"]
    }
  }
}

Claude Code

Create .mcp.json in the project root directory:

{
  "mcpServers": {
    "mcp-server-stu": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-server-stu"]
    }
  }
}

Cursor

Add the following config to .cursor/mcp.json:

{
  "mcpServers": {
    "mcp-server-stu": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-server-stu"]
    }
  }
}

Configuration

The server defaults to mainnet on tron.

Optional environment variables:

| Variable | Description | |---|---| | STU_NETWORK | Default network. Supported value: mainnet | | STU_DEFAULT_CHAIN | Default chain. Supported values: tron, ethereum | | STU_API_HOST_TRON | Override the base API host for the selected TRON network | | STU_API_HOST_ETHEREUM | Override the base API host for the selected Ethereum network | | STU_API_HOST_ALLOWLIST | Comma-separated host allowlist for API requests | | MCP_API_KEY | Required only for HTTP mode |

Example:

{
  "mcpServers": {
    "mcp-server-stu": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-server-stu"],
      "env": {
        "STU_NETWORK": "mainnet",
        "STU_DEFAULT_CHAIN": "tron"
      }
    }
  }
}

Tools

Network & Discovery

| Tool | Description | Write? | |---|---|---| | get_supported_networks | List supported network and chain combinations | No | | get_network | Get the active default network and chain | No | | set_network | Set the active network and chain for the session | Yes |

Market & Rebase

| Tool | Description | Write? | |---|---|---| | get_market_dashboard | Read protocol market dashboard metrics | No | | get_total_balance | Read total stUSDT balance metrics | No | | get_rebase_apy | Read the latest rebase APY | No | | get_rebase_apy_history | Read historical rebase APY data | No | | get_rebase_history | Read historical rebase records | No |

Account

| Tool | Description | Write? | |---|---|---| | get_account | Read account-level stUSDT data for an address | No | | get_account_snapshot | Return the stable endpoint-gone error for a removed backend route | No | | list_account_unstake | Read account unstake queue data | No |

Personal Dashboard

| Tool | Description | Write? | |---|---|---| | get_user_overview | Read personal dashboard overview data | No | | get_user_earning_chart | Read user earning chart data | No | | get_user_earning_history | Read user earning history | No | | export_user_earning_csv | Export user earning history as CSV | No | | get_user_operations | Read user operation history | No | | export_user_operations_csv | Export user operation history as CSV | No | | get_user_transfers | Read user transfer history | No | | export_user_transfers_csv | Export user transfer history as CSV | No |

Prompts

| Prompt | Description | |---|---| | getting_started | Explain supported networks and ask for an address or sample question | | analyze_account | Analyze account state, overview, and recent earnings for an address | | review_unstake_queue | Review an account unstake queue and claimability | | compare_chain_apy | Compare recent rebase APY across TRON and Ethereum | | protocol_health_brief | Produce a short protocol health report from market and rebase data |

Resources

| Resource | Description | |---|---| | stu://protocol-info | Active network metadata, supported combinations, and environment overrides |

HTTP Mode

The default entrypoint is stdio for MCP clients. The package also includes an HTTP server entrypoint for local integration testing.

MCP_API_KEY=$(openssl rand -hex 32) npm run start:http

HTTP mode requires MCP_API_KEY. The SSE transport path is intentionally fail-closed until the relevant SDK interfaces are stable across supported versions.

Notes

• This server is read-only with respect to the stUSDT protocol. It does not sign transactions or manage wallets.
• User identity is represented by wallet address plus chain.
• Chain-dependent account tools require an address and should use the chain requested by the user.
• Schema files are packaged inside mcp-server-stu; users do not need to install a separate schema package.
• Some backend routes that require login are intentionally not registered as MCP tools.
• get_account_snapshot is kept for compatibility and returns a stable STU_E_ENDPOINT_GONE error because the backend route has been removed.
• API host overrides are protected by an allowlist to reduce SSRF risk.

Development

git clone <repository-url>
cd mcp-server-stu
npm install
npm run validate
npm -w mcp-server-stu run build
npm -w mcp-server-stu run test

License

MIT