MCP Smart Device Auto-Onboarding Guide

1. Overview

This guide explains how a smart device exposes an MCP server so an AI system can discover it automatically on the local network, connect to it, and identify the physical device it represents.

It only defines the device-side discovery and identity requirements used by this project. Standard MCP behavior, including generic tool discovery and tool invocation, remains defined by the MCP protocol and is not repeated here.

2. Protocol Versioning

Current version: 0.0.1

This protocol follows Semantic Versioning 2.0.0. The version number uses the format MAJOR.MINOR.PATCH, where each component signals a different kind of change:

• MAJOR — Breaking changes that require AI system or device implementations to be updated. Examples: removing or renaming a required TXT record key, changing the get_description response structure, altering the mDNS service type.
• MINOR — Backwards-compatible additions. Examples: adding a new optional TXT record key, adding optional fields to DeviceInfo, introducing a new recommended tool that existing implementations may ignore.
• PATCH — Clarifications or corrections to the specification text that do not affect the wire format or required behavior.

The protocol is currently in its initial development phase (0.x.x). During this phase, any release may introduce breaking changes. The MAJOR/MINOR/PATCH semantics described above will be strictly enforced starting from version 1.0.0, at which point an AI system built against version 1.x.x will be able to safely interact with any device that also implements 1.x.x.

3. Auto-Onboarding Flow

A smart device joins the AI system by advertising its MCP endpoint and then describing itself after the AI system connects:

1. The device creates its MCP server and registers its tools, including get_description.
2. The device publishes an mDNS service for that server.
3. The device starts serving MCP with the configured transport, host, and port.
4. The AI system browses _mcp._tcp.local. and discovers the device service.
5. The AI system resolves the service to obtain host, port, endpoint path, and discovery metadata.
6. The AI system connects to the MCP endpoint.
7. The AI system calls get_description to identify the physical device.

MCP connection, tool listing, and tool calls use the standard MCP protocol. After the device is identified, the AI system can select and invoke the device-specific business tools exposed by the server.

4. mDNS Discovery Contract

With DiscoveryConfig.mode set to mdns, the device uses mDNS to publish the network location of its MCP endpoint. This is the framework default and the mode used for automatic onboarding. In the current framework configuration this endpoint is served over streamable-http. The mDNS TXT record advertises ServerConfig.path, which defaults to /mcp and matches FastMCP's default Streamable HTTP route. The AI system does not need a static IP, preconfigured port, or manual device registry entry.

If ServerConfig.path is changed from /mcp, the FastMCP HTTP route must be kept in sync with the advertised path. The current framework startup path relies on FastMCP's default /mcp route.

4.1 mDNS Advertisement

With mDNS discovery enabled, each device instance publishes one mDNS service. The service type is fixed so the AI system can find all compatible devices with one browse operation:

_mcp._tcp.local.

By default, the framework generates the fully qualified service name with this pattern:

{device_name}._mcp._tcp.local.

For example, an environment sensor can register as lab_env_sensor._mcp._tcp.local.

When the AI system resolves the service, mDNS provides the host address, port, and server hostname. The TXT record carries the MCP-specific values needed to build the HTTP endpoint and confirm that the service is an MCP device.

Each mDNS service record includes these TXT key-value pairs:

device_type in the TXT record is a protocol identifier. The user-facing device category, such as "environment sensor" or "inspection robot", is returned by get_description in DeviceInfo.device_type.

4.2 Discovery Examples

macOS:

# Browse all MCP devices on the network
dns-sd -B _mcp._tcp

# Resolve a specific device to get host, port, and TXT records
dns-sd -L lab_env_sensor _mcp._tcp local

Python (zeroconf):

from zeroconf import ServiceBrowser, Zeroconf, ServiceListener


class MyListener(ServiceListener):
    def add_service(self, zc: Zeroconf, type_: str, name: str) -> None:
        info = zc.get_service_info(type_, name)
        if info:
            host = info.parsed_addresses()[0]
            port = info.port
            path = info.properties.get(b"path", b"/mcp").decode()
            print(f"Found device: {name}")
            print(f"  Endpoint: http://{host}:{port}{path}")


zeroconf = Zeroconf()
browser = ServiceBrowser(zeroconf, "_mcp._tcp.local.", MyListener())
# Keep running to receive announcements...

5. Required Identification Tool

mDNS tells the AI system where the MCP server is. It does not describe what the server represents. Every device therefore exposes the following MCP tool so the AI system can map the discovered endpoint to a physical device.

5.1 get_description

Returns the device's static identity metadata.

Parameters: None

structured_content payload:

{
  "device_type": "environment sensor",
  "brand": "Acme",
  "model": "ENV-200",
  "description": "Server room environment sensor with temperature, humidity, and air quality monitoring",
  "alias": "server room environment sensor"
}

get_description returns ToolResult(structured_content=...). The AI system uses this payload to understand the device category, manufacturer, model, and user-facing name before selecting or invoking device-specific business tools.

See Appendix A for the full schema.

Appendix A: DeviceInfo Schema

get_description returns this DeviceInfo structure:

All fields are required and must be present in every response.