> For the complete documentation index, see [llms.txt](https://suigar.gitbook.io/suigar-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://suigar.gitbook.io/suigar-docs/public/mcp.md).

# MCP

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

It never signs or executes transactions. It reads Suigar config, describes game metadata, builds unsigned transaction bytes, and can dry-run transactions through Sui client APIs.

GitHub: [Suigar TypeScript SDKs repository](https://github.com/Suigar-Gaming/ts-sdks)

## 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 game metadata, required inputs, Move targets, type arguments, and integration notes
* build unsigned base64 transaction bytes for supported Suigar game flows
* dry-run supported game transactions and summarize success, gas, balance changes, errors, and decoded events
* return structured JSON payloads alongside human-readable text
* render the Suigar Transaction Inspector in MCP App-capable hosts

It cannot:

* sign transactions
* execute transactions
* choose wallet coin objects for a user
* replace your app's wallet connection, signing, or transaction-confirmation UI

## Install

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

### Generic MCP config

Add the server to a JSON-based MCP config:

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

Restart or reload the MCP client after changing its config.

### Codex CLI

```bash
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

```bash
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:

```json
{
	"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:

* `read_config`
* `read_game_metadata`
* `build_coinflip_transaction`
* `build_limbo_transaction`
* `build_plinko_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 the Suigar Transaction Inspector UI for game metadata and transaction tool responses.

### 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 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.

### Transaction builder tools

Transaction tools cover:

* standard games: Coinflip, Limbo, Plinko, Wheel, and Range
* PvP Coinflip: create, join, and cancel

Each transaction tool supports the same three modes: `read-only`, `build`, and `dry-run`.

## 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.

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

## Inputs

Transaction `owner` inputs accept raw Sui addresses, SuiNS names such as `name.sui`, and SuiNS subnames such as `sub.name.sui`.

`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.

## 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:

```ts
{
	packageIds?: {
		sweetHouse?: string;
		core?: string;
		coinflip?: string;
		limbo?: string;
		plinko?: string;
		pvpCoinflip?: string;
		range?: string;
		wheel?: string;
	};
	registryIds?: { pvpCoinflip?: string };
	coins?: {
		sui?: { coinType?: string; decimals?: number };
		usdc?: { coinType?: string; decimals?: number };
	};
	priceInfoObjectIds?: { sui?: string; usdc?: 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."
* "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."
* "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](https://github.com/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:

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

Install a specific skill:

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

Install all skills:

```bash
npx skills add Suigar-Gaming/agent-skills
```

## Boundaries

* Coin object ids and explicit coin sourcing are intentionally not exposed.
* 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](https://github.com/Suigar-Gaming/ts-sdks).
* Keep human review enabled for any workflow that later signs or executes the transaction bytes produced by MCP.
* 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.