Skip to content
Port OS

MCP reference

The Port OS MCP server lets an AI client discover and control your devices. This page lists the endpoint, how a client authorizes and registers, and each tool with its scope, input and result.

To connect your AI first, follow How to use MCP

Endpoint

Enter this server URL in your AI client. The transport is Streamable HTTP and sign-in is required.

Your AI client finds the available tools with tools/list. The tools available can vary by deployment.

Authorization

To access the Port OS MCP endpoint you can use access tokens.

To use an access token, go to the Tokens page and generate an access token.

Then set the access token in your MCP client configuration, for example:

JSON configuration
{
  "mcpServers": {
    "portos": {
      "type": "http",
      "url": "https://api.portoperatingsystem.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_ACCESS_TOKEN"
      }
    }
  }
}

Note that tokens expire after a set period, so they aren't the recommended long-term solution.

To access the Port OS MCP endpoint long term, we recommend using OAuth.

To use Port OS OAuth, see the guide to setting up an OAuth client for Port OS for how to configure the OAuth code exchange and redirects.

Supported OAuth variants:

OAuth flow

The MCP server uses OAuth 2.1 with the authorization code flow. A client sends a request to the endpoint and receives a WWW-Authenticate header that points to the protected-resource metadata at /.well-known/oauth-protected-resource/mcp. That metadata names the authorization server, https://auth.portoperatingsystem.com, whose metadata at /.well-known/oauth-authorization-server lists the authorization, token and registration endpoints.

Client registration

Port OS must know a client before it shows the consent page. A client registers in one of three ways.

Port OS returns the user only to a redirect URL that matches the registration.

Token endpoint authentication

A client authenticates at the token endpoint with one of these token_endpoint_auth_method values.

A client with a secret must also authenticate when it refreshes a token and when it exchanges an authorization code, even with PKCE. See Authentication for token lifetimes and refresh.

Tools

Each tool below lists what it does, the scope it needs, the input your client sends in tools/call, and the result it returns.

Control

Open tool page →
TOOL control

Control connected devices and services, retrieve results, and capture camera snapshots.

Discover the device with endpoint_query or the room with group_query. Copy its full id, message and optional routeId; use the documented payload for the declared message. Send a matching payload ({} for a command without fields). Preserve the account that returned the IDs and clarify ambiguous targets before writes.

Most controls return status accepted: dispatch succeeded, but the physical outcome is unconfirmed. For result-returning commands, such as search, library pages and get-snapshot, set waitForResult=true. A correlated result returns status responded; snapshots also return image pixels and timeOfSample. Outbound declarations include events, so they do not guarantee that every command responds. For playback, volume and power, omit waitForResult and verify fresh state using endpoint_query or group_query with declared expand capabilities and forceDeviceAttributeQuery=true.

Use only capabilities and commands declared by the selected device or service. Examples of device classes and providers, subject to the connected integration's support:

  • Lights, switches and plugs: on/off and brightness (Philips Hue, Tuya, TP-Link).
  • Phones, tablets, laptops, wallets and trackers: locate or ring (Apple Find My, Tile).
  • Thermostats and temperature sensors: heat/cool settings; read ambient temperature with endpoint_query (Nest, Tuya, ecobee).
  • Cameras: request a declared get-snapshot command and inspect the returned pixels (Ring, Nest and other cameras). A snapshot is distinct from live video.
  • Connectivity and battery: check declared observations with endpoint_query for phones, watches, locks and other devices.
  • Smart locks and PINs: use declared lock and PIN commands (August, Yale, Ring, Seam).
  • Home appliances: supported controls and running-state observations (Samsung, LG, Xiaomi).
  • Robot vacuums: clean rooms and return to dock (Roomba, Roborock, Dreame). Send clean-room to the robot listing the room in controllableGroups with {"groupIds": [<group ID>]}. Bounded remote driving requires fresh visual feedback; cleaning is not navigation.
  • Speakers and announcements: supported speech and audio playback (Sonos, Alexa, Nest cameras).
  • TVs, remotes and media libraries: playback, volume, search and declared playlist operations (Spotify, Fire TV, YouTube, Chrome, TCL, Samsung, LG).
  • Files and photos: declared browse, download, upload, rename, move and delete commands (iCloud Photos, iCloud Drive, Google Drive, Outlook). download-file returns a URI; catalog presence alone does not establish upload support.
  • Litter robots and pet appliances: declared cleaning, waste and dispensing observations or controls.
  • Water sensors and sprinklers: declared water detection, watering state and controls.
  • Calendars and reminders: declared list, create, complete, reschedule and delete operations (iCloud Calendar and Reminders). Connected reminders are distinct from assistant-created scheduled tasks.

