> ## Documentation Index
> Fetch the complete documentation index at: https://docs.make87.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Tools Reference

> Complete reference for all MCP tools available in the m87 server

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

<Note>
  Tools marked with **\[Batch]** support batch operations - pass `devices` array instead of `device` to operate on multiple devices at once.
</Note>

## Device Management

### devices\_list

List all accessible devices.

**Parameters:** None

**Returns:**

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

### devices\_approve

Approve a pending device registration.

**Parameters:**

<ParamField path="device" type="string" required>
  Device ID to approve
</ParamField>

**Returns:**

```json theme={null}
{"status": "approved"}
```

### devices\_reject

Reject a pending device registration.

**Parameters:**

<ParamField path="device" type="string" required>
  Device ID to reject
</ParamField>

**Returns:**

```json theme={null}
{"status": "rejected"}
```

### device\_status **\[Batch]**

Get device status and health. Supports batch operations.

**Parameters:**

<ParamField path="device" type="string">
  Single device name or ID (mutually exclusive with `devices`)
</ParamField>

<ParamField path="devices" type="string[]">
  Multiple device names/IDs for batch execution (mutually exclusive with `device`)
</ParamField>

**Returns (single):**

```json theme={null}
{
  "status": "online",
  "health": "healthy",
  "uptime": 86400,
  "last_seen": "2026-03-03T10:00:00Z"
}
```

**Returns (batch):**

