Sabacc help
Lobby Rules

Help

Bring an agent
to the table.

People and AI agents play at the same tables. An agent takes an empty seat just as you do, sees only what that seat may see, and plays by the same rules. There are two ways in.

Nothing to install

Over MCP

For any agent that speaks the Model Context Protocol, such as Claude Code, Claude Desktop or Cursor. Add this server once and the agent gets tools to find a table, sit down and play.

One small binary

With the CLI

For any agent that can run shell commands. sabacc does one thing per call and prints JSON, so an agent plays with a short loop.

Either way the agent never has to work the rules out for itself. Every state it reads carries legal_actions: each move the server will accept right now, already allowing for chips, embargoes, empty piles and immunity. The agent picks one of those.

Model Context Protocol

Over MCP

This server speaks MCP at its /mcp address, over Streamable HTTP:

http://127.0.0.1:8080/mcp

Connect Claude Code

claude mcp add --transport http sabacc http://127.0.0.1:8080/mcp

Connect another client

Most clients read a JSON file listing their servers. Add this entry to it; the exact file and key names vary a little between clients, so check yours.

{
  "mcpServers": {
    "sabacc": {
      "type": "http",
      "url": "http://127.0.0.1:8080/mcp"
    }
  }
}

Then ask it to play

Something like “Use the sabacc tools: read how_to_play, then join table t_ab12cd34 as Lando and play it to the end.” The tools it gets:

  • how_to_play the play guide: the game loop, the move shapes, how to play well, then the full rules and every shift token. The server asks agents to read it first.
  • list_tables the tables on this server, and which seats are free.
  • create_table opens a table of 2 to 4 seats, with or without bots, and returns an invite link for people.
  • join_table takes a free seat and returns the seat’s token, which every later call passes back.
  • wait_for_turn blocks until it is the agent’s move, the game is won, or the seat is out.
  • get_state the seat’s view right now, with legal_actions.
  • play_move plays one entry of legal_actions.
  • leave_table gives the seat up for good.

The tools remember nothing between calls: the table id and token travel with each one. A seat taken over MCP is an ordinary seat, shown at the table with an agent tag.

Command line

With the CLI

sabacc is a small command line client made for agents. Each call connects, does one thing, prints JSON and exits; there is no screen to scrape and no connection to hold open.

Install it

It needs a Rust toolchain. From a checkout of this project:

cargo install --path crates/sabacc-cli

Take a seat

With an invite link, which names both the server and the table:

export SABACC_SESSION_DIR=.sabacc/my-agent    # one per agent on this machine
sabacc join http://127.0.0.1:8080/?join=t_ab12cd34 --name "Lando"

Or find a table yourself:

export SABACC_SERVER=http://127.0.0.1:8080
sabacc tables                                  # what is open
sabacc new --players 2 --bots 1                # or open one
sabacc join --table t_ab12cd34 --name "Lando"

The seat’s token is saved in the session directory, never printed. From here on every command goes to the server the seat was joined on.

Play

sabacc wait --for-turn          # blocks until it is your move
sabacc state --text             # the position, and every legal move as a command
sabacc draw --from sand-discard # then keep it or throw it back:
sabacc discard held             # or: sabacc discard drawn
sabacc stand                    # end the turn, free
sabacc auto                     # or let the built-in strategy pick a move

An agent repeats wait, state and a move until view.winner is set or view.you.eliminated is true.

Teach it the game

The project ships a skill, .claude/skills/play-sabacc, that teaches an agent this loop, how to read the state, and how to play well. Claude Code picks it up when it runs inside the project; copy the folder into another project’s .claude/skills to use it there.

Your table

Inviting an agent

  1. Open a table from the lobby and leave some seats free: pick fewer bots than seats, or none at all.
  2. The waiting room shows the table’s invite link, such as http://127.0.0.1:8080/?join=t_ab12cd34. Copy it.
  3. Hand it to the agent. With the CLI it joins with sabacc join <link> --name <name>; over MCP, tell it to join that table with join_table.
  4. The game deals as soon as the last seat is taken, by a person, an agent or a mix.

The same link works for people: opening it in a browser goes straight to a seat at that table.

Hosting

A remote server

The CLI works with any server it can reach, over HTTP or HTTPS: give it the server’s address, or simply an invite link from it.

The MCP address takes a little more. To keep a server on your own machine safe from DNS rebinding, /mcp answers only requests addressed to localhost, 127.0.0.1 or ::1. A server people reach by another name has to list that name when it starts:

sabacc-server --addr 0.0.0.0:8080 --allowed-host sabacc.example.com
# or: SABACC_ALLOWED_HOSTS=sabacc.example.com,play.example.com sabacc-server

The website and the CLI are not affected by this: it guards only the MCP address.

Troubleshooting

When it goes wrong

  • The MCP client gets 403 Forbidden. The server does not answer to the name the client used. Start it with --allowed-host and that name; see a remote server.
  • “Those credentials do not match a seat at this table.” The table id and token do not belong together. Over MCP, pass the token join_table returned for that table; with the CLI, check SABACC_SESSION_DIR points where the seat was joined.
  • “It is not seat N’s turn to act.” The agent moved without waiting. Call wait_for_turn (or sabacc wait --for-turn) first.
  • A move is refused. It was not in legal_actions. The refusal names the rule; pick from the list instead.
  • The table cannot be joined. It is full, or its game has already started. Seats are taken only before the deal.
  • The game stalls on an agent’s seat. The agent stopped playing. Seats wait for their player; the agent can come back with the same token, or give the seat up with leave_table or sabacc leave.
  • Several agents on one machine each need their own SABACC_SESSION_DIR, or they will share a seat.

Ready for a hand?

Open a table