Balatro solver API and MCP
Versioned hand scoring and exact small-deck analysis through HTTP and remote MCP.
Choose the right tool
| Tool | Question | Limits/output |
|---|---|---|
| get_solver_capabilities | Is this state supported? | Catalog, validated mechanics, engine/rules identity and limits. Takes {}. |
| evaluate_hand | What does this chosen hand score? | 1–5 played cards; optimized score and hand type, no probability. |
| compare_actions | What plays or discards can I choose? | Immediate scores or exact small-deck action values, ties and draw proofs. |
| recommend_action | Which exact decision clears this target? | Exact supported model only; null unique recommendation when optimal actions tie. |
Versioned schemas and endpoint
Live MCP input schemas · Live capabilities · Build-time capability snapshot.
https://balatro.fantasysolvers.com/mcp
HTTP scoring request
curl https://balatro.fantasysolvers.com/api/v1/evaluate_hand \
-H 'Content-Type: application/json' \
-d '{"contract_version":"balatro-web-v1","played":["9H","9S"],"held":[],"jokers":[{"id":"joker","edition":"none"},{"id":"the_duo","edition":"none"}],"levels":{}}'Actual result: pair, 336 chips. Full response and reversed-rack comparison.
MCP request
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "evaluate_hand",
"arguments": {
"contract_version": "balatro-web-v1",
"played": [
"9H",
"9S"
],
"held": [],
"jokers": [
{
"id": "joker",
"edition": "none"
},
{
"id": "the_duo",
"edition": "none"
}
],
"levels": {}
}
}
}Initialize and negotiate MCP first. Supported transport versions: 2025-03-26, 2025-06-18 and 2025-11-25; stateless JSON responses, no legacy SSE subscriptions.
Decision request
{
"contract_version": "balatro-web-v1",
"state": {
"id": "worked-example",
"hand": [
"AH",
"KH",
"QH",
"JH",
"9H",
"9S",
"4C",
"2D"
],
"deck": [
"TH",
"9D",
"AS",
"KC",
"2S"
],
"hands_left": 1,
"discards_left": 1,
"chips_needed": 600,
"jokers": [],
"levels": {}
},
"explain_actions": [
{
"kind": "discard",
"cards": [
"2D",
"4C",
"9S",
"9H"
]
}
]
}POST to /api/v1/compare_actions, or pass the same arguments to the MCP tool. Full exact result and branch proof.
Errors, budgets and cancellation
Both channels share strict Rust validation: unknown rule-bearing fields, unsupported Jokers and conflicting modifiers are rejected with a path and message. Read complete/status before interpreting a result. Exact action values are limited to one million score calls and a 15-second wall limit; at most two native worker jobs run simultaneously. Busy, cancellation, timeout and budget exhaustion return no completed recommendation. POST /api/v1/cancel with contract_version and request_id to cancel an HTTP job.
Identity and assumptions
Every response identifies contract, engine, rules, build target, objective, assumptions and budget. Exactness concerns the supported model. Manually entered custom notes never alter rules. Directory publication and web indexing are independent; this endpoint must be deliberately connected in a compatible client.
Scope and trust
Supported model: 20 validated Jokers, 150 catalog names; exact analysis accepts 1–8 hand cards, 0–12 draw cards, 1–2 hands and 0–2 discards. Uniform replacement draws and optimal continuation are assumed. Unsupported boss, consumable, shop, history and scaling effects are rejected. No standalone sampled full-deck advice. Card order is optimized; Joker slot order is preserved.
Mathematical action values are conditional on the stated game model, not estimates of real-game success. Equal values are ties. Incomplete searches provide no completed recommendation. This independent tool is not affiliated with the game publisher.