Read the relevant bundled skill reference or portos://guides/index for unfamiliar workflows. File/reminder deletion and PIN changes modify account data. Inspect partial or uncertain writes before another action. result_timeout means unknown outcome: read state before considering a retry. MESSAGE_UNSUPPORTED or MESSAGE_AMBIGUOUS means nothing was sent; correct the message from discovery. An unreachable device rejected the command. Never automatically retry a state-changing command or claim success from conflicting observations.

Use endpoint_manage/group_manage to change names, types, membership or merges.

Required scope

message:send

Input

Fields
correlationTokenstring

Optional caller-provided correlation token.

idstringRequired

Full Port OS endpoint ID (…/endpoints/…) from endpoint_query or group ID (…/endpoint-groups/…) from group_query.

messagestringRequired

Full message ID copied from the target's messages: <capability-interface-namespace>/messages/<message-name>, with an @<version> suffix only when the listed ID has one.

payloadobjectRequired

JSON object matching the message payload schema. Use {} for messages without fields.

routeIdstring

Optional provider route ID copied from the target routes. Reuse it for pause, resume and volume after playing through that provider. It must belong to id and advertise the requested message. Without it, the route declaring the most interfaces is used, then the highest route ID.

waitForResultboolean

Wait for one correlated, schema-validated result for commands that retrieve results, such as camera snapshots, media search or library pages, when outboundMessages are declared. Playback and volume commands do not return correlated results. For power and other response-less controls omit it, then read fresh state with endpoint_query.

Result

Fields
timeOfSamplestring

format: "date-time"

correlationTokenstring
resultobject
statusstringRequired

Allowed values: accepted, responded.

Errors

A failed call returns this error object as its result instead.

Fields
familystringRequired

The broad class of an error. The family decides the HTTP status of a REST error, so clients can handle every code of a family alike.

codestringRequired

The specific error, one of a closed set of Port OS codes. Every REST error body, MCP tool error, batch item error and discovery item error uses this enum; each code belongs to an `ErrorFamily` that decides its HTTP status. Provider-specific codes are never codes: they travel in `details.providerCode`. New failure kinds are added here, never as free strings.

messagestringRequired

Plain-language description of the failure and the suggested next action.

detailsErrorDetails

Optional typed context for an error. Fields are additive and only populated when the error can safely expose that context to API clients.

errorsarray<SynchronizationItemError>

Every rejected item when a request that is validated item by item and applied atomically fails, such as a discovery `SynchronizationRequest` whose routes, group routes or relationships are rejected. Omitted for single-item failures.

Manage Devices and Services

Open tool page →
TOOL endpoint_manage

Manage the names, types and registry entries of your devices and connected services.

Choose one operation: RENAME, SET_TYPE, SET_ENABLEMENT, MERGE_INTO, or DELETE. Use endpoint_query first and copy the full endpoint ID. Rename and type changes are durable across provider rediscovery. Disabled endpoints stay available for explicit metadata reads, but cannot receive messages; rediscovery preserves the disabled state. DELETE removes the registry entry, though a provider may rediscover it later. MERGE_INTO retains the source endpoint as disabled and moves supported references to the target; it does not create a source-ID alias, and the target's enablement remains in effect. Before MERGE_INTO or DELETE, identify the actual endpoint and explain the effect to the user; never assume two endpoints are duplicates because their names match. This tool changes registry metadata only and never performs physical control.

Required scope

endpoint:write

Input

Fields
enablementstring

New endpoint enablement; only for SET_ENABLEMENT.

Allowed values: ENABLED, DISABLED.

endpointIdstringRequired

Full endpoint ID from endpoint_query.

mergeIntostring

Full target endpoint ID; only for MERGE_INTO.

namestring

New endpoint name; only for RENAME.

operationstringRequired

Allowed values: RENAME, SET_TYPE, SET_ENABLEMENT, MERGE_INTO, DELETE.

typestring

New ontological endpoint type; only for SET_TYPE.

Result

Fields
endpointIdstringRequired
mergeIntostring
operationstringRequired
statusstringRequired

Allowed values: UPDATED, DELETED.

Errors

