MCP Tools Reference

This page documents all tools exposed by the m87 MCP server. Tools are organized by category.

Tools marked with [Batch] support batch operations - pass devices array instead of device to operate on multiple devices at once.

Device Management

devices_list

List all accessible devices. Parameters: None Returns:

[
  {
    "id": "dev-abc123",
    "name": "my-device",
    "status": "online",
    "owner": "user@example.com"
  }
]

devices_approve

Approve a pending device registration. Parameters:

device

string

required

Device ID to approve

Returns:

{"status": "approved"}

devices_reject

Reject a pending device registration. Parameters:

device

string

required

Device ID to reject

Returns:

{"status": "rejected"}

device_status [Batch]

Get device status and health. Supports batch operations. Parameters:

device

string

Single device name or ID (mutually exclusive with devices)

devices

string[]

Multiple device names/IDs for batch execution (mutually exclusive with device)

Returns (single):

{
  "status": "online",
  "health": "healthy",
  "uptime": 86400,
  "last_seen": "2026-03-03T10:00:00Z"
}

Returns (batch):

{
  "results": [
    {"device": "device-1", "status": "online", ...},
    {"device": "device-2", "status": "offline", ...}
  ]
}

device_audit_logs [Batch]

Get audit logs for a device. Supports batch operations. Parameters:

device

string

Single device name or ID (mutually exclusive with devices)

devices

string[]

Multiple device names/IDs (mutually exclusive with device)

since

string

Start time in ISO 8601 format (e.g., “2026-03-01T00:00:00Z”)

until

string

End time in ISO 8601 format

max

number

default:"100"

Maximum number of logs to return

Returns (single):

{
  "logs": [
    {
      "timestamp": "2026-03-03T10:00:00Z",
      "user": "user@example.com",
      "action": "shell",
      "details": "..."
    }
  ]
}

Returns (batch):

{
  "results": [
    {"device": "device-1", "logs": [...]},
    {"device": "device-2", "logs": [...]}
  ]
}

Device Access Control

device_access_list

List users with access to a device. Parameters:

device

string

required

Device name or ID

Returns:

[
  {
    "email": "user@example.com",
    "role": "editor"
  },
  {
    "org_id": "my-org",
    "role": "admin"
  }
]

device_access_add

Grant access to a device. Parameters:

device

string

required

Device name or ID

email_or_org_id

string

required

Email address or organization ID

role

string

required

Role: admin, editor, or viewer

Returns:

{"status": "added"}

device_access_remove

Revoke access to a device. Parameters:

device

string

required

Device name or ID

email_or_org_id

string

required

Email address or organization ID

Returns:

{"status": "removed"}

File Operations

device_ls

List files in a device directory. Parameters:

path

string

required

Remote path in format <device>:<path>

Returns:

[
  {"name": "file.txt", "is_dir": false},
  {"name": "logs", "is_dir": true}
]

device_cp

Copy files between local and remote device. Parameters:

source

string

required

Source path. Use <device>:<path> for remote, <path> for local.

dest

string

required

Destination path. Use <device>:<path> for remote, <path> for local.

Returns:

{"status": "copied"}

device_sync

Sync files between local and remote device. Parameters:

source

string

required

Source path

dest

string

required

Destination path

delete

boolean

default:"false"

Delete files not in source

dry_run

boolean

default:"false"

Show what would be done without making changes

exclude

string[]

File patterns to exclude

Returns:

{"status": "synced"}

Remote Execution

device_exec [Batch]

Execute a command on a device and return output. Non-zero exit codes are returned as data, not errors. Supports batch operations. Parameters:

device

string

Single device name or ID (mutually exclusive with devices)

devices

string[]

Multiple device names/IDs (mutually exclusive with device)

command

string[]

required

Command and arguments to execute

timeout_secs

number

default:"30"

Command timeout in seconds

Returns (single):

{
  "output": "command output here",
  "exit_code": 0
}

Returns (batch):

