Suigar Gaming MCP

@suigar/mcp

MCP server for agents working with Suigar’s provably fair casino games on Sui, SweetHouse pools, NFTs, and referral claims.

• SDK-backed tools for reading Suigar config and live game metadata
• Referral claimable-amount reads and unsigned claim builders
• Unsigned transaction builders for standard Suigar games, PvP Coinflip, and SweetHouse
• build, dry-run, and read-only modes
• A compact MCP App UI resource for compatible hosts
• Text and structured-content fallbacks for normal MCP clients

Transactions remain unsigned by default. mode: "execute" uses the paired Suigar browser wallet and opens an explicit approval request unless executionWallet: "session" is selected. Session execution signs and submits directly from the local session-wallet key held in the operating-system keychain; it returns the final transaction digest without an approval URL. Wallet balance reads aggregate all result pages and display human-readable amounts using configured or on-chain coin metadata.

Wallet validation uses TypeError for malformed recovery phrases and RangeError for unsupported private-key schemes or oversized bridge requests. Wallet bridges and session setup validate 32-byte hexadecimal state tokens and compare their decoded bytes using timing-safe equality. Wallet setup pages continue to display the error message; operational failures such as expired sessions and unavailable keychain storage remain generic errors.

Install

Runtime requirement:

• Node.js ^24.0.0 || ^26.0.0.

Install for all detected coding agents with add-mcp:

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

Add -y to skip the installer prompts. Restart or reload your MCP client after installation.

Manual configuration

To add the stdio server to an MCP client yourself, use:

