Warning

This documentation is actively being updated as the project evolves and may not be complete in all areas.

jumpstarter-mcp¶

MCP (Model Context Protocol) server for AI agent interaction with Jumpstarter hardware devices.

Overview¶

This package provides an MCP server that exposes Jumpstarter’s lease management, device connections, and command execution as structured tools accessible by AI agents (e.g., via Cursor, Claude Code, or any MCP-compatible host).

IDE Integration¶

Cursor¶

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "jumpstarter": {
      "command": "jmp",
      "args": ["mcp", "serve"]
    }
  }
}

Claude Code¶

Claude Code discovers MCP servers from its configuration. Add Jumpstarter with:

claude mcp add jumpstarter -- jmp mcp serve

Or manually add to ~/.claude/claude_desktop_config.json:

{
  "mcpServers": {
    "jumpstarter": {
      "command": "jmp",
      "args": ["mcp", "serve"]
    }
  }
}

Claude Desktop¶

Add to your Claude Desktop configuration file (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "jumpstarter": {
      "command": "jmp",
      "args": ["mcp", "serve"]
    }
  }
}

Available Tools¶

Lease & Exporter Management¶

Tool	Description
`jmp_list_exporters`	List exporters with online status and lease info
`jmp_list_leases`	List active leases
`jmp_create_lease`	Create a new lease by selector or exporter name
`jmp_delete_lease`	Release a lease

Connection Management¶

Tool	Description
`jmp_connect`	Connect to a device (by lease, selector, or exporter)
`jmp_disconnect`	Disconnect from a device
`jmp_list_connections`	List active connections

Device Interaction¶

Tool	Description
`jmp_run`	Execute CLI commands on a connected device
`jmp_get_env`	Get environment and code examples for direct access

Discovery & Introspection¶

Tool	Description
`jmp_explore`	Discover available CLI commands on a device
`jmp_drivers`	List driver objects and their methods
`jmp_driver_methods`	Inspect driver method signatures and docstrings

Typical Workflow¶

A typical interaction with an AI agent looks like this:

List exporters to see what hardware is available:

“What devices are available on the cluster?”
Create a lease for a target device:

“Get me a QEMU target” or “Lease a board with label board-type=qc8650”
Connect to establish a persistent connection:

“Connect to that lease”
Interact with the device:

“Power on the target and check what OS it’s running via SSH”
Disconnect and release when done:

“Disconnect and delete the lease”

Writing Python with AI Assistance¶

The MCP server is especially useful when writing Python code that interacts with hardware. While connected to a device, the agent can introspect the live connection to discover available drivers, methods, and their signatures – then use that knowledge to help you write correct code.

Ask the agent to explore what’s available on your target:

“I’m connected to an ARM board. What drivers and methods are available?”

The agent calls jmp_drivers and jmp_driver_methods to inspect the live connection and gives you a summary of power, ssh, serial, storage, etc.

Ask for help writing automation scripts:

“Write me a Python script that power-cycles the board, waits for it to boot, and grabs the kernel version over SSH.”

The agent inspects the driver methods to discover exact signatures and generates a working script using the env() helper.

Debug a failing interaction:

“My serial expect is timing out. Can you read the serial output and tell me what the board is printing?”

The agent calls jmp_run with ["serial", "pipe"] and a short timeout to capture what the console is outputting right now.

Discover capabilities you didn’t know about:

“What can I do with the storage driver on this device?”

The agent calls jmp_driver_methods for the storage driver and shows you methods like flash, write_local_file, read_to_local_file, etc. with their full signatures and docstrings.

Iterate on code with live hardware feedback:

“Run my test script and tell me if the board boots successfully.”

The agent uses jmp_get_env to get the shell environment, executes your script, and reports back with the actual device output.

Logging¶

The MCP server logs to ~/.jumpstarter/logs/mcp-server.log. To monitor:

tail -f ~/.jumpstarter/logs/mcp-server.log