MCP Tools
The headless Java client exposes these tools via the Model Context Protocol over stdio. LLM players use them to observe game state and make decisions. This page is generated from the same schema the LLM clients use.
Game Flow
Tools for managing the action/priority loop.
is_action_on_me
Check if game action is currently required. Returns action_pending, and if true: action_type and message.
No parameters.
wait_for_action
Block until a game action is required, or timeout. Returns action_pending, action_type, message.
| Parameter | Type | Required | Description |
|---|---|---|---|
timeout_ms | integer | No | Max milliseconds to wait (default 15000) |
pass_priority
Auto-pass priority until you need to make a decision: playable cards, combat (declare attackers/blockers), or non-priority actions. Returns action_pending, action_type, actions_passed, has_playable_cards, combat_phase. On timeout: action_pending=false, timeout=true.
| Parameter | Type | Required | Description |
|---|---|---|---|
timeout_ms | integer | No | Max milliseconds to wait (default 30000) |
auto_pass_until_event
Auto-handle all actions and block until meaningful game state change. Returns event_occurred, new_log, actions_taken.
| Parameter | Type | Required | Description |
|---|---|---|---|
min_new_chars | integer | No | Min new log characters to trigger return (default 50) |
timeout_ms | integer | No | Max milliseconds to wait (default 10000) |
Actions
Tools for making game decisions.
take_action
Execute default action (pass priority or first available choice)
No parameters.
get_action_choices
Get available choices for the current pending action. Call before choose_action. Includes context (phase/turn) and players (life totals). response_type: select (cards to play, attackers, blockers), boolean (yes/no), index (target/ability), amount, pile, or multi_amount. During combat: combat_phase indicates declare_attackers or declare_blockers.
No parameters.
choose_action
Respond to pending action. Use index to pick a choice (card, attacker, blocker, target, ability, mana source). Use answer for yes/no, pass priority, or confirm combat (true=confirm attackers/blockers). Call get_action_choices first.
| Parameter | Type | Required | Description |
|---|---|---|---|
amount | integer | No | Amount value (for get_amount actions) |
answer | boolean | No | Yes/No response. For GAME_ASK: true means YES to the question, false means NO. For mulligan: true = YES MULLIGAN (discard hand, draw new cards), false = NO KEEP (keep this hand). For GAME_SELECT: false = pass priority (done playing cards this phase), true = confirm combat (done declaring attackers/blockers). Also false to cancel target/mana selection. |
amounts | array[integer] | No | Multiple amount values (for multi_amount actions) |
pile | integer | No | Pile number: 1 or 2 (for pile choices) |
index | integer | No | Choice index from get_action_choices (for target/ability/choice and mana source/pool choices) |
Game State
Tools for observing the game.
get_game_state
Get full game state: turn, phase, players, stack, combat. Each player has life, mana_pool, hand (yours only), battlefield (name, tapped, P/T, counters, token/copy/face_down flags), graveyard, exile, commanders.
No parameters.
get_game_log
Get game log text. Returns log, total_length, truncated. Use max_chars for recent entries only.
| Parameter | Type | Required | Description |
|---|---|---|---|
max_chars | integer | No | Max characters to return (0 or omit for all) |
get_oracle_text
Get oracle text (rules) for cards. Provide exactly one of: card_name (single), card_names (batch array), or object_id (in-game object). Single returns {name, rules}. Batch returns {cards: [{name, rules}, ...]}.
| Parameter | Type | Required | Description |
|---|---|---|---|
card_name | string | No | Single card name lookup |
card_names | array[string] | No | Batch card name lookup |
object_id | string | No | UUID of an in-game object |
Communication
Tools for interacting with other players.
send_chat_message
Send a chat message to the game
| Parameter | Type | Required | Description |
|---|---|---|---|
message | string | Yes | Message to send |
Source: McpServer.java