---
title: MCP Resources
description: Reference for mcbluetooth MCP resource URIs
---

mcbluetooth exposes live Bluetooth state through MCP resources. These provide real-time queries without tool calls.

## Resource URIs

| URI | Description |
|-----|-------------|
| `bluetooth://adapters` | All Bluetooth adapters |
| `bluetooth://paired` | Paired devices |
| `bluetooth://connected` | Connected devices |
| `bluetooth://visible` | All known/discovered devices |
| `bluetooth://trusted` | Trusted devices |
| `bluetooth://adapter/{name}` | Specific adapter details |
| `bluetooth://device/{address}` | Specific device details |
| `bluetooth://ble/notifications` | All active BLE notification subscriptions |
| `bluetooth://ble/{address}/{uuid}/notifications` | Latest notification value and stats |
| `bluetooth://ble/{address}/{uuid}/notifications/history` | Buffered notification history |

## Adapter Resources

### bluetooth://adapters

Lists all Bluetooth adapters on the system.

**Response:**
```json
[
  {
    "name": "hci0",
    "address": "AA:BB:CC:DD:EE:FF",
    "alias": "My Laptop",
    "powered": true,
    "discoverable": false,
    "pairable": true,
    "discovering": false
  }
]
```

### bluetooth://adapter/{name}

Get details for a specific adapter.

**URI:** `bluetooth://adapter/hci0`

**Response:**
```json
{
  "name": "hci0",
  "address": "AA:BB:CC:DD:EE:FF",
  "alias": "My Laptop",
  "class": 7995916,
  "powered": true,
  "discoverable": false,
  "discoverable_timeout": 180,
  "pairable": true,
  "pairable_timeout": 0,
  "discovering": false,
  "uuids": ["0000110a-...", "0000110c-..."],
  "modalias": "usb:v1D6Bp0246d0540"
}
```

## Device Resources

### bluetooth://paired

Lists all paired devices across all adapters.

**Response:**
```json
[
  {
    "address": "C8:7B:23:55:68:E8",
    "name": "Bose NCH700",
    "alias": "My Headphones",
    "paired": true,
    "connected": true,
    "trusted": true,
    "adapter": "hci0"
  }
]
```

### bluetooth://connected

Lists currently connected devices.

**Response:**
```json
[
  {
    "address": "C8:7B:23:55:68:E8",
    "name": "Bose NCH700",
    "connected": true,
    "services": ["audio", "hfp"]
  }
]
```

### bluetooth://visible

Lists all known devices (discovered or previously seen).

**Response:**
```json
[
  {
    "address": "AA:BB:CC:DD:EE:FF",
    "name": "Unknown Device",
    "paired": false,
    "connected": false,
    "rssi": -75,
    "last_seen": "2024-01-15T10:30:00"
  }
]
```

### bluetooth://trusted

Lists devices marked as trusted (auto-connect allowed).

**Response:**
```json
[
  {
    "address": "C8:7B:23:55:68:E8",
    "name": "Bose NCH700",
    "trusted": true,
    "paired": true
  }
]
```

### bluetooth://device/{address}

Get details for a specific device.

**URI:** `bluetooth://device/C8:7B:23:55:68:E8`

**Response:**
```json
{
  "address": "C8:7B:23:55:68:E8",
  "name": "Bose NCH700",
  "alias": "My Headphones",
  "class": 2360344,
  "icon": "audio-headphones",
  "paired": true,
  "bonded": true,
  "trusted": true,
  "blocked": false,
  "connected": true,
  "legacy_pairing": false,
  "rssi": -55,
  "uuids": [
    "0000110b-0000-1000-8000-00805f9b34fb",
    "0000110e-0000-1000-8000-00805f9b34fb"
  ],
  "modalias": "bluetooth:v009Ep4020d0134",
  "adapter": "hci0"
}
```

## Usage in MCP Clients

Resources can be read using the standard MCP resource protocol:

```json
{
  "method": "resources/read",
  "params": {
    "uri": "bluetooth://paired"
  }
}
```

## Comparison: Resources vs Tools

| Use Case | Resource | Tool |
|----------|----------|------|
| Check current state | ✓ Resources | |
| Modify state | | ✓ Tools |
| Real-time queries | ✓ Resources | |
| Complex operations | | ✓ Tools |

**Resources** are read-only and ideal for:
- Dashboard displays
- State monitoring
- Quick queries

**Tools** are for actions:
- Pairing devices
- Connecting/disconnecting
- Sending files
- Changing settings

## BLE Notification Resources

These resources provide access to buffered BLE GATT notification values.

### bluetooth://ble/notifications

Lists all active notification subscriptions.

**Response:**
```json
{
  "count": 1,
  "subscriptions": [
    {
      "address": "AA:BB:CC:DD:EE:FF",
      "char_uuid": "00002a37-0000-1000-8000-00805f9b34fb",
      "char_path": "/org/bluez/hci0/dev_.../service.../char...",
      "notifying": true,
      "buffer_count": 15,
      "total_received": 47,
      "uuid_short": "0x2A37"
    }
  ]
}
```

### bluetooth://ble/{address}/{uuid}/notifications

Get latest notification value and buffer statistics.

**URI:** `bluetooth://ble/AA:BB:CC:DD:EE:FF/00002a37-0000-1000-8000-00805f9b34fb/notifications`

**Response:**
```json
{
  "address": "AA:BB:CC:DD:EE:FF",
  "characteristic_uuid": "00002a37-0000-1000-8000-00805f9b34fb",
  "characteristic_uuid_short": "0x2A37",
  "notifying": true,
  "latest": {
    "timestamp": "2026-02-09T20:05:39.091206+00:00",
    "value_hex": "1648",
    "value_bytes": [22, 72]
  },
  "buffer_count": 15,
  "total_received": 47
}
```

### bluetooth://ble/{address}/{uuid}/notifications/history

Get buffered notification history (up to 100 values).

**URI:** `bluetooth://ble/AA:BB:CC:DD:EE:FF/00002a37-.../notifications/history?count=10`

**Response:**
```json
{
  "address": "AA:BB:CC:DD:EE:FF",
  "characteristic_uuid": "00002a37-...",
  "count": 10,
  "values": [
    {
      "timestamp": "2026-02-09T20:05:39.091206+00:00",
      "value_hex": "1648",
      "value_bytes": [22, 72]
    },
    {
      "timestamp": "2026-02-09T20:05:38.091206+00:00",
      "value_hex": "1647",
      "value_bytes": [22, 71]
    }
  ]
}
```

**Notes:**
- Enable notifications with `bt_ble_notify` first
- Notifications are buffered in a circular buffer (max 100 values)
- Buffer persists for the MCP server session lifetime
- Use `bt_ble_clear_notification_buffer` to clear without disabling