Skip to main content

MCP

@suigar/mcp is the Suigar MCP stdio server, plugin bundle, and bundled MCP App for agent-assisted Suigar transaction workflows on Sui.

By default, it does not sign or execute transactions. It reads Suigar config, describes game metadata, pairs a browser wallet, reads wallet balances and coin objects, builds unsigned transaction bytes, dry-runs transactions through Sui client APIs, and can open an explicit wallet approval flow for execute-mode transactions.

Advanced users can also create a local session wallet. Session-wallet execution signs and submits directly from that local session-wallet key, which is stored in the operating-system keychain. Fund only the amount you are willing to delegate to the local MCP process.

GitHub: Suigar TypeScript SDKs repository

What the MCP server does​

Use Suigar MCP when an AI coding agent needs to inspect Suigar configuration, understand supported game inputs, or prepare a transaction for a wallet or backend signer.

It can:

  • Read network-aware Suigar package ids, registry ids, supported coin metadata, and price info object ids
  • Describe live game parameters, required inputs, Move targets, type arguments, and integration notes
  • Pair or disconnect a browser wallet through a short-lived localhost flow
  • Read aggregate wallet balances and paginated coin objects
  • Create, recover, inspect, and fund a persistent local session wallet
  • List the Suigar NFT catalog and matching NFTs owned by an address
  • Read claimable referral commission and level-up USD rewards
  • Build unsigned base64 transaction bytes for supported Suigar game flows
  • Build unsigned referral reward claim transactions
  • Build unsigned NFT V1 mint transactions
  • Dry-run supported game transactions and summarize success, gas, balance changes, errors, and decoded events
  • Execute with a paired wallet approval URL, then check approval status
  • Execute supported game transactions directly from a funded local session wallet
  • Return structured JSON payloads alongside human-readable text
  • Render the Suigar Transaction Inspector in MCP App-capable hosts

It cannot:

  • Access private keys from chat messages
  • Approve a paired-wallet transaction without the user reviewing it in the browser wallet flow
  • Execute from a session wallet unless the user has explicitly set up and funded that local wallet
  • Choose an unlimited budget for a user
  • Replace your production app's wallet UX, policy checks, or transaction-confirmation UI

Install​

Suigar MCP is a local stdio MCP server. Install @suigar/mcp in the MCP client you want your agent to use.

All detected coding agents​

Use add-mcp to install Suigar MCP for the coding agents it finds on your machine:

npx add-mcp @suigar/mcp --name suigar

Add -y to skip installer prompts, then restart or reload your MCP client.

Generic MCP config​

Add the server to a JSON-based MCP config:

{
	"mcpServers": {
		"suigar": {
			"command": "npx",
			"args": ["-y", "@suigar/mcp"]
		}
	}
}

Restart or reload the MCP client after changing its config.

Codex CLI​

codex mcp add suigar -- npx -y @suigar/mcp

Then start Codex from your project and ask it to list MCP tools or use the Suigar MCP tools.

Claude Code​

claude mcp add suigar -- npx -y @suigar/mcp

Then run /mcp inside Claude Code to confirm that suigar is connected.

Cursor​

Add this to .cursor/mcp.json in your project, or to your global Cursor MCP config:

{
	"mcpServers": {
		"suigar": {
			"command": "npx",
			"args": ["-y", "@suigar/mcp"]
		}
	}
}

Restart Cursor after saving the file.

VS Code and other clients​

Use the same command and args in any MCP client that supports stdio servers:

  • Command: npx
  • Args: ["-y", "@suigar/mcp"]

Setup details vary by client. If the client has separate fields for name, command, and arguments, use suigar, npx, and -y @suigar/mcp.

Available tools​

Current tools:

  • setup_session_wallet
  • get_session_wallet
  • fund_session_wallet
  • suigar_login
  • suigar_logout
  • get_connection_status
  • read_config
  • read_game_metadata
  • list_nfts
  • get_wallet_balances
  • list_wallet_coins
  • get_execution_status
  • get_referral_commission
  • get_referral_level_up_usd_rewards
  • build_referral_commission_claim_transaction
  • build_referral_level_up_usd_rewards_claim_transaction
  • build_nft_v1_mint_transaction
  • build_coinflip_transaction
  • build_limbo_transaction
  • build_plinko_transaction
  • build_soccer_transaction
  • build_wheel_transaction
  • build_range_transaction
  • build_pvp_coinflip_create_transaction
  • build_pvp_coinflip_join_transaction
  • build_pvp_coinflip_cancel_transaction

