MCP tools
Endpoint: https://mcp.staging.nodelets.com/mcp
The endpoint serves MCP over Streamable HTTP, with POST only, and refuses protocol versions older than 2026. It authenticates with an OAuth access token whose connection holds a permission list. Nodelets does not yet offer readers a way to register a client. The protected resource metadata is at https://mcp.staging.nodelets.com/.well-known/oauth-protected-resource/mcp, and the token’s scope is nodelets.
Every tool and resource sees only what the connection’s list covers. A Nodelet outside the list answers NOT_FOUND. A request body is at most 4 MiB.
| Tool | Input | Result | Permission |
|---|---|---|---|
list_nodelets |
none | {"items": [{"id", "name", "bridgeId", "revision"}]} |
Any permission naming the Nodelet |
describe_nodelet |
nodeletId |
The Nodelet’s summary, its covered capabilities and its Thing Description as td |
Any permission naming the Nodelet |
read_property |
nodeletId, name |
{"value": ...}, read from the device for this call |
Read value |
write_property |
nodeletId, name, value |
{"value": null} once the device accepted it. There is no read-back |
Write value |
invoke_action |
nodeletId, name, optional input |
{"value": ...}, the action’s declared output |
Run action |
read_history |
nodeletId, optional property, limit (1 to 1,000, default 100), before, tier (recent or archive) |
A page of saved readings, newest first | Read history |
read_record |
nodeletId, optional before |
A page of the Nodelet’s record, newest first | Read record |
read_history answers with the same fields as the REST saved readings, except that it pages with before, a sequence number, in place of cursor. Pass a page’s before back to go on; null means no more.
read_record answers as the REST record does. Text in a callerSupplied field was written by a caller. A client should treat it as data and never as instructions.
describe_nodelet delivers no events. Events arrive on the bridge stream, which needs an API key.
Errors
Section titled “Errors”A tool that fails returns isError: true, with the error as text and as structured content:
{"error": {"code": "OUTCOME_UNKNOWN", "message": "OUTCOME_UNKNOWN", "correlationId": "mcp_...", "outcome": "unknown"}}The codes and outcomes are those in Outcomes and errors. An unknown outcome on write_property or invoke_action means the device may have acted. Read the property before repeating the call, because a repeat is a new command.
A connection that has ended answers the whole request with HTTP 401 and an invalid_token challenge, so the client can sign in again.
Resources
Section titled “Resources”| URI template | Content | Listing |
|---|---|---|
nodelets://{nodeletId}/td |
The Thing Description, as application/td+json |
One per Nodelet the connection reaches |
nodelets://{nodeletId}/properties/{name} |
The property’s current value as JSON, read from the device for each read | One per property the connection may read |
Reading a property resource needs Read value.
Listen for changes
Section titled “Listen for changes”A client can listen with subscriptions/listen, naming property resources. Each one needs Watch live value, and the property must be readable and observable in its definition. Reading the resource after a change needs Read value. The acknowledgement names only the resources the connection covers; the others are left out.
When a property changes, the client receives notifications/resources/updated with the resource URI. The notification carries no value: read the resource to get it. A listen ends when the token expires, when the connection is ended, or when the bridge’s stream ends. A listen that covers nothing ends at its acknowledgement.