NXS — MCP Tool Reference
Applies to: NXS SDK 1.1.x · nxs mcp · the mcp extra · Model Context Protocol (stdio)
| Document set | |
|---|---|
| Glossary | one word for each thing |
| Technical Specifications | capability summary tables |
| Device Reference | interfaces, performance and limits, shipped personalities, versioning |
| Interface Description | transports, register map, commands, procedures |
| Integration & Operation Manual | design-in, host setup, workflows |
| Click Personality Reference | authoring personalities for unsupported sensors |
| Cam Personality Reference | describing camera chains for the camera ports |
| MCP Tool Reference (this document) | operating and configuring through an AI agent |
1. Overview
Section titled “1. Overview”nxs mcp serves the nxs verbs to an AI agent as tools. The agent calls on, capture, set, status. Each tool runs the same command line an operator types. The agent gets the same words, the same refusals, the same laws.
The machine’s declaration is suite.yaml. It has three doors:
| Door | Who | How values are chosen |
|---|---|---|
| The file | an engineer with an editor | typed, and the shipped JSON Schema flags shape errors in the editor |
nxs tune | an operator at the terminal | picked from offered options only |
nxs mcp | an agent | picked from offered options only (suite_get, suite_set) |
All three are judged by the same findings, the ones a bare nxs status prints under declaration:. switch converges the units to the file, and nxsd the ports. A value the hardware cannot do is refused on every door. The refusal names the lawful values. Nothing is clamped silently.
MCP operates the hardware as well as the declaration. nxs tune reaches the hardware too: --play signals nxsd, and i in the panel strobes a unit’s LED. on writes registers, and power-dips a port’s camera heads when a link does not lock.
The agent must read before it writes. caps says what a sensor offers. status without a port says whether the declaration is lawful and which declared nodes answer. status with a port says what the hardware is doing now.
The server runs on the machine that owns the buses. An agent elsewhere reaches it over ssh.
2. Installation
Section titled “2. Installation”On the Jetson (or any host with the buses):
orin$ pipx inject aliensense-nxs 'aliensense-nxs[mcp]'orin$ nxs mcp --doc-tableThe second command prints the Tools table of §3 and exits. It proves the extra is installed. Without it, nxs mcp says so and exits.
Claude Code on a workstation, reaching the Jetson over ssh (key-based login, the Jetson user in the i2c and video groups). An ssh command runs no login profile, so name the user install’s executable by its path, quoted so the Jetson expands $HOME, not the workstation:
host$ claude mcp add nxs -- ssh <user>@<jetson> '$HOME/.local/bin/nxs' mcpClaude Desktop, in its MCP configuration file:
{ "mcpServers": { "nxs": {"command": "ssh", "args": ["<user>@<jetson>", "$HOME/.local/bin/nxs", "mcp"]} }}An agent on the Jetson itself uses "command": "nxs", "args": ["mcp"].
Smoke test from the client: list the tools. 20 names appear, in the order of §3. Then call status with no port. Its declaration carries in_tune: true or the findings, and each declared node its presence. The buses are read and nothing is written.
3. Tools
Section titled “3. Tools”| Tool | Purpose | Arguments | Hardware effect | Refuses when |
|---|---|---|---|---|
probe | the units that answer, on every bus or a port’s | port?, link? | none (reads identity registers) | no ACK rows, or an unknown port, which lists the ports |
generate | the rig as it answers: ports, hubs, links, sensors, units | dry_run? | walks every camera port and bus. With dry_run false it writes hardware.yaml, the report of what answered, and seeds suite.yaml when there is none. It writes a declaration of api 2 or the 1.0 form again in api 3, the earlier file kept beside it. A unit on a bare bus running nothing is named by trying every personality on it | no hub and no camera port, or the wiring file is not writable |
status | the declaration against the rig, or a port’s presence and health | port?, link? | none (reads identity and status registers) | hub does not answer |
identify | strobe a unit’s LED to find the box | unit? | the unit’s LED strobes ~10 s | unit does not answer |
samples | read decoded samples from a unit | unit?, count? | reads the sample window. Over Cyphal it sets the output decimation for the read and puts the previous value back | no personality measuring, or the unit does not answer |
caps | what the sensor offers, with the laws | port, link? | none (reads facts) | no hub serves the port, or nothing installed describes its sensor |
on | bring a link or the whole port up | port, link?, sensor?, mode?, fps?, dry_run? | writes the program, trains links, follows video lock, counts two seconds of frames on every camera link | the laws refuse the mode or rate, the hub does not answer, video did not lock, or the links do not deliver the rate |
off | park the whole port | port | bare heads to standby, CSI gate closed, viewers stopped, each pod’s head parked by its unit | kernel-owned hub |
capture | headless delivery proof | port, link, frames?, timeout_s? | opens a capture session on the up link, the tool’s viewer on it stopped first | the link is not up, or the frames were not delivered |
get | read a knob: the port’s sync, the sensor’s, the unit’s | port, link, knob | none (reads a row of the map, a bare head’s registers or the unit’s parameter) | unknown knob lists the knobs |
set | change a knob under the laws, sync being the port’s frame sync | port, link?, knob, value, dry_run?, fps?, exposure_us? | a row’s commit on a pod’s or smart camera’s map, a bare head’s registers, or the link’s unit for its personality’s parameter. Sync starts or stops the hub’s generator, and a sync or fps change counts two seconds of frames | an unlawful value, with the lawful alternatives. A sync or rate the links do not deliver, the previous one restored. A live sibling link, for a bare head’s camera knob. The port is not up |
suite_get | the declaration as options | — | none | no camera port on the host and no declaration |
suite_schema | each node’s rows on this rig as JSON Schema | — | none | the declaration does not parse |
suite_set | set declared values from their options, one or a batch | channel?, field?, value?, section?, sets? | writes suite.yaml once (a timestamped backup, created when absent) | a value not among the options, a field that repeats without its section, or a knob a set moved that the batch does not name |
switch | apply the saved declaration to the units | dry_run?, accept_new_serial? | retunes or re-uploads the personality on units whose entry differs | the declaration is out of tune, or a declared unit does not answer |
reload | apply the saved declaration to the ports | — | nxsd reconverges changed ports | the declaration is out of tune, or nxsd is not running |
freeze | adopt live tuning into the declaration: the units’, or the camera ports’ | unit?, ports?, port?, dry_run? | writes suite.yaml | unit unreachable, or a port no host bus answers to |
upload | compile and upload a personality to a unit (or compile only) | name, port?, link?, unit?, params?, slot?, compile_only? | a click personality runs, and a cam personality lands in a store slot | an unknown name, a source that does not compile, a full store, or several units that answer with none named |
host_info | the capture host and what it booted | — | none (reads the device tree and boot config) | never |
host_modes | the booted capture table of a port | port | none (reads the device tree) | an unknown port, or a silent device tree |
Arguments marked ? are optional. fps is the rate set runs the port’s frame sync at (knob: sync, value: fsync). Without it the declared rate applies, else 30 fps. exposure_us is refused with the fact that sets the exposure. Under frame sync that is the trigger pulse’s low time at the rate, in free run the capture stack’s loop.
port is a port name (cam1). link is a link name (A, B). knob names come from caps. channel, section, and field come from suite_get.
On a pod’s link and on a smart camera, a camera knob is a row of the map (Interface Description §4.5). caps lists those rows, set commits a row by its name in the row’s unit, and get reads the row’s value in effect. A value past a range row’s bounds commits at the bound, and the output names the value in effect and the one asked. On a head with no unit that is not a smart camera, set writes the sensor’s registers. A knob the camera does not have goes to the link’s unit as its personality’s parameter.
unit is the name of a unit node in the declaration. When it is omitted, identify and samples address the one unit answering on the host’s camera buses. So a unit can be found and read before it is declared.
Read tools return the same JSON the command line prints with --json: probe, generate, status, samples, caps, suite_get, suite_set, reload. Every such document carries contract: 2, and the SDK’s tests validate every surface against the shipped surface schema. suite_schema returns the rig schema itself, a JSON Schema document with no contract member. Live tools return the verb’s text.
A refused call is a tool error. Its text is the verb’s refusal: the fact on one line, then one line per lawful alternative. A JSON tool’s refusal is the document {"refused": {"fact": …, "alternatives": […]}}, so a program reads the alternatives without parsing a sentence. The agent asks for one of them.
A finding in a status document has the same parts. where is the node path it names, such as nodes.hub-cam0.parameters.sync_source, and text is the sentence the command line prints, beside fact and alternatives. A bare status document also carries the declaration’s graph: each node with its state, present, absent or unknown, and each connection as from and to. The graph definition of the shipped surface schema states its shape.
3.1 Schemas and refusals
Section titled “3.1 Schemas and refusals”Each format has one role. The declaration file is YAML, because a person edits it. Every tool result and every --json document is JSON. The contract between them is JSON Schema 2020-12. The shipped suite schema covers the file, the surface schema the results, and the rig schema that suite_schema returns covers one rig. A declaration rendered as JSON loads and validates identically, so an agent may write either.
A declaration carries api: 3, its nodes by name and its connections. A node is a type and its parameters, the rows of its block by name in display form and its identity pins. A connection is keyed by the port that feeds, <node>.<port>, and lists the ports it feeds (Integration & Operation Manual §5.1).
The rig schema is the declaration schema narrowed by the nodes on this rig. Each declared node’s type is a constant. Its parameters admit its identity pins and the rows its block offers at its place in the graph, with the values each takes there. A row the block does not offer there is left out:
- A hub’s rows follow its frame sync:
sync_fpsunderfsyncwhere the trigger laws leave a rate, andexposurein free run. Itscsi_a_lanestakes the lanes the host’s connector takes. - A camera’s
modenames the modes its program carries, and itsfpsspans the rates its mode runs free at on its port. Under frame sync it has nofps. - A click’s rows are its personality’s, and a host’s are its connectors’ lanes and drivers.
- A unit’s own rows are integers, judged where the unit answers.
A violation names the key it broke and the values that key admits.
The schema is necessary and not sufficient. It judges names and values one node at a time. The loader holds the connections’ laws. status judges what spans nodes, such as two cameras on one port or the lanes against the hub’s output.
Findings and refusals follow the shape of the Linux kernel’s netlink extended ACK. That ACK carries the message, the offset of the invalid attribute, and the policy for a rejected attribute: here fact, where, and alternatives. suite_schema is the counterpart of netlink’s policy dump, which gives the supported attributes with the ranges of values the kernel accepts (netlink introduction).
4. Workflows
Section titled “4. Workflows”4.1 Declare first
Section titled “4.1 Declare first”Edit the declaration, validate it, apply it.
- Call
suite_get: every channel, its fields, the values each may take. - Call
suite_setwithchannel: cam1/A,field: fpsandvalue: 25, a rate the knob offers. A batch goes insets(cam1:HUB=maxim,max96792a,cam1/A:CAM=framos,imx900), applied in order. It writes the declaration once, in api 3 with a timestamped backup, and the result carries the findings. - Call
statuswith no port. It answersdeclaration.in_tune: true, or findings that name the lawful alternatives, each under the node it concerns. - Call
switch: it retunes or re-uploads every declared unit whose personality or settings differ from its entry. It leaves a matching unit alone. Callreload:nxsdreconverges only the ports whose declaration changed. It also reconverges the ports a by-handonbrought up away from theirs.
A stream on an untouched port keeps running. A changed rate, or a mode of another bit depth, moves the port’s boot table. switch then installs the port’s overlay and ends with REBOOT NEEDED, and the port runs the new declaration once the operator reboots. A frame-sync rate is counted on the running port first, and one the links do not deliver is refused before the table.
A field name that exists in two sections of a channel (two personalities on one unit carry sample_rate) is refused. Pass section with the section’s label (imu-a/iam20680). A set that moves another knob (a mode whose rate the laws pull) is refused unless the batch names that knob after it.
A channel with declared: false is a port the platform names, or a unit that answered with no node in the declaration yet. presence says whether a hub or a unit answers on it. Its DECLARE section carries the knobs that write its nodes. A port carries HUB: an installed hub, or connector for a camera wired to the host’s connector. Each of its links (the channel cam1/A) carries CAM and POD. A unit or a pod carries one CLICK knob per click node on its socket, CLICK, then CLICK-2.
suite_set on those knobs declares the nodes and their connections, and creates the declaration when absent. Each block the knobs declare opens its rows section on the next suite_get. That is the port’s hub and host, the link’s camera, a click’s <unit>/<personality> and the unit’s own. A section’s kind is declare for the knobs that write nodes and rows for a block’s rows.
A rows section’s fields are the block’s rows by name. A value is the row’s display form: a name such as fsync, or a number in the row’s unit, 12 for a gain in dB. A row the block does not offer at that point is absent, such as the hub’s sync_fps in free run.
4.2 Tune live, then freeze
Section titled “4.2 Tune live, then freeze”Change values on the hardware, verify, then write what works into the declaration.
- Call
onwithport: cam1,link: A. The link comes up. The result readsvideo locked, and the delivery check that counted two seconds of its frames,cam1: verified 30.0 fps (A 30.0). - Call
setwithknob: exposure,value: 8ms, applied under the sensor’s laws. - Call
capturewithframes: 1700: sixty seconds of frames must arrive.oncounted two seconds of frames, and this count proves the stream holds for a minute. A locked link proves nothing. - Call
freeze: the units’ live parameters become their click nodes’ parameters. It leaves a camera’s exposure alone. In free run the capture stack’s loop sets it, unless the hub node declaresexposurewithgain.
4.3 Verify a capture
Section titled “4.3 Verify a capture”capture opens a headless Argus session with the CSI-gate choreography the viewers use. Four frames prove the path. 1700 frames (~60 s) is the steadiness oracle. The result names delivered frames against requested ones.
on, set sync and set fps count two seconds of frames on the links they change. status with the port carries the last count that passed as verified. On a frame-synced pair ae names who decides the gain. When nxsd copies no gain for a followed pair (ae.mode: follow, ae.following: false), status fails. The tool error carries the document, and sudo systemctl restart nxsd brings the follower back.
4.4 Recover a link
Section titled “4.4 Recover a link”After a pulled cable or a head holding stale state the video does not lock. on recovers once by itself: it power-dips the heads on that port, resets and retrains them, then follows video lock again. A running stream on the sibling link stops. When on still ends with video did not lock, check the cabling and call on again.
4.5 A new sensor
Section titled “4.5 A new sensor”- Call
host_modeswithport: cam1: the booted capture table. The capture stack cannot capture a sensor mode missing here yet. - Call
switchto realize the declaration. When the booted table lacks a declared mode, it generates the port’s overlay. The sources are the hub directory and the installed cam personalities, and the overlay goes under thealiensense_genboot label. The result ends withREBOOT NEEDED, and nothing reboots. The operator reboots. - Call
onwithport: cam1,link: A,sensor: imx335: the link with that sensor. The port remembers the sensor, and later calls omit it.onstops withREBOOT NEEDEDwhen the booted table lacks the mode and has installed the overlays itself. - Call
capturewithport: cam1,link: A,frames: 60to prove delivery at the declared rate through the capture stack.statusis the verdict, declared against actual.
4.6 Validate a declaration before writing it
Section titled “4.6 Validate a declaration before writing it”A whole declaration, written by an agent or pushed from a fleet server, is checked against the rig’s own rules before it reaches the file.
- Call
suite_schema: the rig’s rules as JSON Schema (§3.1). - Check the declaration against it locally, with any JSON Schema 2020-12 validator. A violation names the key and the values it admits. Take one of them.
- Call
suite_setwith the knobs insets, saved once, or write the file for a whole declaration. - Call
statuswith no port: the findings the schema cannot see, each withwhere,fact, andalternatives.declaration.in_tune: trueis the pass. - Call
switchfor the units,reloadfor the ports.
The schema stops a wrong name or an out-of-range value before anything is written. It approves no arithmetic across nodes, so step 4 is never skipped.
4.7 Discover the rig
Section titled “4.7 Discover the rig”- Call
generatewithdry_run: true, the default. It lists every camera port with the nodes that answered on it (the hub, each link’s serializer, sensor, and unit). After the ports come the units on the bare buses. It writes nothing. Over a declaration of an earlier language, the 1.0 form or api 2, the dry run refuses and namesnxs generate. - Read
unanswered. A port carries it when the wiring or the platform names a hub and nothing answers at its address. That hub stays out ofhardware.yaml. With its power and cabling checked, callgenerateagain. - Call
generatewithdry_run: false. It writeshardware.yamlfrom the walk, a report that no verb reads, and seedssuite.yamlwhen there is none. It writes an earlier declaration again in api 3, the earlier file kept assuite.yaml.1.0orsuite.yaml.api2. It names a unit on a bare bus running nothing by trying every personality on it.hardware,seeded,keptandmigratedin the result say what it wrote.undeclaredlists the ports where a Hub, head or unit answered and a kept declaration does not name. - Call
statuswith no port: the declaration against what answered.
A declared hub that does not answer is a finding in step 4: cam1: the hub does not answer at 0x6a, with the power and cabling check as the alternative. A type nothing installed describes is refused when the declaration loads, with nxs describe <type> and nxs personality install <directory> among the alternatives.
5. Safety and limits
Section titled “5. Safety and limits”- Refusals are results.
onwithfps: 500answerslink A: 500 fps is outside 1920x1080 RAW10's 1.50–160.49 fps (the datasheet frame law's range with 1 camera on 2 CSI lanes)and names the whole rates at the ends,fps 160andfps 2, as its alternatives. The agent asks for a rate inside the range. Retrying 500 gets the same answer. A rate inside the range that the rig does not deliver is refused the same way, afteronorsetcounts two seconds of frames. The answer iscam0: 60 fps asked, 58.1 delivered on A, 57.9 on B, naming the whole rate at or under the lowest. - Register-level access does not exist. No tool writes a named register. Every write goes through a declared knob or a captured program.
- Live siblings are protected. On a bare head
seton one link refuses while the other link streams, because isolating a link’s control window would drop the sibling’s video. Park first (off), or set beforeon. A pod’s or a smart camera’s knob commits on its camera door and selects no window, so the other link keeps streaming. A unit’s parameter (a Click’s rate) is no camera knob:setwrites it to the link’s unit and parks nothing. on’s recovery is destructive on purpose. When video does not lock it power-dips every head on the port. Nothing else does.- A hub this host does not run is read-only. With the host’s row
<connector>_driver: kernel,on,offandsetrefuse, andstatusanswers from directly readable registers. On a passive host, where a module owns the Hub, they refuse the same way. - A hub change keeps the cameras. Every hub offers every installed cam personality, so a port whose hub changes keeps its camera nodes. A sensor no installed cam personality describes is not among the options. A sensor set on a port with no hub is refused with
set cam1:HUB first, in the same --set batch or before.setscarries both in one call, the hub first:cam1:HUB=…, thencam1/A:CAM=…. - The declaration is optional. Ports resolve from the platform (udev aliases, the mux channel ids).
reloadandfreezeneed a declaration, andswitchwithout one runs the host’s steps alone. On a host that boots no camera bus it installs the boot table that starts them and endsREBOOT NEEDED, else it namesnxs generate.suite_getlists the platform’s ports and what answered without one,suite_setdeclares into one, and the live tools never read it. - An earlier declaration is refused. Every tool that reads the declaration refuses one of the 1.0 form or api 2 and names
nxs generate.generatewithdry_run: falsewrites it again in api 3 and keeps the earlier file beside it,suite.yaml.1.0orsuite.yaml.api2. switchwrites/boot. On a host that boots no camera bus it writes the camera kernel package’s multiplexer overlay into one boot label (aliensense_gen). When the booted table lacks a declared mode, or its rows miss the declared rate and bit depth, the generated overlay goes in too. It copies that overlay into/boot/camera-dtbos, adds it to the same label and backs upextlinux.conf. The operator’s own labels are untouched, and nothing reboots.- Time.
ontakes seconds to a minute (training).capturewith 1700 frames takes about a minute.onwith a recovery takes up to several minutes. The server applies a timeout per tool and reports it as a refusal.
6. Troubleshooting
Section titled “6. Troubleshooting”| Symptom | Cause | Action |
|---|---|---|
nxs mcp needs: pipx inject aliensense-nxs 'aliensense-nxs[mcp]' | the mcp package is not installed | run the line the message names. In an environment pip made, it names pip install 'aliensense-nxs[mcp]' |
on answers REBOOT NEEDED | the booted capture table lacks the sensor mode, and switch regenerated and installed the overlay | reboot the Jetson, then call on again |
on answers <port>/<link>: … boots on no row of this port's table (…) | the mode is of another pixel format than the port’s declaration runs, so its table carries no row for it | declare the mode on every camera node of the port (nodes.<camera>.parameters.mode) and call switch, or call on with a mode the answer names |
on answers MISMATCH: declared …, answers as … | another sensor sits behind the link | call on with the detected sensor, or fix the camera node’s type |
the client lists no tools, or Connection closed at initialize | the server did not start: ssh asked for a password, or the client launched ssh with a minimal environment that hides the key agent (SSH_AUTH_SOCK) | run the ssh command by hand. Use the dedicated key the deploy guide restricts to the server, named by IdentityFile in ~/.ssh/config, or hand the agent through in the client’s env. Claude Desktop passes no agent socket |
hub … does not answer | deserializer unpowered, wrong bus, wrong module SKU in the boot config | probe without a port, and DEPLOY.md §2 of the camera kernel package |
capture fails, Failed to create CaptureSession | nvargus-daemon wedged by an earlier raw session | sudo systemctl restart nvargus-daemon, and capture restarts it once by itself |
video did not lock after on | a head holding stale state | on recovers once by itself. Check the cabling, then on again (§4.4) |
suite_set refuses ambiguous | two sections of the channel carry the field | pass section |
suite_set refuses … — name the knob in the same --set batch | a set moved a dependent knob (a mode change pulled the rate) | add the moved knob to sets after the set that moved it |
a tool refuses <path>: declares the 1.0 form (ports and units), and this nxs reads api 3, or <path>.api: 2, an earlier declaration language, and this nxs reads api 3 | the declaration is in an earlier language | call generate with dry_run: false: it writes the declaration again in api 3 and keeps the earlier file beside it |
reload answers played: false | nxsd is not running, or the declaration is out of tune | status with no port, and start nxsd |
nxs cam1 A stream shows nothing for the agent | viewers need a display | agents use capture, and viewers are for a person at the screen |