All tools return text content plus structuredContent. Hosts that support MCP Apps can render purpose-built Suigar views for config discovery, live game parameters, NFTs, referral rewards, wallet/session-wallet state, execution status, and transaction inspection.

Wallet tools​

suigar_login, suigar_logout, and get_connection_status manage a paired browser wallet for the selected network. Login and logout open the same local browser bridge used by the CLI, so the wallet pairing page starts automatically instead of requiring manual URL copy and paste.

get_wallet_balances returns aggregate balances for the paired wallet or an explicit address. list_wallet_coins returns paginated individual coin objects for the paired wallet or an explicit address. These tools are useful before sizing a bet or preparing a session-wallet funding transfer.

setup_session_wallet opens a local setup page to create, recover, or import one persistent session wallet. Recovery phrases and imported suiprivkey... exports stay in the local browser setup flow; they are not returned through MCP. The signing key is stored in the operating-system keychain.

get_session_wallet returns the session wallet address, formatted balances for the selected network, a funding QR code, and, when a browser wallet is paired, a prefilled funding link. fund_session_wallet opens that prefilled transfer flow so the user can choose a coin and amount, then review and sign from the paired wallet.

Command-line wallet management is also available:

npx -y @suigar/mcp login --network testnet
npx -y @suigar/mcp status --network testnet
npx -y @suigar/mcp logout --network testnet
npx -y @suigar/mcp clean

Useful environment variables:

  • SUIGAR_MCP_BRIDGE_WEB_URL for a custom connection-page origin
  • SUIGAR_MCP_BRIDGE_TIMEOUT_MS for login, logout, and approval bridge expiry
  • SUIGAR_MCP_BRIDGE_MAX_BODY_BYTES for maximum browser callback JSON body size
  • SUIGAR_MCP_SESSION_SETUP_TIMEOUT_MS for local session-wallet setup page expiry

Read tools​

read_config returns the resolved Suigar configuration for mainnet or testnet, including package ids, registry ids, supported coin metadata, and price info object ids.

read_game_metadata returns the supported inputs, live onchain parameters, and transaction wiring for one game flow. Use it before asking an agent to build a transaction so the agent can see required fields, optional fields, and mode support.

list_nfts returns the Suigar NFT V1 catalog and matching NFTs owned by an address or SuiNS name. get_referral_commission and get_referral_level_up_usd_rewards simulate the corresponding claim and return the amount currently available; a non-claimable reward returns 0.

Transaction builder tools​

Transaction tools cover:

  • Standard games: Coinflip, Limbo, Plinko, Soccer, Wheel, and Range
  • PvP Coinflip: create, join, and cancel
  • Referral rewards: commission and level-up USD reward claims
  • NFT V1 minting

Game transaction tools support read-only, build, dry-run, and execute. Referral and NFT transaction tools support the same planning/build/simulation shape and paired-wallet approval where supported by the current tool.

Modes​

  • read-only: resolves config and returns the intended Move target, type arguments, required inputs, and notes.
  • build: returns unsigned transaction bytes as base64 plus a transaction summary.
  • dry-run: simulates the unsigned transaction and returns a JSON-safe raw dry-run result plus a stable summary.
  • execute: opens a paired-wallet approval request by default. For game tools, pass executionWallet: "session" to sign and submit from the funded local session wallet instead.

Dry-run summaries include success state, errors when present, gas deltas, balance changes, and decoded event fields when available.

Inputs​

For build, dry-run, and paired-wallet execute, transaction owner inputs accept raw Sui addresses, SuiNS names such as name.sui, and SuiNS subnames such as sub.name.sui.

For session-wallet execution, MCP uses the local session-wallet address. In that mode, owner is optional; if supplied, it must match the selected session wallet.

stake and cashStake are currency amounts in the selected coin, not base-unit integers. For example, stake: 1 means 1 SUI or 1 USDC depending on the resolved coin type. The MCP server converts those amounts to base units before calling @suigar/sdk.

