STS2-Agent: an in-game AI companion and MCP server for Slay the Spire 2

What STS2-Agent actually solves for Slay the Spire 2 players

Slay the Spire 2 has no scripting surface that an external AI can read. STS2-Agent closes that gap from inside the game process. The mod turns the live run into a text state covering cards, energy, enemy intents, relics, HP and potion slots, and it turns model output back into card plays, reward picks, shop purchases, event choices and path decisions. Everything runs locally: the mod talks to an OpenAI-compatible chat-completions endpoint that you configure, and it exposes its own local HTTP API on port 8080. The audience splits in two. Players want an AI teammate in co-op or a hands-off auto-play run. Developers want the state and action layer without writing a mod, which is why the same port can expose MCP at /mcp for Cursor, Claude and Codex. The README is blunt that this is a work in progress and that some things may be unfinished or break.

How the state engine and action dispatch fit together

The mechanism is a loop, not a trained policy. The mod compiles a compact text state of the current decision point and sends it to your chat-completions endpoint. The model returns tool calls, and the mod dispatches them into the game: play a card, take a reward, choose a route, buy from a shop. Vision is optional. When you bind a vision-capable model, screenshots are captured on demand to add visual context, but the README states that the text state is what combat, drafting, shops, events, pathing and capstones are built on. The overlay shows prompt, completion and total token counts plus request counts live, and session budget guards stop new calls once a limit is reached and bound retries. Two caveats are worth reading twice. Missing usage is reported as unknown, and the README says these guards are not a billing guarantee. The state engine is also the reason offline state and action tests do not prove full-run completion: passing a decision test is not the same as finishing a run.

Installing STS2-Agent from the Steam Workshop or a GitHub zip

The README recommends the Steam Workshop page. You subscribe, wait for the download, then start the game from Steam with Play with Mods and copy no files. If the game warns that the code is untrusted, accept, quit fully, enable STS2 AI Agent in Mods, and restart. The GitHub release zip is the manual path. Download sts2-ai-agent-v*-windows.zip from the releases page and unzip it, then copy only three files from the zip's mod/ folder into the game's mods/ folder, creating it if needed.

STS2AIAgent.dll
STS2AIAgent.pck
mod_id.json

The README gives this layout as the expected result, and warns against copying the whole zip or the mcp_server/ directory into mods/.

C:\Program Files (x86)\Steam\steamapps\common\Slay the Spire 2\mods\STS2AIAgent.dll
C:\Program Files (x86)\Steam\steamapps\common\Slay the Spire 2\mods\STS2AIAgent.pck
C:\Program Files (x86)\Steam\steamapps\common\Slay the Spire 2\mods\mod_id.json

Once the game is running, press F8 or click the grey AI tab on the right edge to open the overlay. In Settings you add an endpoint (name and Base URL; the API key may be empty for Ollama or LM Studio), add a model and bind it to that endpoint, then choose a Chat Model and a Play Model. An empty play model falls back to the chat model. Click Test Connection, then Save Settings. The README notes that a default URL plus model name is not treated as ready, and that chat success is not play success. Only after the play model reports connectivity should you invite a teammate.

Auto-play and the dual-instance co-op teammate

Auto-play is started from the Play tab with Start Auto-Play, or advanced one decision at a time with Step Once. The model evaluates the live state and dispatches cards, rewards and route decisions on its own. Co-op is the more interesting mode. From the main menu you switch to the AI Teammate tab and click Invite AI Teammate, and a second game window launches and joins the lobby. You play your character; the AI plays its own. The isolation work is where the engineering shows: the mod propagates --force-steam off, increments clientId in offline mode, and derives and clones settings.companion.json so the two instances never overwrite each other's configuration or save slots. Team chat lets you type instructions such as focusing an enemy or taking the shop path, and the teammate replies using its play model with recent context feeding later decisions. The README states the chat interface is read-only with respect to your character: it never plays cards for the human and never unpauses a paused companion. Proactive chat is off by default and limited to one short line at the start and end of a fight.

Where STS2-Agent stops being the right tool

The honest limitation is that the mod is a bridge, not an agent. Strategy quality and run completion depend on the model and the game conditions, and the README says so directly. If your endpoint is a small local model, expect the loop to make legal moves without making good ones; the state engine constrains what is possible, not what is wise. Budget behaviour is another boundary. Session guards track reported token usage and request counts, but missing usage shows as unknown, so a provider that does not report usage can drift past your intended ceiling without the overlay noticing. The README explicitly refuses to call these guards a billing guarantee. Installation has a failure mode too: subscribing on the Workshop and also copying the GitHub files loads two copies, and the README's instruction is to delete the manual copies and keep the Workshop item. Finally, this is a mod for a specific game on Windows, distributed as a zip with a Windows path example. If you are not running Slay the Spire 2 with mods enabled, none of the rest applies.

STS2-Agent against a general MCP desktop client

The obvious comparison is a general MCP setup that drives a desktop or browser rather than a game. A screen-driven client sees pixels and synthesizes clicks. STS2-Agent does the opposite: the mod runs inside the game and hands the model a structured text state with named actions, so the model never has to locate a card on screen. That is why vision is optional here rather than load-bearing, and why the same port can serve both a plain HTTP API and /mcp. The trade is scope. A general desktop client can be pointed at any application; STS2-Agent only knows Slay the Spire 2, and only the parts the state engine covers. If your goal is to automate decisions inside this game, the structured route is far less fragile. If your goal is to automate something else, this repository gives you nothing.

Maintenance, upgrades and what the licence does not say

The repository is not archived and the last push was on 2026-09-10, with v0.10.5 released on 2026-09-08 and v0.10.4 and v0.10.3 the day before that. Three releases inside a week is a fast cadence, and the README's own framing is that the mod is still in development, so upgrade cost is real: the overlay, the HTTP API and the MCP tool surface are all moving. The practical upgrade path is the one the README already describes, re-subscribing on the Workshop or replacing the three files in mods/ from a newer zip, and the double-install warning applies again after every upgrade. The licence field on the repository is NOASSERTION, which means GitHub could not map the LICENSE file to a known identifier. Read the LICENSE file itself before you redistribute the mod, bundle it, or ship it inside anything commercial; this is a description of what the metadata says, not legal advice. The package.json at the repository root pulls @sammysnake/fast-context-mcp and overrides its yauzl dependency to 3.2.1, which is a developer-side concern rather than something a player installs.

Editorial conclusion

Adopt STS2-Agent if you already run Slay the Spire 2 with mods and you have an OpenAI-compatible endpoint you are willing to point at a live run, or if you want an MCP client to read game state from :8080. Do not adopt it if you expect a finished, hands-off bot: the README says the mod is still in development, the guards around token budgets are explicitly not a billing guarantee, and offline state and action tests do not prove full-run completion. Before committing, verify the three files you copied into mods/ match the layout in the README, confirm you have not double-installed alongside the Workshop item, and click Test Connection on your play model rather than assuming chat success means play success.

Frequently asked questions

Official sources

1. CharTyr/STS2-Agent on GitHub
2. Issues
3. README
4. Releases