A failed call returns this error object as its result instead.

Fields
familystringRequired

The broad class of an error. The family decides the HTTP status of a REST error, so clients can handle every code of a family alike.

codestringRequired

The specific error, one of a closed set of Port OS codes. Every REST error body, MCP tool error, batch item error and discovery item error uses this enum; each code belongs to an `ErrorFamily` that decides its HTTP status. Provider-specific codes are never codes: they travel in `details.providerCode`. New failure kinds are added here, never as free strings.

messagestringRequired

Plain-language description of the failure and the suggested next action.

detailsErrorDetails

Optional typed context for an error. Fields are additive and only populated when the error can safely expose that context to API clients.

errorsarray<SynchronizationItemError>

Every rejected item when a request that is validated item by item and applied atomically fails, such as a discovery `SynchronizationRequest` whose routes, group routes or relationships are rejected. Omitted for single-item failures.

Find Devices and Services

Open tool page →
TOOL endpoint_query

Find connected devices and services, discover their controls, and read their state.

Start with a focused name, room or category query; follow paginationContext.nextToken. Results include full IDs, device types, provider routes, capabilities and accepted message IDs. An endpoint is a device or connected service, including a filesystem or media library. Copy IDs verbatim into control. For a known device, use endpointId; inspect its declared capabilities, commands and outbound message IDs. Use group_query for rooms and endpoint_manage for requested inventory cleanup.

To read state, set expand to the declared capabilities you need, for example ["power","connectivity"] or ["battery"]. expand adds observations; it does not discover more devices or send controls. Add forceDeviceAttributeQuery=true to refresh selected attributes from the provider; otherwise readings may come from cache. Only FRESH observations establish the current state. A FRESH value is the current state; a STALE value is the last known state, reported with its sampledAt and never as live or unknown (a forced read may refresh it). Errored, missing or invalid values are unknown, not OFF or a dead battery, and a STALE value alone must not support a safety claim such as locked or off. An attribute with error.code PROVIDER_NO_STATE (forced reads only) means the provider answered but has no value for it: state is unknown and retrying will not help until the provider reports one. FRESH UNREACHABLE means offline even if a power value is present; STALE UNREACHABLE is the last known connectivity. An ID-only lookup retrieves metadata without requesting fresh state.

Supported discovery includes:

  • Lights, switches and plugs: select by name and power/brightness capabilities as well as type; a light may be typed SWITCH or PLUG.
  • Thermostats and sensors: read temperature-sensor for ambient temperature; a setpoint is not room temperature. Clarify indoor versus outdoor temperature when ambiguous.
  • Cameras, locks, appliances, vacuums, pet appliances, sprinklers and water sensors: inspect declared controls and observations.
  • Phones, Apple Watch and trackers: read battery, charging, connectivity or location capabilities; use control for a declared ring command.
  • Speakers, TVs and media services: discover playback, volume, search and playlist commands. Alexa devices may be VOICE_ASSISTANT.
  • Filesystems, photos, calendars and reminders: choose a concrete route-backed service, rather than a generic plugin catalog or an old unrouted record.

Read portos://guides/index or the bundled Port OS skill references for device workflows. Keep the account with every ID; check relevant authorized accounts before reporting a device missing. Names alone do not prove identity. Preserve routeId for the chosen provider and establish identity before merging records. By default lists contain enabled devices; enablement=DISABLED selects disabled devices and enablement=* includes both. Exact endpointId lookup can read metadata regardless of enablement. With group:read, controllableGroups lists rooms a device can act on. Simulator state does not establish household device state.

Required scope

endpoint:read

Input

Fields
enablementstring

Filter by ENABLED (default), DISABLED, or * for both. This filter is preserved by pagination.

Default: ENABLED

Allowed values: ENABLED, DISABLED, *.

endpointIdstring

Return one endpoint by its full Port OS identifier. Cannot be combined with other filters or pagination. Results advertise its declared command and outbound message IDs.

expandarray<string>

Select observations to add to each device result, for example ["power", "connectivity"] or ["battery"]. Use capability names or full namespaces declared by the device. This reads attributes; it does not send commands or broaden the device search. Short names use port1/systems/zero/capability-interfaces. No state reads by default.

forceDeviceAttributeQueryboolean

Read selected attributes from devices instead of cache. Requires nonempty expand. Failed reads remain unavailable.

maxResultsinteger

Maximum number of results (default 10, maximum 100).

minimum: 1