metadata values must be JSON-compatible strings, numbers, or booleans. Send large integer metadata values as strings.

Optional shared transaction inputs include gasBudget in MIST and useGasCoin for native SUI bets. Some game tools accept betCount; when provided for Limbo, Plinko, Range, Soccer, or Wheel, MCP reads active onchain parameters and rejects counts above the declared maximum.

NFT V1 minting requires owner and specId. Referral commission claims require owner and optionally coinType; referral level-up USD reward claims require owner.

Config​

network defaults to testnet. Supported networks are mainnet and testnet. Pass providerUrl when the MCP client should use a specific Sui gRPC endpoint instead of the default network endpoint.

Optional config follows the public SDK extension override shape:

{
	packageIds?: {
		nftV1?: string;
		referral?: string;
		core?: string;
		coinflip?: string;
		limbo?: string;
		plinko?: string;
		pvpCoinflip?: string;
		range?: string;
		soccer?: string;
		wheel?: string;
	};
	objectIds?: {
		sweetHouse?: string;
		nftV1Factory?: string;
	};
	registryIds?: { pvpCoinflip?: string };
	coins?: {
		sui?: { coinType?: string; decimals?: number; priceInfoObjectId?: string };
		usdc?: { coinType?: string; decimals?: number; priceInfoObjectId?: string };
	};
}

Partner attribution should be passed as top-level partner. The MCP server forwards it through suigar({ partner }).

Example prompts​

After the server is connected, prompts like these work well:

  • "Use Suigar MCP to read mainnet config and tell me the supported coin types."
  • "Use Suigar MCP to inspect the Coinflip transaction inputs before wiring my form."
  • "Log in my testnet Suigar wallet through MCP and show the connection status."
  • "Show my paired wallet balances and list my SUI coin objects."
  • "Set up a local session wallet, then show me its funding QR code."
  • "Build a testnet Coinflip transaction in read-only mode for owner 0x..., SUI, stake 1, and heads."
  • "Dry-run a testnet Plinko transaction for owner 0x... with SUI stake 0.1 and summarize any errors."
  • "Execute a tiny testnet Coinflip with my paired wallet and give me the approval URL."
  • "Use my funded session wallet to execute a testnet Coinflip, then return the digest."
  • "Show the Suigar NFTs owned by name.sui."
  • "Build an NFT V1 mint transaction for spec 0x... in read-only mode."
  • "Check the referral commission available for name.sui, then build the claim in read-only mode."
  • "Use Suigar MCP to get PvP Coinflip metadata, then show me the fields needed to create a lobby."

For build and dry-run, pass a real owner address or resolvable SuiNS name. For dry-run, the owner must have enough funds and the selected network must have live Suigar config.

Agent Skills​

Suigar agent skills live in Suigar-Gaming/agent-skills. The suigar-mcp skill teaches agents how to install, configure, operate, and troubleshoot this MCP server and MCP App.

Browse available skills:

npx skills list Suigar-Gaming/agent-skills --list

Install a specific skill:

npx skills add Suigar-Gaming/agent-skills --skill suigar-mcp

Install all skills:

npx skills add Suigar-Gaming/agent-skills

Boundaries​

  • Coin object ids and explicit coin sourcing are intentionally not exposed.
  • list_nfts, wallet reads, session-wallet reads, connection status, execution status, and referral reward reads are read-only.
  • Referral claim and NFT mint builders return transactions for review and never claim or mint by themselves in read-only, build, or dry-run.
  • PvP Coinflip join may need live object reads when serialized or dry-run, because the SDK resolves the current game stake from the game object.
  • Use @suigar/sdk directly when your app needs to sign, execute, or deeply customize wallet UX.

Security notes​

  • Verify that the server command points to the official package: @suigar/mcp from github.com/Suigar-Gaming/ts-sdks.
  • Keep human review enabled for any workflow that later signs or executes the transaction bytes produced by MCP.
  • Use session wallets only with limited funds you are willing to delegate to the local MCP process.
  • Keep session-wallet recovery phrases and private-key exports out of MCP chats. The setup page is local; chat is not.
  • Treat dry-run results as a simulation, not a guarantee that a later signed transaction will succeed against changed onchain state.
  • Do not paste private keys, seed phrases, or signing credentials into an MCP chat. Suigar MCP does not need them.