MCP Tools Reference

Swarm AI exposes device control through the Model Context Protocol (MCP). This page lists all available tools.

Tool Categories

Swarm AI provides 42 tools across three categories:

Category	Tools	Purpose
Device Control	15	Query and operate lab devices
Transporter Control	19	Control robotic arms and plate handlers
Teachpoint Management	8	Save and manage named positions

Device Control Tools

These tools work with shakers, centrifuges, sealers, and other lab devices.

Query Tools

Tool	Description
device_list	List all connected devices, optionally filtered by type
device_get_info	Get detailed information about a device
device_get_capabilities	Get list of commands a device supports
device_is_initialized	Check if a device is initialized and ready

Operation Tools

Tool	Description	Parameters
device_shake	Shake at speed for duration	device_id, speed (RPM), duration (seconds)
device_centrifuge	Centrifuge at g-force	device_id, g, duration (seconds)
device_seal	Seal plate at temperature	device_id, temperature (Celsius), duration (seconds)
device_stop	Emergency stop	device_id

Device State Tools

Tool	Description
device_initialize	Initialize device (connect, home, calibrate)
device_open	Open device door/lid
device_close	Close device door/lid
device_lock_plate	Lock plate to shaker deck
device_unlock_plate	Unlock plate from shaker deck
device_set_temperature	Set temperature setpoint
device_get_temperature	Get current temperature

Transporter Control Tools

These tools control robotic arms and plate handlers.

Movement Tools

Tool	Description
transporter_move_to	Move to a named teachpoint
transporter_home	Move to home position
transporter_move_to_safe	Move to pre-defined safe position
transporter_halt	Emergency stop (immediate)

Pick and Place Tools

Tool	Description
transporter_pick_plate	Pick up plate from a teachpoint
transporter_place_plate	Place plate at a teachpoint

Gripper Tools

Tool	Description
transporter_open_gripper	Open gripper
transporter_close_gripper	Close gripper

Position Query Tools

Tool	Description
transporter_get_joint_position	Get current position in joint coordinates
transporter_get_cartesian_position	Get current position in cartesian coordinates

Speed Control

Tool	Description
transporter_set_speed	Set movement speed (0.0 to 1.0)
transporter_get_speed	Get current speed setting

Advanced Movement

Tool	Description
transporter_move_to_coords	Move to raw coordinates (joint or cartesian)
transporter_pick_at_coords	Pick at raw cartesian coordinates
transporter_place_at_coords	Place at raw cartesian coordinates
transporter_move_single_axis	Move one axis to absolute position
transporter_move_single_axis_relative	Move one axis by relative distance

Teaching Mode

Tool	Description
transporter_initialize	Initialize transporter (home axes, calibrate)
transporter_set_free_mode	Enable/disable freedrive for manual positioning

Teachpoint Tools

These tools manage named positions for transporters.

Tool	Description
teachpoint_list	List all teachpoints for a device
teachpoint_get	Get a specific teachpoint by name
teachpoint_create	Create teachpoint with explicit coordinates
teachpoint_save_current_position	Save current robot position as teachpoint
teachpoint_update	Update teachpoint coordinates
teachpoint_delete	Delete a teachpoint
teachpoint_bulk_import	Import multiple teachpoints at once
teachpoint_export	Export all teachpoints for a device

Error Responses

All tools return a consistent response format:

Success:

{
  "success": true,
  "result": { ... }
}

Failure:

{
  "success": false,
  "error": "error_type",
  "message": "Human-readable description"
}

Common error types:

• not_found - Device or teachpoint doesn't exist
• not_initialized - Device needs initialization first
• timeout - Operation timed out
• device_error - Device reported an error

MCP Endpoint

URL: https://swarm.cheshirelabs.io/mcp

Transport: Streamable HTTP (MCP specification 2025-03-26)

Authentication: X-API-Key header

What's Next?

• REST API - HTTP API reference
• Using Claude with Swarm AI - Practical examples
• Transporters - Detailed transporter guide