nextTokenstring

Opaque cursor returned by a previous endpoint_query call.

queryobject

Optional field-first filter. Omit it to load full context; filter only when the account is large. Each key is a field or a combinator, and all keys of one object must match: {"name": {"like": "living"}, "type": {"in": ["LIGHT", "SWITCH"]}}. Combinators: {"and": [query, ...]}, {"or": [query, ...]}, {"not": query}. Text operators: eq (exact), in (any of a list), like (case-insensitive substring), lt and gt (lexical order). List operators: has (contains the exact value), like (some value contains the substring, case-insensitive). Fields: the fields your connected devices declare, listed in the tool description returned by tools/list.

Result

Fields
(payload)object

Show Devices and Services

Open tool page →
TOOL endpoint_show

Show Port OS devices with their supported controls.

To show a device, always call this tool: the widget it opens is the device's UI, so never render a second card, map or controls for it; answer in a sentence or two.

Uses the same selection, expansion and pagination arguments as endpoint_query. A single matching device opens its full view with now playing, transport, volume and other controls; several matches open only a list of names to choose from, so pass one full endpoint ID (or a query matching one device) to control a device. Showing a device does not start live video or send a control command.

Pass primary to choose which card leads, one of the device's card ids (every result lists them as cardIds; an unknown id is rejected with the available ones). The device's usual card and every other card stay behind the details toggle. Examples: "what's the battery on the vacuum" -> primary battery; "turn the thermostat fan on" -> primary fan; "how open are the blinds" -> primary closure; "show me the camera on the roborock" -> primary camera. "where is my phone" or "show its location" -> primary location; "show the roborock's map" or "pick a room to clean" -> primary house-map. Every result already includes the cached readings of the cards it lists (cardIds), so you can answer without a second call; pass expand to choose different capabilities. primary refreshes that card's readings from the device, so the answer is current. Always state the value in words: a FRESH reading is current; a STALE reading is the last known value, so say it is last known and give its age.

Required scope

endpoint:read

Input

Fields
enablementstring

Filter by ENABLED (default), DISABLED, or * for both. This filter is preserved by pagination.

Default: ENABLED

Allowed values: ENABLED, DISABLED, *.

endpointIdstring

Return one endpoint by its full Port OS identifier. Cannot be combined with other filters or pagination. Results advertise its declared command and outbound message IDs.

expandarray<string>

Select observations to add to each device result, for example ["power", "connectivity"] or ["battery"]. Use capability names or full namespaces declared by the device. This reads attributes; it does not send commands or broaden the device search. Short names use port1/systems/zero/capability-interfaces. endpoint_show already includes cached readings for the cards it lists; expand replaces that selection.

forceDeviceAttributeQueryboolean

Read selected attributes from devices instead of cache. Requires nonempty expand. Failed reads remain unavailable.

maxResultsinteger

Maximum number of results (default 10, maximum 100).

minimum: 1

nextTokenstring

Opaque cursor returned by a previous endpoint_query call.

primarystring

The card to lead with, one of the device's card ids (shown as cardIds in the result), for example battery, fan, closure, thermostat, camera or remote; house-map for a vacuum's map or room picking (never draw your own map). Needs endpointId. Every other card stays behind the details toggle.

queryobject

Optional field-first filter. Omit it to load full context; filter only when the account is large. Each key is a field or a combinator, and all keys of one object must match: {"name": {"like": "living"}, "type": {"in": ["LIGHT", "SWITCH"]}}. Combinators: {"and": [query, ...]}, {"or": [query, ...]}, {"not": query}. Text operators: eq (exact), in (any of a list), like (case-insensitive substring), lt and gt (lexical order). List operators: has (contains the exact value), like (some value contains the substring, case-insensitive). Fields: the fields your connected devices declare, listed in the tool description returned by tools/list.

Result

Fields
(payload)object

Manage Rooms and Device Groups

Open tool page →
TOOL group_manage

Organize rooms and device groups: create, rename, change members, enable, disable, merge or delete them.

