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.
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?
USRP_00@ucla is reserved until 2:30 PM. Want me to generate a starter script?
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 --json2. 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 --codexBy 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 projectMCP 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, andremoterf://docs/{page} - MCP Prompts:
reserve-and-receiveandexplain-my-reservations
Agent Workflow
-
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. -
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 thereservation_id. -
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. -
Step 4
Release Early When Done
When you finish early, the assistant asks if you want to cancel the remaining slot time via
remoterf_cancelso 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 --jsonSafety & Token Rules
- User confirmation before booking: Assistants ask for your confirmation before calling
remoterf_reserve,remoterf_cancel, or running a script withoutREMOTERF_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 afinally:block when finished.