```json theme={null}
{
  "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:**

<ParamField path="device" type="string">
  Single device name or ID (mutually exclusive with `devices`)
</ParamField>

<ParamField path="devices" type="string[]">
  Multiple device names/IDs (mutually exclusive with `device`)
</ParamField>

<ParamField path="since" type="string">
  Start time in ISO 8601 format (e.g., "2026-03-01T00:00:00Z")
</ParamField>

<ParamField path="until" type="string">
  End time in ISO 8601 format
</ParamField>

<ParamField path="max" type="number" default="100">
  Maximum number of logs to return
</ParamField>

**Returns (single):**

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

**Returns (batch):**

```json theme={null}
{
  "results": [
    {"device": "device-1", "logs": [...]},
    {"device": "device-2", "logs": [...]}
  ]
}
```

## Device Access Control

### device\_access\_list

List users with access to a device.

**Parameters:**

<ParamField path="device" type="string" required>
  Device name or ID
</ParamField>

**Returns:**

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

### device\_access\_add

Grant access to a device.

**Parameters:**

<ParamField path="device" type="string" required>
  Device name or ID
</ParamField>

<ParamField path="email_or_org_id" type="string" required>
  Email address or organization ID
</ParamField>

<ParamField path="role" type="string" required>
  Role: `admin`, `editor`, or `viewer`
</ParamField>

**Returns:**

```json theme={null}
{"status": "added"}
```

### device\_access\_remove

Revoke access to a device.

**Parameters:**

<ParamField path="device" type="string" required>
  Device name or ID
</ParamField>

<ParamField path="email_or_org_id" type="string" required>
  Email address or organization ID
</ParamField>

**Returns:**

```json theme={null}
{"status": "removed"}
```

## File Operations

### device\_ls

List files in a device directory.

**Parameters:**

<ParamField path="path" type="string" required>
  Remote path in format `<device>:<path>`
</ParamField>

**Returns:**

```json theme={null}
[
  {"name": "file.txt", "is_dir": false},
  {"name": "logs", "is_dir": true}
]
```

### device\_cp

Copy files between local and remote device.

**Parameters:**

<ParamField path="source" type="string" required>
  Source path. Use `<device>:<path>` for remote, `<path>` for local.
</ParamField>

<ParamField path="dest" type="string" required>
  Destination path. Use `<device>:<path>` for remote, `<path>` for local.
</ParamField>

**Returns:**

```json theme={null}
{"status": "copied"}
```

### device\_sync

Sync files between local and remote device.

**Parameters:**

<ParamField path="source" type="string" required>
  Source path
</ParamField>

<ParamField path="dest" type="string" required>
  Destination path
</ParamField>

<ParamField path="delete" type="boolean" default="false">
  Delete files not in source
</ParamField>

<ParamField path="dry_run" type="boolean" default="false">
  Show what would be done without making changes
</ParamField>

<ParamField path="exclude" type="string[]">
  File patterns to exclude
</ParamField>

**Returns:**

```json theme={null}
{"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:**

<ParamField path="device" type="string">
  Single device name or ID (mutually exclusive with `devices`)
</ParamField>

<ParamField path="devices" type="string[]">
  Multiple device names/IDs (mutually exclusive with `device`)
</ParamField>

<ParamField path="command" type="string[]" required>
  Command and arguments to execute
</ParamField>

<ParamField path="timeout_secs" type="number" default="30">
  Command timeout in seconds
</ParamField>

**Returns (single):**

```json theme={null}
{
  "output": "command output here",
  "exit_code": 0
}
```

**Returns (batch):**

```json theme={null}
{
  "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:**

<ParamField path="device" type="string" required>
  Device name or ID
</ParamField>

<ParamField path="args" type="string[]" required>
  Docker CLI arguments (e.g., `["ps", "-a"]` or `["run", "-d", "nginx"]`)
</ParamField>

<ParamField path="timeout_secs" type="number" default="60">
  Timeout in seconds (use higher values for builds/pulls)
</ParamField>

**Returns:**

```json theme={null}
{
  "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:**

<ParamField path="device" type="string" required>
  Device name or ID
</ParamField>

<ParamField path="specs" type="string[]" required>
  Forward specifications (e.g., `["8080:80", "/tmp/sock:/var/run/docker.sock"]`)
</ParamField>

**Returns:**

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

### forward\_stop

Stop a running forward session by session ID.

**Parameters:**

<ParamField path="session_id" type="string" required>
  Session ID returned by `forward_start`
</ParamField>

**Returns:**

```json theme={null}
{
  "session_id": "1",
  "status": "stopped"
}
```

### forward\_list

List all active forward sessions.

**Parameters:** None

**Returns:**

```json theme={null}
[
  {
    "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:**

<ParamField path="device" type="string" required>
  Device name or ID
</ParamField>

<ParamField path="file" type="string" required>
  Path to deployment file (docker-compose.yml or run spec YAML)
</ParamField>

<ParamField path="spec_type" type="string" default="auto">
  Spec type: `auto`, `compose`, `runspec`, or `deployment`
</ParamField>

<ParamField path="name" type="string">
  Optional display name for the run spec
</ParamField>

<ParamField path="deployment_id" type="string">
  Target deployment ID (uses active if omitted)
</ParamField>

**Returns:**

```json theme={null}
{"status": "deployed"}
```

### device\_undeploy

Remove a deployment spec from a device.

**Parameters:**

<ParamField path="device" type="string" required>
  Device name or ID
</ParamField>

<ParamField path="job_id" type="string" required>
  Job ID to remove
</ParamField>

<ParamField path="deployment_id" type="string">
  Target deployment ID (uses active if omitted)
</ParamField>

**Returns:**

```json theme={null}
{"status": "undeployed"}
```

### device\_deployment\_list **\[Batch]**

List all deployments for a device. Supports batch operations.

**Parameters:**

<ParamField path="device" type="string">
  Single device name or ID (mutually exclusive with `devices`)
</ParamField>

<ParamField path="devices" type="string[]">
  Multiple device names/IDs (mutually exclusive with `device`)
</ParamField>

**Returns (single):**

```json theme={null}
{
  "deployments": [
    {
      "id": "dep-123",
      "active": true,
      "jobs": [...]
    }
  ]
}
```

**Returns (batch):**

```json theme={null}
{
  "results": [
    {"device": "device-1", "deployments": [...]},
    {"device": "device-2", "deployments": [...]}
  ]
}
```

### device\_deployment\_new

Create a new deployment for a device.

**Parameters:**

<ParamField path="device" type="string" required>
  Device name or ID
</ParamField>

<ParamField path="active" type="boolean" default="false">
  Make this deployment active immediately
</ParamField>

**Returns:**

```json theme={null}
{
  "id": "dep-456",
  "active": false,
  "jobs": []
}
```

### device\_deployment\_show

Show deployment details.

**Parameters:**

<ParamField path="device" type="string" required>
  Device name or ID
</ParamField>

<ParamField path="deployment_id" type="string">
  Deployment ID (uses active if omitted)
</ParamField>

**Returns:**

```json theme={null}
{
  "id": "dep-123",
  "active": true,
  "jobs": [
    {
      "id": "web-app",
      "enabled": true,
      "type": "service"
    }
  ]
}
```

### device\_deployment\_rm

Remove a deployment.

**Parameters:**

<ParamField path="device" type="string" required>
  Device name or ID
</ParamField>

<ParamField path="deployment_id" type="string" required>
  Deployment ID to remove
</ParamField>

**Returns:**

```json theme={null}
{"status": "removed"}
```

### device\_deployment\_active

Get the currently active deployment.

**Parameters:**

<ParamField path="device" type="string" required>
  Device name or ID
</ParamField>

**Returns:**

```json theme={null}
{
  "active_deployment_id": "dep-123"
}
```

### device\_deployment\_activate

Set the active deployment.

**Parameters:**

<ParamField path="device" type="string" required>
  Device name or ID
</ParamField>

<ParamField path="deployment_id" type="string" required>
  Deployment ID to activate
</ParamField>

**Returns:**

```json theme={null}
{"status": "activated"}
```

### device\_deployment\_status **\[Batch]**

Get deployment status. Supports batch operations.

**Parameters:**

<ParamField path="device" type="string">
  Single device name or ID (mutually exclusive with `devices`)
</ParamField>

<ParamField path="devices" type="string[]">
  Multiple device names/IDs (mutually exclusive with `device`)
</ParamField>

<ParamField path="deployment_id" type="string">
  Deployment ID (uses active if omitted)
</ParamField>

**Returns (single):**

```json theme={null}
{
  "deployment_id": "dep-123",
  "status": "running",
  "jobs": [
    {
      "id": "web-app",
      "status": "running",
      "health": "healthy"
    }
  ]
}
```

**Returns (batch):**

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

### device\_deployment\_clone

Clone a deployment.

**Parameters:**

<ParamField path="device" type="string" required>
  Device name or ID
</ParamField>

<ParamField path="deployment_id" type="string" required>
  Source deployment ID to clone
</ParamField>

<ParamField path="active" type="boolean" default="false">
  Make cloned deployment active immediately
</ParamField>

**Returns:**

```json theme={null}
{
  "id": "dep-789",
  "active": false,
  "jobs": [...]
}
```

## Organization Management

### org\_list

List organizations.

**Parameters:** None

**Returns:**

```json theme={null}
[
  {
    "id": "my-org",
    "owner": "owner@example.com",
    "members": 5
  }
]
```

### org\_create

Create an organization.

**Parameters:**

<ParamField path="id" type="string" required>
  Organization ID
</ParamField>

<ParamField path="email" type="string" required>
  Owner email address
</ParamField>

**Returns:**

```json theme={null}
{"status": "created"}
```

### org\_delete

Delete an organization.

**Parameters:**

<ParamField path="id" type="string" required>
  Organization ID
</ParamField>

**Returns:**

```json theme={null}
{"status": "deleted"}
```

### org\_update

Update organization.

**Parameters:**

<ParamField path="id" type="string" required>
  Current organization ID
</ParamField>

<ParamField path="new_id" type="string" required>
  New organization ID
</ParamField>

**Returns:**

```json theme={null}
{"status": "updated"}
```

### org\_members\_list

List organization members.

**Parameters:**

<ParamField path="org_id" type="string" required>
  Organization ID
</ParamField>

**Returns:**

```json theme={null}
[
  {
    "email": "user@example.com",
    "role": "editor"
  }
]
```

### org\_members\_add

Add organization member.

**Parameters:**

<ParamField path="org_id" type="string" required>
  Organization ID
</ParamField>

<ParamField path="email" type="string" required>
  Member email address
</ParamField>

<ParamField path="role" type="string" required>
  Role: `admin`, `editor`, or `viewer`
</ParamField>

**Returns:**

```json theme={null}
{"status": "added"}
```

### org\_members\_remove

Remove organization member.

**Parameters:**

<ParamField path="org_id" type="string" required>
  Organization ID
</ParamField>

<ParamField path="email" type="string" required>
  Member email address
</ParamField>

**Returns:**

```json theme={null}
{"status": "removed"}
```

### org\_devices\_list

List organization devices.

**Parameters:**

<ParamField path="org_id" type="string" required>
  Organization ID
</ParamField>

**Returns:**

```json theme={null}
[
  {
    "id": "dev-123",
    "name": "my-device",
    "status": "online"
  }
]
```

### org\_devices\_add

Add device to organization.

**Parameters:**

<ParamField path="org_id" type="string" required>
  Organization ID
</ParamField>

<ParamField path="device" type="string" required>
  Device name or ID
</ParamField>

**Returns:**

```json theme={null}
{"status": "added"}
```

### org\_devices\_remove

Remove device from organization.

**Parameters:**

<ParamField path="org_id" type="string" required>
  Organization ID
</ParamField>

<ParamField path="device" type="string" required>
  Device name or ID
</ParamField>

**Returns:**

```json theme={null}
{"status": "removed"}
```