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 from this player. Returns action_pending (boolean), and if true: action_type, game_id, and message.
No parameters.
wait_for_action
Block until a game action is required from this player, or until timeout. Returns the same info as is_action_on_me. Use this instead of polling is_action_on_me in a loop.
| Parameter | Type | Required | Description |
|---|---|---|---|
timeout_ms | integer | No | Max milliseconds to wait (default 15000) |
pass_priority
Auto-pass priority until you can actually do something. Skips empty priorities where you have no playable cards, and returns when: (1) you have cards you can play, or (2) a non-priority decision is needed (mulligan, target selection, etc.). Call this after making your play or passing to skip ahead efficiently. Returns action_pending, action_type, actions_passed (count of auto-passed priorities), and has_playable_cards (true if you have non-mana cards to play). 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 game actions (pass/default) and block until the game state changes meaningfully (turn change, life total change, permanents entering/leaving, cards going to graveyard). Returns event_occurred (boolean), new_log (description of changes), new_chars, and actions_taken (count). Use this in a loop to observe the game.
| 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 detailed information about the current pending action including all available choices with human-readable descriptions. Call this before choose_action to see what options are available. Always includes phase context: turn, phase, step, active_player, is_my_main_phase, players. Returns response_type: 'select' (GAME_SELECT: playable cards by index, pass with answer=false; GAME_PLAY_MANA: mana sources with choice_type 'tap_source'/'mana_source'/'pool_mana'), 'boolean' (yes/no; mulligan includes your_hand with card details), 'index' (target/ability/choice; target includes required and can_cancel), 'amount' (includes min/max), 'pile' (includes pile1/pile2 card names), or 'multi_amount' (includes items array with per-item min/max/default).
No parameters.
choose_action
Respond to the current pending action with a specific choice. Call get_action_choices first to see available options. For GAME_SELECT (response_type=select): 'index' to play a card, or 'answer: false' to pass priority. For GAME_PLAY_MANA: 'index' to tap a mana source or spend pool mana, 'answer: false' to cancel. For GAME_TARGET: 'index' to select target, 'answer: false' to cancel. For GAME_ASK: 'answer' true/false. For GAME_CHOOSE_ABILITY/CHOICE: 'index'. For GAME_GET_AMOUNT: 'amount'. For GAME_GET_MULTI_AMOUNT: 'amounts' array. For GAME_CHOOSE_PILE: 'pile' (1 or 2).
| Parameter | Type | Required | Description |
|---|---|---|---|
amount | integer | No | Amount value (for get_amount actions) |
answer | boolean | No | Yes/No response (for ask/select). 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 structured game state: turn, phase/step, active_player, priority_player, and stack. Each player has: name, life, library_size, hand_size, is_active, is_you, battlefield, graveyard, and optionally counters and commanders. Your hand includes card details with playable flag. Battlefield permanents include tapped state, types, power/toughness, loyalty, counters, and summoning_sickness.
No parameters.
get_game_log
Get the game log text. Returns log (string), total_length, returned_length, and truncated (boolean). If max_chars is set, returns the most recent max_chars characters.
| 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 a card by name or in-game object ID. Provide exactly one of card_name or object_id (not both). Returns success, source ('database' or 'game'), name, and rules. Database lookups also return set_code and card_number.
| Parameter | Type | Required | Description |
|---|---|---|---|
card_name | string | No | Card name for database lookup (e.g., 'Lightning Bolt') |
object_id | string | No | UUID of an in-game object for dynamic rules |
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