Aether

MCP Tools Reference

Complete reference for all Aether MCP tools available in Cursor and other MCP clients.

🤖🤖 Your Agent Knows All This

Once your Cursor MCP is connected, your agent has full access to this entire tools reference. You don't need to memorize these commands—just let your agent handle it! 👀

Overview

Aether exposes 7 MCP tools for querying Unity runtime state:

  • aether_snapshot - Get current game state
  • aether_tail - Stream recent events
  • aether_mark - Create a markpoint
  • aether_clip - Create a time-window clip
  • aether_getClip - Retrieve a marked clip
  • aether_package - Create a capsule
  • aether_viewCapsule - View a capsule
aether_snapshot
Free

Get current Unity state: selected object snapshot (if any), current scene/frame/time, last N events, last N console entries, optional UI focus summary. Returns surgical GTML snapshots for suspect objects (bounded: 25 components, 40 fields, depth 4).

Parameters

include_ui(boolean)

Include UI snapshot summary (default: true)

event_count(integer)

Number of recent events to include (default: 10, max: 50)

console_count(integer)

Number of recent console entries to include (default: 10, max: 50)

Example

cursor-chat
1@aether snapshot
ℹ️When to Use

Use aether_snapshot when you need to understand the current state of the game. Perfect for:

  • "What's the current game state?"
  • "What objects are active?"
  • "What happened recently?"
aether_tail
Free

What happened in the last N seconds? Returns events + console in window, top state changes (derived diff using fingerprints, not full structural diff), and notable objects touched (instance_ids).

Parameters

seconds(number)

Time window in seconds (default: 10, max: 60)

include_changes(boolean)

Include top state changes summary (default: true)

max_events(integer)

Maximum events to return (default: 50, max: 200)

Example

cursor-chat
1@aether tail 30
ℹ️When to Use

Use aether_tail to see what happened recently. Perfect for:

  • "What happened in the last 10 seconds?"
  • "Show me recent events"
  • "What changed recently?"
aether_mark
Free

Save this moment. Persists last context_seconds (+ optionally next post_seconds if arming). Returns clip_id. Can be used to arm capture for next exception/probe failure.

Parameters

label(string)

Optional label for the clip

context_seconds(number)

Seconds of context to capture before this moment (default: 10)

post_seconds(number)

Seconds to capture after this moment if arming (default: 0, no arming)

arm_until_trigger(boolean)

If true, arm capture until next exception/probe failure (default: false)

include_screenshot(boolean)

Include screenshot in clip (default: false)

Example

cursor-chat
1@aether mark "Player clicked button"
ℹ️When to Use

Use aether_mark to save important moments. Perfect for:

  • "Mark this moment for later analysis"
  • "Save state before this action"
  • "Arm capture for next error"
aether_clip
Free

Create a clip from a time window. Captures events in the specified time range around the current moment.

Parameters

seconds_before(number)

Seconds of history to capture (default: 10)

seconds_after(number)

Seconds to capture after current moment (default: 5)

Example

cursor-chat
1@aether clip 20 5
ℹ️When to Use

Use aether_clip to capture a specific time window. Perfect for:

  • "Capture the last 20 seconds"
  • "Get events around this moment"
aether_getClip
Free

Replay the evidence from a marked clip. Returns same payload as aether_tail but for the clip window, including top changes in that clip window.

Parameters

clip_id(string)
Required

The clip ID (e.g. 'clip_a1b2c3d4')

include_changes(boolean)

Include top state changes summary (default: true)

Example

cursor-chat
1@aether getClip clip_a1b2c3d4
ℹ️When to Use

Use aether_getClip to retrieve a previously marked clip. Perfect for:

  • "Show me what happened in that clip"
  • "Replay the marked moment"
aether_package
Pro

Create a Capsule for the last crash/error/mark: timeline + key errors + minimal context. Pro adds ranked suspects, source links, and richer compression.

Parameters

target(string)
Required

Target to package: 'last_crash', 'last_error', 'last_mark', or 'session'

session_id(string)

Session ID (required if target is 'session')

window_seconds(number)

Time window in seconds (default: 60, only for 'session' target)

Example

cursor-chat
1@aether package last_error
ℹ️When to Use

Use aether_package to create a capsule for analysis. Perfect for:

  • "Package the last error"
  • "Create a capsule from the last mark"
  • "Package this session"
⚠️Pro Feature

Pro tier adds ranked suspects, source links, and richer compression to capsules.

aether_viewCapsule
Free

View the last generated capsule. Returns capsule metadata, file path, and viewer URL. Use after aether_package to inspect results.

Parameters

capsule_id(string)

Optional specific capsule ID to view. If omitted, shows the last capsule.

Example

cursor-chat
1@aether viewCapsule
ℹ️When to Use

Use aether_viewCapsule after creating a capsule to view it. Perfect for:

  • "Show me the capsule I just created"
  • "View capsule analysis"

Usage Patterns

Debugging Workflow

  1. Snapshot - Get current state: @aether snapshot
  2. Tail - See recent events: @aether tail 30
  3. Mark - Save important moment: @aether mark "Before fix"
  4. Package - Create capsule: @aether package last_mark
  5. View - Inspect capsule: @aether viewCapsule

Error Investigation

  1. Package Error - @aether package last_error
  2. View Capsule - @aether viewCapsule
  3. Analyze - Review capsule contents and suspects (Pro)

Performance Analysis

  1. Mark - @aether mark "Performance spike"
  2. Tail - @aether tail 10 to see events
  3. Package - @aether package last_mark

Response Format

All tools return JSON-RPC 2.0 responses with:

  • Success: { "jsonrpc": "2.0", "id": 1, "result": {...} }
  • Error: { "jsonrpc": "2.0", "id": 1, "error": {...} }

Results contain GTML-formatted data for AI consumption.

Best Practices

  1. Use Snapshots Sparingly: They're comprehensive but can be large
  2. Mark Before Fixes: Save state before attempting changes
  3. Package Errors Immediately: Create capsules right after errors occur
  4. Leverage Pro Features: Use suspect analysis for faster debugging

Next Steps

PreviousGTML
NextRecipes