{
  "results": [
    {"device": "device-1", "output": "...", "exit_code": 0},
    {"device": "device-2", "error": "timeout"}
  ]
}

docker_exec

Run a docker command on a device and capture output. The docker socket is forwarded via QUIC automatically. For long-running containers use the -d flag. Parameters:

device

string

required

Device name or ID

args

string[]

required

Docker CLI arguments (e.g., ["ps", "-a"] or ["run", "-d", "nginx"])

timeout_secs

number

default:"60"

Timeout in seconds (use higher values for builds/pulls)

Returns:

{
  "stdout": "CONTAINER ID   IMAGE   ...",
  "stderr": "",
  "exit_code": 0
}

Port Forwarding

forward_start

Start port/socket forwarding to a device. Returns a session ID for lifecycle management. Forwarding runs in the background until stopped. Parameters:

device

string

required

Device name or ID

specs

string[]

required

Forward specifications (e.g., ["8080:80", "/tmp/sock:/var/run/docker.sock"])

Returns:

{
  "session_id": "1",
  "device": "my-device",
  "targets": ["TcpPort(8080->80)"],
  "status": "started"
}

forward_stop

Stop a running forward session by session ID. Parameters:

session_id

string

required

Session ID returned by forward_start

Returns:

{
  "session_id": "1",
  "status": "stopped"
}

forward_list

List all active forward sessions. Parameters: None Returns:

[
  {
    "session_id": "1",
    "device": "my-device",
    "specs": ["8080:80"],
    "targets": ["TcpPort(8080->80)"]
  }
]

Deployment Operations

device_deploy

Add a deployment spec to a device. Parameters:

device

string

required

Device name or ID

file

string

required

Path to deployment file (docker-compose.yml or run spec YAML)

spec_type

string

default:"auto"

Spec type: auto, compose, runspec, or deployment

name

string

Optional display name for the run spec

deployment_id

string

Target deployment ID (uses active if omitted)

Returns:

{"status": "deployed"}

device_undeploy

Remove a deployment spec from a device. Parameters:

device

string

required

Device name or ID

job_id

string

required

Job ID to remove

deployment_id

string

Target deployment ID (uses active if omitted)

Returns:

{"status": "undeployed"}

device_deployment_list [Batch]

List all deployments for a device. Supports batch operations. Parameters:

device

string

Single device name or ID (mutually exclusive with devices)

devices

string[]

Multiple device names/IDs (mutually exclusive with device)

Returns (single):

{
  "deployments": [
    {
      "id": "dep-123",
      "active": true,
      "jobs": [...]
    }
  ]
}

Returns (batch):

{
  "results": [
    {"device": "device-1", "deployments": [...]},
    {"device": "device-2", "deployments": [...]}
  ]
}

device_deployment_new

Create a new deployment for a device. Parameters:

device

string

required

Device name or ID

active

boolean

default:"false"

Make this deployment active immediately

Returns:

{
  "id": "dep-456",
  "active": false,
  "jobs": []
}

device_deployment_show

Show deployment details. Parameters:

device

string

required

Device name or ID

deployment_id

string

Deployment ID (uses active if omitted)

Returns:

{
  "id": "dep-123",
  "active": true,
  "jobs": [
    {
      "id": "web-app",
      "enabled": true,
      "type": "service"
    }
  ]
}

device_deployment_rm

Remove a deployment. Parameters:

device

string

required

Device name or ID

deployment_id

string

required

Deployment ID to remove

Returns:

{"status": "removed"}

device_deployment_active

Get the currently active deployment. Parameters:

device

string

required

Device name or ID

Returns:

{
  "active_deployment_id": "dep-123"
}

device_deployment_activate

Set the active deployment. Parameters:

device

string

required

Device name or ID

deployment_id

string

required

Deployment ID to activate

Returns:

{"status": "activated"}

device_deployment_status [Batch]

Get deployment status. Supports batch operations. Parameters:

device

string

Single device name or ID (mutually exclusive with devices)

devices

string[]