{

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

Package installation

Install the package directly when you need to import its programmatic API or run a local copy:

npm install @suigar/mcp

The package is also published on JSR for programmatic imports:

pnpm add jsr:@suigar/mcp

The server registers tools and resources through the MCP server and MCP Apps APIs. It targets MCP 2026-07-28. The server and bundled App use MCP SDK 2 and ext-apps 2 and support MCP Apps 1.x hosts.

The stdio server supports MCP 2026-07-28 and older clients that use initialization. Call startSuigarMcpServer() to start stdio, or createSuigarMcpServer() to get an McpServer from @modelcontextprotocol/server v2.

Plugins

The package also ships plugin/ manifests for plugin-capable hosts:

• plugin/.codex-plugin/plugin.json for Codex
• plugin/.claude-plugin/plugin.json for Claude Code
• plugin/.cursor-plugin/plugin.json for Cursor
• plugin/plugin.json for Antigravity-style plugin discovery

The Codex, Claude, and Cursor manifests use the bundled .mcp.json MCP config, which registers the npx -y @suigar/mcp@ stdio server. Plugin manifest versions, the MCP config package specifier, and package-local JSR config versions are kept in sync with packages/mcp/package.json by pnpm run codegen:version, which also runs during pnpm run changeset:version.

Repository marketplace catalogs support GitHub installation and local plugin testing:

• .agents/plugins/marketplace.json for ChatGPT desktop and Codex
• .claude-plugin/marketplace.json for Claude Code
• .cursor-plugin/marketplace.json for Cursor multi-plugin repository discovery

For Codex, install the marketplace from GitHub, then install the suigar-mcp plugin:

codex plugin marketplace add Suigar-Gaming/ts-sdks

codex plugin add suigar-mcp@suigar

For Claude Code, use the equivalent GitHub marketplace flow:

claude plugin marketplace add Suigar-Gaming/ts-sdks

claude plugin install suigar-mcp@suigar

Inside an interactive Claude Code session, use /plugin marketplace add Suigar-Gaming/ts-sdks and /plugin install suigar-mcp@suigar instead. For local development, replace Suigar-Gaming/ts-sdks with . in either marketplace-add command. ChatGPT desktop local testing works by opening the repository, restarting the app, opening the Plugins directory in Work mode or Codex, then installing suigar-mcp from the Suigar source.

For Cursor, the repository includes both the plugin manifest and a root .cursor-plugin/marketplace.json for multi-plugin repository flows. During local development, you can also copy or symlink packages/mcp/plugin into Cursor's local plugin directory and reload Cursor. If you only need MCP tools, direct MCP configuration with npx -y @suigar/mcp is simpler and does not require the plugin wrapper.

Local development

The package uses the shared strict TypeScript checks with isolatedDeclarations disabled so Zod can infer schema and handler types. Run these commands from the repository root.

pnpm turbo run build --filter=@suigar/mcp

node packages/mcp/dist/bin.mjs

This builds the local workspace dependencies, MCP server, and bundled MCP App. Run the generated stdio entrypoint from the repository root for manual client testing.

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_sweethouse_deposit_transaction
• build_sweethouse_redeem_request_transaction
• build_sweethouse_claim_own_redeem_request_after_delay_transaction
• build_coinflip_transaction
• build_keno_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 in content alongside structuredContent. Known tools return isError: true for invalid inputs and handler failures. Handler errors include text and structured details. An unknown tool name raises a JSON-RPC invalid-params error (-32602).

Hosts that support MCP Apps can display config, live game parameters, the NFT catalog and wallet holdings, referral rewards, SweetHouse plans, and transaction details in the bundled App.

Wallet tools

• Paired browser wallet
• suigar_login, suigar_logout, and get_connection_status manage the paired browser wallet.
• suigar_login and suigar_logout start the same local npx -y @suigar/mcp ... CLI flows used for command-line wallet management, so the correct mainnet or testnet pairing page opens in the default browser instead of requiring manual URL copy/paste.
• suigar_login and suigar_logout accept webUrl, timeoutMs, maxBodyBytes, open, and noOpen inputs matching the CLI bridge options.
• get_wallet_balances and list_wallet_coins read aggregate balances or paginated coin objects. Both also accept an explicit address.
• get_execution_status checks an execute-mode transaction's browser approval result.
• Local session wallet
• setup_session_wallet opens a local, one-time setup page to create or recover one persistent session wallet shared by mainnet and testnet.
• Set SUIGAR_MCP_SESSION_SETUP_TIMEOUT_MS to control how long local setup pages remain available. The built-in default is 600000.
• It does not require a paired browser wallet, and its recovery phrase never passes through MCP.
• The local setup page can also import a standard suiprivkey... export. It never passes through MCP or the session-wallet JSON file.
• The operating-system keychain protects the signing key without a separate application passphrase. Avoid custom encrypted files. Use a dedicated wallet with a small balance to limit the funds the session can spend.
• MCP keeps one active session wallet. Restarting MCP automatically uses that same keychain entry; importing or recovering another wallet requires explicit replacement confirmation. Keep the original recovery phrase/private-key backup to restore it later.
• get_session_wallet returns the public address, formatted balances, and a funding QR code. If a wallet is paired on the selected network, it also returns a prefilled funding URL.
• fund_session_wallet requires a paired wallet and opens a prefilled mcp-website transfer form. The user chooses an owned coin and amount, then reviews and signs the transfer in their browser.
• In an App-capable host, it displays a dedicated Session Wallet view with balances for the selected network, a funding QR code, and a paired-wallet funding link when available. If no wallet exists, the same view provides the local setup link.
• Fund only the amount the user is willing to delegate to the local MCP process.
• For game tools, use mode: "execute", executionWallet: "session" to make the session wallet the sender and submit immediately. owner is optional in this mode; if supplied, it must match the session-wallet address. Ensure it is funded for both the wager and gas. You can set a custom provider URL and partner; custom SDK config overrides are rejected. Before signing, the server verifies that the built transaction calls only the selected Suigar game package.
• Command-line wallet management
• Run npx -y @suigar/mcp login --network testnet (or mainnet), status, logout, or clean.
• Login uses a short-lived, localhost-only browser pairing flow and stores non-secret network-specific metadata in ~/.suigar-mcp/credentials.json with owner-only permissions.
• status shows the current connection. logout --all disconnects every stored network and opens both logout pages when using the default Suigar mainnet and testnet web origins. clean deletes the local credential file without opening a browser.
• Set SUIGAR_MCP_BRIDGE_WEB_URL or pass --web-url to use a local or custom connection-page origin.
• Set SUIGAR_MCP_BRIDGE_TIMEOUT_MS or pass --timeout-ms to control how long login, logout, and approval bridges wait before expiring. The default is 300000.
• Set SUIGAR_MCP_BRIDGE_MAX_BODY_BYTES or pass --max-body-bytes to control the maximum browser callback JSON body size. The default is 16384.
• Bridge URLs open automatically by default. Pass --no-open for CLI login or logout when you only want the URL or URLs printed.
• Your MCP client discovers the available tools automatically through the MCP protocol.

Read tools

• read_config, read_game_metadata, list_nfts, wallet balance/coin reads, execution status, and the referral amount reads are read-only.
• SDK-backed reads accept shared network, provider, SDK config, and partner inputs.
• read_game_metadata additionally requires game; the NFT and referral reads additionally require an owner address or SuiNS name.
• Referral reads simulate the SDK's real claim transaction and return 0 when it cannot be claimed or simulated.
• get_referral_commission accepts an optional coinType (defaulting to configured SUI); level-up USD rewards use configured USDC.

In an App-capable host, the NFT view presents catalog and owned-NFT tables separately. HTTPS NFT image URLs are displayed as thumbnails, while unavailable or unsupported image URLs remain visible as text. Referral reads render a dedicated Referral Rewards view with the referrer, reward type, coin type, and simulated claimable amount.

Transaction tools

All transaction tools accept the shared config inputs and support these mode