AI Agents & MCP

The remoterf client package includes a local Model Context Protocol (MCP) server (remoterf mcp), installable Agent Skills (remoterf skill install), and a non-interactive JSON CLI for AI coding assistants such as Claude, Codex, and Gemini.

AI Agent
Is there a USRP free at UCLA right now?
Yes, USRP_00@ucla, USRP_01@ucla, and USRP_02@ucla are online and open for the 2:00–2:30 PM slot. Should I reserve USRP_00@ucla?
Yes, go ahead.
Done, USRP_00@ucla is reserved until 2:30 PM. Want me to generate a starter script?
Sure
Created main.py for USRP_00@ucla that receives a signal and plots its spectrum. Ready to run whenever you are.

Overview

When connected to your local remoterf installation, an AI assistant can:

  • Inspect available hardware: Check which radios are online across your enrolled deployments and find open reservation slots.
  • Query live device APIs: Fetch the exact Python import statement, constructor, properties, and methods from a deployment’s Interface Description Language (IDL) schema for any handle (such as USRP_00@ucla) without needing an active reservation.
  • Generate starter scripts: Produce ready-to-run receive and spectrum scripts tailored to a specific device handle.
  • Reserve and release slots with confirmation: Book or cancel reservations after asking for your confirmation in chat.

Setting Up MCP & Agent Skills

1. Log In Once on Your Machine

Log in once from your terminal; MCP tools and CLI subcommands reuse your saved session without prompting for a password:

remoterf --login
# Or non-interactively:
printf '%s\n' "$REMOTERF_PASSWORD" | remoterf auth login --user YOUR_USERNAME --password-stdin --accept-tos
remoterf auth status --json

2. Install MCP Support & Register the Server

Install the optional mcp extras and register the local stdio MCP server with your coding assistant:

pip install "remoterf[mcp]"

# Register with your assistant (--print previews the config without writing):
remoterf mcp install --claude-code
remoterf mcp install --claude-desktop
remoterf mcp install --cursor
remoterf mcp install --gemini
remoterf mcp install --codex

By default, remoterf mcp runs in read-only mode (allowing device discovery, slot searches, and API inspection). To let the assistant also reserve or cancel time slots after your confirmation (remoterf_reserve and remoterf_cancel), enable it once in ~/.config/remoterf-client/.env:

mkdir -p ~/.config/remoterf-client
echo "REMOTERF_MCP_ALLOW_RESERVE=true" >> ~/.config/remoterf-client/.env

(Alternatively, you can add "--allow-reserve" to "args": ["mcp", "--allow-reserve"] in your assistant’s MCP config file.)

3. Install the RemoteRF Agent Skill

Install the bundled RemoteRF skill so your assistant knows device handle conventions, driver imports, error codes, and how to prevent unintended auto-reservations (REMOTERF_AUTO_RESERVE=0):

remoterf skill install --claude      # writes ~/.claude/skills/remoterf/SKILL.md
remoterf skill install --gemini      # updates ~/.gemini/GEMINI.md
remoterf skill install --codex       # updates ~/.codex/AGENTS.md
remoterf skill install --agents-md   # updates ./AGENTS.md in the current project

MCP Tools, Resources & Prompts

The remoterf mcp server exposes nine tools, three resource URI templates, and two workflow prompts:

MCP Tool Mode Description
remoterf_whoami Read Returns the logged-in account, home deployment, connected deployments, client version, and whether reserve/cancel are enabled.
remoterf_list_devices Read Lists radios by handle (Name@deployment) with device type, online status, availability state (free, busy, mine), slot_minutes, and max_days_ahead.
remoterf_find_slots Read Finds free, midnight-aligned reservation blocks for a specific device handle over the next N days.
remoterf_list_reservations Read Lists active and upcoming reservations with reservation_id, handle, device, deployment, start/end timestamps, and ownership.
remoterf_device_api Read Returns the exact Python import statement, class name, constructor, and exposed methods/properties from the deployment's IDL.
remoterf_example_script Read Generates a runnable receive starter script (connect, rx_once, or rx_spectrum) for a given device handle.
remoterf_guide Read Retrieves the RemoteRF agent guide or a specific section (workflow, python, tokens, cli, mcp, safety, errors).
remoterf_reserve Write Reserves [start, end) on a handle after explicit user confirmation in the conversation, returning reservation_id and use_as_token.
remoterf_cancel Write Cancels an active or future reservation by reservation_id after explicit user confirmation.
  • MCP Resources: remoterf://guide, remoterf://devices/{handle}/api, and remoterf://docs/{page}
  • MCP Prompts: reserve-and-receive and explain-my-reservations

Agent Workflow

  1. Step 1

    Discover Hardware & Free Slots

    Ask your assistant to set up or run an experiment (for example, "Capture a spectrum snapshot at 915 MHz on an available Pluto at UCLA"). The assistant lists online devices, picks a free handle such as Pluto_00@ucla, and finds the next available time slot.

  2. Step 2

    Confirm & Reserve

    The assistant shows you the device handle and time window and waits for your confirmation before calling remoterf_reserve. Once confirmed, it records the reservation_id.

  3. Step 3

    Inspect API & Run Script

    The assistant checks remoterf_device_api, writes a Python script using the device handle (e.g., Pluto_00@ucla), runs it locally during the reserved window, and processes the captured IQ data.

  4. Step 4

    Release Early When Done

    When you finish early, the assistant asks if you want to cancel the remaining slot time via remoterf_cancel so the radio is freed for other users.

Non-Interactive JSON CLI

For coding assistants or scripts that run shell commands directly without MCP, every remoterf subcommand supports --json. JSON output is written to stdout (with both RFC 3339 UTC strings and _ts epoch seconds), human messages go to stderr, and --confirm is required on state-changing commands:

# 1. Check login status and list online devices
remoterf auth status --json
remoterf devices --json

# 2. Find aligned free slots for a specific device handle
remoterf slots Pluto_00@ucla --days 1 --json

# 3. Reserve a slot (after user confirmation) and inspect device API
remoterf reserve Pluto_00@ucla --start 2026-10-31T19:00:00Z --end 2026-10-31T19:30:00Z --confirm --json
remoterf api Pluto_00@ucla --json

# 4. Generate a starter script and run it
remoterf example Pluto_00@ucla --recipe rx_spectrum -o rx_spectrum.py
REMOTERF_AUTO_RESERVE=0 python rx_spectrum.py

# 5. Cancel when done early
remoterf cancel RESERVATION_ID --confirm --json

Safety & Token Rules

  • User confirmation before booking: Assistants ask for your confirmation before calling remoterf_reserve, remoterf_cancel, or running a script without REMOTERF_AUTO_RESERVE=0.
  • Handles instead of raw tokens in code: Generated scripts use os.environ.get("REMOTERF_TOKEN", "Pluto_00@ucla") so raw one-time bearer tokens are not hardcoded in source files or chat history.
  • Server-enforced safeguards: Just like standard RemoteRF usage, every command is validated by the deployment server against configured frequency, sample rate, and gain limits, as well as any active lockouts. AI agents cannot bypass these safeguards.
  • Buffer cleanup: Scripts should release transmit and receive buffers (tx_destroy_buffer(), rx_destroy_buffer()) or close the device in a finally: block when finished.

Next Steps