To hide a discovered group (such as a robot's room) for good, disable it with SET_ENABLEMENT: rediscovery may recreate a deleted discovered group but never re-enables a disabled one. This tool never performs physical control; use control to act on devices.

MERGE_INTO and DELETE_GROUP are destructive: describe exactly which groups will be merged or deleted and get the user's explicit confirmation before calling, and never infer that consent from an earlier request. Read each group with group_query first and pass its current etag; a stale etag fails with PRECONDITION_FAILED, so re-read and confirm again rather than retrying blindly.

Operations in one call apply atomically: either every operation commits or none does. Set validateOnly=true to check a batch without writing. idempotencyKey (required unless validateOnly) is a fresh unique string per intended change; reuse the same key only to retry that same request after an unknown outcome, which then returns the original result.

The result is the Port OS group management envelope: status COMMITTED or FAILED, results correlated by requestId, and errors listing every failing operation with code, family and message.

Required scope

group:manage

Input

Fields
idempotencyKeystring

Unique key for this intended change, at most 255 characters. Required unless validateOnly is true.

operationsarray<EndpointGroupsManageOperation>Required

Ordered operations applied atomically.

validateOnlyboolean

Validate and authorize the batch and report what would happen without writing.

Result

Fields
statusstringRequired

Outcome of an atomic batch. `COMMITTED` means every operation was applied (or, for a validate-only request, would be applied); `FAILED` means nothing was written and `errors` lists every failing operation.

Allowed values: COMMITTED, FAILED.

resultsarray<EndpointGroupsManageResult>Required
errorsarray<BatchItemError>Required

Errors

A failed call returns this error object as its result instead.

Fields
familystringRequired

The broad class of an error. The family decides the HTTP status of a REST error, so clients can handle every code of a family alike.

codestringRequired

The specific error, one of a closed set of Port OS codes. Every REST error body, MCP tool error, batch item error and discovery item error uses this enum; each code belongs to an `ErrorFamily` that decides its HTTP status. Provider-specific codes are never codes: they travel in `details.providerCode`. New failure kinds are added here, never as free strings.

messagestringRequired

Plain-language description of the failure and the suggested next action.

detailsErrorDetails

Optional typed context for an error. Fields are additive and only populated when the error can safely expose that context to API clients.

errorsarray<SynchronizationItemError>

Every rejected item when a request that is validated item by item and applied atomically fails, such as a discovery `SynchronizationRequest` whose routes, group routes or relationships are rejected. Omitted for single-item failures.

Find Rooms and Device Groups

Open tool page →
TOOL group_query

Find rooms, floors, zones, homes and device groups, with their members and supported controls.

Returns canonical IDs, names, etags, spatial roles, parent paths, children, member devices, controllers and providers. Call it without arguments first to load full context and follow every paginationContext.nextToken; filter with query only when the account is large.

Controllers are the endpoints that can act on the group, with the message IDs that accept it: to clean a room, call control on the controller endpoint with one of those message IDs and payload {"groupIds": [<group ID>]}.

Messages are message IDs the group itself accepts: send one with control, using the group ID as id, and Port OS dispatches it to the provider's group. Room cleaning is not a group message; use the controller as above. If two groups match a spoken room name, ask the user which one, naming each group's parentPath.

Pass id to read one group; a merged group ID resolves to the surviving group and reports redirectedFrom.

To show a room map or let someone pick rooms, call endpoint_show on the vacuum (controller) with primary house-map; never draw a map yourself from spatial geometry.

Expand accepts capability names as in endpoint_query (for example ["speaker","media-player"]); forceDeviceAttributeQuery refreshes those observations. Read route attribute status before trusting a value: omitted or failed fresh values are unavailable.

Each route's membershipComplete is provider-declared: false means incomplete or unreported, and absent means unknown. members lists resolved endpoints, so an empty list does not prove a provider group has no members.

Disabled groups are hidden unless enablement is DISABLED or *; they cannot be targeted, and group_manage SET_ENABLEMENT enables them again. Copy group IDs and etags verbatim into control and group_manage.

Required scope

group:read

Input

Fields
enablementstring

Filter by ENABLED (default), DISABLED, or * for both. This filter is preserved by pagination; id reads ignore it.

Default: ENABLED

Allowed values: ENABLED, DISABLED, *.

expandarray<string>

Select declared capabilities whose route observations to return, for example ["speaker", "media-player"]. Requires id. This adds state readings to the selected group; it does not expand group membership or send commands. Expanding spatial returns raw room geometry for reading only. To show a map or let someone pick rooms, call endpoint_show on the vacuum with primary house-map; never draw one yourself.

forceDeviceAttributeQueryboolean

Requires id and nonempty expand; refresh provider state before returning route observations.

idstring

Return one group by its full group ID. Cannot be combined with query, maxResults or nextToken.

maxResultsinteger

Maximum number of groups (default 25, maximum 100).

minimum: 1

nextTokenstring

Opaque cursor returned by a previous group_query call with the same query and maxResults.

queryobject

Optional field-first filter. Omit it to load full context; filter only when the account is large. Each key is a field or a combinator, and all keys of one object must match: {"role": {"eq": "ROOM"}, "name": {"like": "kitchen"}}. Combinators: {"and": [query, ...]}, {"or": [query, ...]}, {"not": query}. Text operators: eq (exact), in (any of a list), like (case-insensitive substring), lt and gt (lexical order). List operators: has (contains the exact value), like (some value contains the substring, case-insensitive). Fields: the fields your connected devices declare, listed in the tool description returned by tools/list.

Result

Fields
paginationContextobject
redirectedFromstring
resultsarray<object>Required

Errors

A failed call returns this error object as its result instead.

Fields
familystringRequired

The broad class of an error. The family decides the HTTP status of a REST error, so clients can handle every code of a family alike.

codestringRequired

The specific error, one of a closed set of Port OS codes. Every REST error body, MCP tool error, batch item error and discovery item error uses this enum; each code belongs to an `ErrorFamily` that decides its HTTP status. Provider-specific codes are never codes: they travel in `details.providerCode`. New failure kinds are added here, never as free strings.

messagestringRequired

Plain-language description of the failure and the suggested next action.

detailsErrorDetails

Optional typed context for an error. Fields are additive and only populated when the error can safely expose that context to API clients.

errorsarray<SynchronizationItemError>

Every rejected item when a request that is validated item by item and applied atomically fails, such as a discovery `SynchronizationRequest` whose routes, group routes or relationships are rejected. Omitted for single-item failures.

Cancel Subscription

Open tool page →
TOOL subscription_cancel

Stop watching by cancelling one Port OS event subscription using its exact ID from subscription_list or subscription_inspect.

Cancellation is idempotent. Select the intended subscription by name, source endpoint and catalog event; names are not cancellation keys. A stopped monitor requires a new subscription to watch again.

Required scope

subscription:write

Input

Fields
idstringRequired

Exact subscription ID returned by subscription_list. Never use a display name or endpoint ID.

maxLength: 2048

minLength: 1

pattern: "\\S"

Result

Fields
idstringRequired
statusanyRequired

const: "stopped"

Errors

A failed call returns this error object as its result instead.

Fields
familystringRequired

The broad class of an error. The family decides the HTTP status of a REST error, so clients can handle every code of a family alike.

codestringRequired

The specific error, one of a closed set of Port OS codes. Every REST error body, MCP tool error, batch item error and discovery item error uses this enum; each code belongs to an `ErrorFamily` that decides its HTTP status. Provider-specific codes are never codes: they travel in `details.providerCode`. New failure kinds are added here, never as free strings.

messagestringRequired

Plain-language description of the failure and the suggested next action.

detailsErrorDetails

Optional typed context for an error. Fields are additive and only populated when the error can safely expose that context to API clients.

errorsarray<SynchronizationItemError>

Every rejected item when a request that is validated item by item and applied atomically fails, such as a discovery `SynchronizationRequest` whose routes, group routes or relationships are rejected. Omitted for single-item failures.

Inspect Subscription

Open tool page →
TOOL subscription_inspect

Inspect one Port OS event subscription by its exact ID returned by subscription_list.

Returns its safe query, source endpoint, catalog name and lifecycle status. A retained active subscription establishes registration; it does not prove that any client has received or acted on a camera event.

Required scope

subscription:read

Input

Fields
idstringRequired

Exact subscription ID returned by subscription_list. Never use a display name or endpoint ID.

maxLength: 2048

minLength: 1

pattern: "\\S"

Result

Fields
catalogNamestringRequired
endpointIdstringRequired
expiresAtstring | nullRequired

format: "date-time"

generationintegerRequired
idstringRequired
nameobjectRequired
queryobjectRequired
reasonCodestring
revisionintegerRequired
statusstringRequired

Errors

A failed call returns this error object as its result instead.

Fields
familystringRequired

The broad class of an error. The family decides the HTTP status of a REST error, so clients can handle every code of a family alike.

codestringRequired

The specific error, one of a closed set of Port OS codes. Every REST error body, MCP tool error, batch item error and discovery item error uses this enum; each code belongs to an `ErrorFamily` that decides its HTTP status. Provider-specific codes are never codes: they travel in `details.providerCode`. New failure kinds are added here, never as free strings.

messagestringRequired

Plain-language description of the failure and the suggested next action.

detailsErrorDetails

Optional typed context for an error. Fields are additive and only populated when the error can safely expose that context to API clients.

errorsarray<SynchronizationItemError>

Every rejected item when a request that is validated item by item and applied atomically fails, such as a discovery `SynchronizationRequest` whose routes, group routes or relationships are rejected. Omitted for single-item failures.

Edit Subscription Label

Open tool page →
TOOL subscription_label_edit

Change only the display name of one Port OS event subscription by exact ID.

Use a PLAIN name-value object. The event, endpoint, filter and destination are immutable; to change what is watched, establish a replacement monitor and cancel the old ID.

Required scope

subscription:write

Input

Fields
idstringRequired

Exact subscription ID returned by subscription_list. Never use a display name or endpoint ID.

maxLength: 2048

minLength: 1

pattern: "\\S"

nameobjectRequired

Result

Fields
catalogNamestringRequired
endpointIdstringRequired
expiresAtstring | nullRequired

format: "date-time"

generationintegerRequired
idstringRequired
nameobjectRequired
queryobjectRequired
reasonCodestring
revisionintegerRequired
statusstringRequired

Errors

A failed call returns this error object as its result instead.

Fields
familystringRequired

The broad class of an error. The family decides the HTTP status of a REST error, so clients can handle every code of a family alike.

codestringRequired

The specific error, one of a closed set of Port OS codes. Every REST error body, MCP tool error, batch item error and discovery item error uses this enum; each code belongs to an `ErrorFamily` that decides its HTTP status. Provider-specific codes are never codes: they travel in `details.providerCode`. New failure kinds are added here, never as free strings.

messagestringRequired

Plain-language description of the failure and the suggested next action.

detailsErrorDetails

Optional typed context for an error. Fields are additive and only populated when the error can safely expose that context to API clients.

errorsarray<SynchronizationItemError>

Every rejected item when a request that is validated item by item and applied atomically fails, such as a discovery `SynchronizationRequest` whose routes, group routes or relationships are rejected. Omitted for single-item failures.

List Subscriptions

Open tool page →
TOOL subscription_list

Enumerate the user's Port OS event subscriptions, including their exact IDs, names, source endpoint, catalog event and status.

For requests to stop watching a camera, list subscriptions and follow every nextCursor, select the intended monitor, then use subscription_cancel with its exact ID. Creating a monitor uses the host's events/subscribe capability after discovering supported camera events; these tools never accept callback URLs or signing keys.

Required scope

subscription:read

Input

Fields
cursorstring

Opaque nextCursor from the preceding subscription_list page. Omit for the first page.

maxLength: 4096

minLength: 1

pattern: "\\S"

Result

Fields
nextCursorstring
subscriptionsarray<object>Required

Errors

A failed call returns this error object as its result instead.

Fields
familystringRequired

The broad class of an error. The family decides the HTTP status of a REST error, so clients can handle every code of a family alike.

codestringRequired

The specific error, one of a closed set of Port OS codes. Every REST error body, MCP tool error, batch item error and discovery item error uses this enum; each code belongs to an `ErrorFamily` that decides its HTTP status. Provider-specific codes are never codes: they travel in `details.providerCode`. New failure kinds are added here, never as free strings.

messagestringRequired

Plain-language description of the failure and the suggested next action.

detailsErrorDetails

Optional typed context for an error. Fields are additive and only populated when the error can safely expose that context to API clients.

errorsarray<SynchronizationItemError>

Every rejected item when a request that is validated item by item and applied atomically fails, such as a discovery `SynchronizationRequest` whose routes, group routes or relationships are rejected. Omitted for single-item failures.

Resources

Each resource below is a document your client reads with resources/read, with the URI it is read from and the content type it returns.

Capability resources describe messages and payloads.

See the capability reference for customer-readable descriptions.

Capability interface

RESOURCE portos://capability-interfaces/{interfaceName}/{version}

A Port OS capability interface definition. Returns the interface specification including supported messages and attributes. Message input schemas are not returned.

Content typeapplication/yaml

Endpoint widget

RESOURCE ui://portos/endpoint/build-{sha256}.html

Interactive endpoint controls and observations.

Content typetext/html;profile=mcp-app
Capabilities Previous Pagecontrol Next Page