mcbluetooth/docs-site/src/content/docs/reference/resources.md

title	description
MCP Resources	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:

[
  {
    "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:

{
  "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:

[
  {
    "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:

[
  {
    "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:

[
  {
    "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:

[
  {
    "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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