switch_start_session

Initialize debugging for Nintendo Switch executables by connecting to the GDB stub, loading debug commands, and setting up the game's base address automatically.

Instructions

Start gdb-multiarch and connect to the Switch/Yuzu GDB stub. This MUST be called before any other tool. Connects to the IP/port configured via SWITCH_IP and SWITCH_PORT environment variables (defaults: 192.168.1.235:22225). Automatically loads Switch debug commands, attaches to the game, and sets $main to the base address of cross2_Release.nss. Do NOT manually run 'target remote', 'attach', or 'set $main' — this tool handles all of that.

Input Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Implementation Reference

src/gdb_multiarch_mcp/server.py:71-99 (handler)

The _start_session function implements the logic to initialize the GDB session, deploy necessary scripts, and connect to the target.

def _start_session() -> dict:
    """
    Start a gdb-multiarch session and connect to Yuzu.

    Uses DEFAULT_SWITCH_IP:DEFAULT_SWITCH_PORT, sources the Switch gdbinit
    commands, runs attach.py to auto-attach and set $main.
    """
    global _session
    with _session_lock:
        if _session is not None and _session.is_running:
            return {"status": "error", "message": "Session already running. Stop it first."}

        scripts_dir = _deploy_scripts()

        _session = GDBSession()
        init_cmds = [
            f"source {scripts_dir}/gdbinit_switch",
            f"target extended-remote {DEFAULT_SWITCH_IP}:{DEFAULT_SWITCH_PORT}",
            f"source {scripts_dir}/attach.py",
        ]

        result = _session.start(init_commands=init_cmds)

        if result.get("status") == "error":
            logger.error(f"Start failed: {result.get('message')}")
            _session = None

        return result

src/gdb_multiarch_mcp/server.py:208-221 (registration)

Tool definition and registration for 'switch_start_session' in the list_tools method.

Tool(
    name="switch_start_session",
    description=(
        "Start gdb-multiarch and connect to the Switch/Yuzu GDB stub. "
        "This MUST be called before any other tool. "
        "Connects to the IP/port configured via SWITCH_IP and SWITCH_PORT "
        "environment variables (defaults: 192.168.1.235:22225). "
        "Automatically loads Switch debug commands, attaches to the game, "
        "and sets $main to the base address of cross2_Release.nss. "
        "Do NOT manually run 'target remote', 'attach', or 'set $main' — "
        "this tool handles all of that."
    ),
    inputSchema=NO_ARGS_SCHEMA,
),

src/gdb_multiarch_mcp/server.py:439-440 (handler)
Dispatch logic in the call_tool function that routes the 'switch_start_session' tool call to the _start_session handler.
```
if name == "switch_start_session":
    result = _start_session()
```

gdb-multiarch-mcp