Multiple device names/IDs (mutually exclusive with device)

deployment_id

string

Deployment ID (uses active if omitted)

Returns (single):

{
  "deployment_id": "dep-123",
  "status": "running",
  "jobs": [
    {
      "id": "web-app",
      "status": "running",
      "health": "healthy"
    }
  ]
}

Returns (batch):

{
  "results": [
    {"device": "device-1", "deployment_id": "dep-123", ...},
    {"device": "device-2", "error": "No active deployment"}
  ]
}

device_deployment_clone

Clone a deployment. Parameters:

device

string

required

Device name or ID

deployment_id

string

required

Source deployment ID to clone

active

boolean

default:"false"

Make cloned deployment active immediately

Returns:

{
  "id": "dep-789",
  "active": false,
  "jobs": [...]
}

Organization Management

org_list

List organizations. Parameters: None Returns:

[
  {
    "id": "my-org",
    "owner": "owner@example.com",
    "members": 5
  }
]

org_create

Create an organization. Parameters:

string

required

Organization ID

string

required

Owner email address

Returns:

{"status": "created"}

org_delete

Delete an organization. Parameters:

string

required

Organization ID

Returns:

{"status": "deleted"}

org_update

Update organization. Parameters:

string

required

Current organization ID

new_id

string

required

New organization ID

Returns:

{"status": "updated"}

org_members_list

List organization members. Parameters:

org_id

string

required

Organization ID

Returns:

[
  {
    "email": "user@example.com",
    "role": "editor"
  }
]

org_members_add

Add organization member. Parameters:

org_id

string

required

Organization ID

string

required

Member email address

role

string

required

Role: admin, editor, or viewer

Returns:

{"status": "added"}

org_members_remove

Remove organization member. Parameters:

org_id

string

required

Organization ID

string

required

Member email address

Returns:

{"status": "removed"}

org_devices_list

List organization devices. Parameters:

org_id

string

required

Organization ID

Returns:

[
  {
    "id": "dev-123",
    "name": "my-device",
    "status": "online"
  }
]

org_devices_add

Add device to organization. Parameters:

org_id

string

required

Organization ID

device

string

required

Device name or ID

Returns:

{"status": "added"}

org_devices_remove

Remove device from organization. Parameters:

org_id

string

required

Organization ID

device

string

required

Device name or ID

Returns:

{"status": "removed"}

​Device Management

​devices_list

​devices_approve

​devices_reject

​device_status [Batch]

​device_audit_logs [Batch]

​Device Access Control

​device_access_list

​device_access_add

​device_access_remove

​File Operations

​device_ls

​device_cp

​device_sync

​Remote Execution

​device_exec [Batch]

​docker_exec

​Port Forwarding

​forward_start

​forward_stop

​forward_list

​Deployment Operations

​device_deploy

​device_undeploy

​device_deployment_list [Batch]

​device_deployment_new

​device_deployment_show

​device_deployment_rm

​device_deployment_active

​device_deployment_activate

​device_deployment_status [Batch]

​device_deployment_clone

​Organization Management

​org_list

​org_create

​org_delete

​org_update

​org_members_list

​org_members_add

​org_members_remove

​org_devices_list

​org_devices_add

​org_devices_remove

Device Management

devices_list

devices_approve

devices_reject

device_status [Batch]

device_audit_logs [Batch]

Device Access Control

device_access_list

device_access_add

device_access_remove

File Operations

device_ls

device_cp

device_sync

Remote Execution

device_exec [Batch]

docker_exec

Port Forwarding

forward_start

forward_stop

forward_list

Deployment Operations

device_deploy

device_undeploy

device_deployment_list [Batch]

device_deployment_new

device_deployment_show

device_deployment_rm

device_deployment_active

device_deployment_activate

device_deployment_status [Batch]

device_deployment_clone

Organization Management

org_list

org_create

org_delete

org_update

org_members_list

org_members_add

org_members_remove

org_devices_list

org_devices_add

org_devices_remove