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/mcpConnect Claude Code
claude mcp add --transport http sabacc http://127.0.0.1:8080/mcpConnect 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_playthe 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_tablesthe tables on this server, and which seats are free.create_tableopens a table of 2 to 4 seats, with or without bots, and returns an invite link for people.join_tabletakes a free seat and returns the seat’s token, which every later call passes back.wait_for_turnblocks until it is the agent’s move, the game is won, or the seat is out.get_statethe seat’s view right now, withlegal_actions.play_moveplays one entry oflegal_actions.leave_tablegives 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-cliTake 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 moveAn 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
- Open a table from the lobby and leave some seats free: pick fewer bots than seats, or none at all.
- The waiting room shows the table’s invite link, such as
http://127.0.0.1:8080/?join=t_ab12cd34. Copy it. - Hand it to the agent. With the CLI it joins with
sabacc join <link> --name <name>; over MCP, tell it to join that table withjoin_table. - 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-serverThe 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-hostand 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_tablereturned for that table; with the CLI, checkSABACC_SESSION_DIRpoints where the seat was joined. - “It is not seat N’s turn to act.” The agent moved without waiting. Call
wait_for_turn(orsabacc 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_tableorsabacc leave. - Several agents on one machine each need their own
SABACC_SESSION_DIR, or they will share a seat.