MCP server

Let an AI assistant look up your device fleet and policies, and optionally send commands to your devices and propose policy changes, using Sign in with Nomid or a Nomid API key.

What the MCP server does

The Model Context Protocol (MCP) is an open standard that lets AI assistants call tools in other systems. The Nomid MCP server lets an assistant such as claude.ai, ChatGPT, Claude Code, Codex or Cursor answer questions about your fleet in plain language, for example how many devices use a policy or which devices have not synced since a given date, without anyone opening the portal. It can also diagnose why a device cannot be reached remotely, is out of sync or fails to enroll, find where an app is, read the company's own plan, link to a page in the portal, and look up Nomid's public plans and list prices. With an extra permission it can send commands to one or several devices, such as lock, reboot or change policy, propose policy changes, or create provisioning QR codes. A separate permission allows destructive commands such as wipe, one device per call.

Endpoint and transport

POST https://mcp.nomid.tech/emm/api/mcp

The server uses MCP Streamable HTTP in stateless mode. Every JSON-RPC call is an independent HTTPS request, so there is no session to keep alive and no event stream to hold open.

Tool calls require Sign in with Nomid (OAuth) or an API key. Send an API key as an Authorization: Bearer token or in the X-API-Key header. Initialization, ping and the tool catalog are available without credentials. Tool calls without credentials, and requests with invalid or expired credentials, return 401.

The API key or the Sign in with Nomid connection decides which companies the assistant can reach. An API key or a connection made for one company sees only that company's devices and policies. A connection made with All companies I manage reaches every company the user manages: list_companies lists them, and every other tool takes an optional company argument to work in one of them.

Sign in with Nomid

Sign in with Nomid is OAuth for MCP clients, open to every company. Instead of using a key, the user signs in to Nomid in the browser and approves what the assistant may do. The assistant then acts as that user, in the company picked on the consent page, and sees only the devices and policies the user's role and policy access allow.

claude.ai, ChatGPT and Claude Code connect with Sign in with Nomid: add the endpoint URL above as a custom connector or MCP server, without a key, and sign in when the client asks. The Codex and Cursor examples below use an API key.

In Claude Code, add the server without a header, then run /mcp in Claude Code and select the server to sign in.

claude mcp add --transport http nomid-mdm https://mcp.nomid.tech/emm/api/mcp

A connection carries OAuth scopes, which take the place of API key permissions.

ScopeWhat it allows
mcp:readThe read tools. The user's role needs permission to view devices, policies or the library; each tool still needs its own.
mcp:devices:commandsend_device_command and the clear_app_data command of send_destructive_command. Needs the company's device commands setting and a user who is allowed to send device commands.
mcp:devices:destructiveThe other commands of send_destructive_command. Needs the company's destructive commands setting and a user who is allowed to send device commands.
mcp:provisioningcreate_provisioning_qr_code. Needs the company's provisioning setting and a user who is allowed to provision devices and view policies.
mcp:policies:writeThe policy change tools. Needs the company's policy changes setting and a user who is allowed to edit and view policies. Granting it also grants mcp:read.

Clients that follow the server's sign-in challenge ask for mcp:read, mcp:devices:command and mcp:provisioning. A client that sends no scope gets mcp:read only. mcp:devices:destructive and mcp:policies:write are never requested automatically: a client has to ask for them explicitly.

On the consent page the user can untick scopes, and Nomid drops any scope the user's role or the company's AI agent access settings do not allow. Approving a command, destructive or policy change scope needs a recent sign-in.

Every request checks the connection again. If the user loses access to the company or the role permissions a tool needs, or the company turns off AI agent access, requests are refused while that lasts.

On the consent page, a user with more than one company can choose All companies I manage. The connection then reaches every company the user could connect one by one, with the same access as a single-company connection there, and the user's role and that company's AI agent access settings apply in each. list_companies lists those companies with their device counts, and every other tool takes an optional company argument with a company value from that list; without it, a tool runs in the connection's own company. Naming a company out of reach, or one that does not exist, is the same tool error. A connection made for one company that names another is told to reconnect with All companies I manage. Rate limits stay per connection, whatever the company.

Create an API key

The MCP server uses the same API keys as the REST API. Create a dedicated key for each assistant so you can revoke it without affecting other integrations.

  1. 1

    In the Nomid portal, open Settings and select the API tab.

  2. 2

    Click Create API Key and enter a name that identifies the assistant, for example Claude Code read-only.

  3. 3

    Choose the permissions described below. If you want the key to stop working on a given date, set an expiration date.

  4. 4

    Copy the key when it is shown. It is displayed only once.

Read-only key

Enable the device and policy read permissions (DEVICES_READ and POLICIES_READ). This is enough for every read tool and is the recommended starting point.

Command key

To let the assistant send device commands, also enable the device command permission (DEVICES_COMMAND). A command key must also have DEVICES_READ, and changing a device's policy also needs POLICIES_READ. Only a portal user who is allowed to send device commands and has access to all policies can create a key with this permission.

Destructive command key

To let the assistant wipe a device, reset or change its screen lock, relinquish ownership or uninstall apps, enable the destructive device command permission (DEVICES_COMMAND_DESTRUCTIVE) with DEVICES_READ. The company must also turn on destructive commands under AI agent access in the portal. The same portal user rules apply as for a command key.

Provisioning key

To let the assistant create provisioning QR codes, enable the provisioning permission (PROVISIONING) with POLICIES_READ. Only a portal user who is allowed to provision devices and has access to all policies can create a key with this permission.

Connect your assistant

Store the key in an environment variable named NOMID_API_KEY and never commit it to a repository. The URL in each example is the production endpoint.

Claude Code

Run this once in your shell. Your shell expands the variable when you run the command, and Claude Code then stores the resulting key in plain text in its own configuration file. Use a dedicated read-only key for this.

claude mcp add --transport http nomid-mdm https://mcp.nomid.tech/emm/api/mcp \
  --header "Authorization: Bearer ${NOMID_API_KEY}"

Codex

Add this to ~/.codex/config.toml. Codex reads the token from the named environment variable. It does not expand variables written inside the file.

[mcp_servers.nomid]
url = "https://mcp.nomid.tech/emm/api/mcp"
bearer_token_env_var = "NOMID_API_KEY"

Cursor

Add this to .cursor/mcp.json. Cursor expands environment variables in the header value, as shown.

{
  "mcpServers": {
    "nomid-mdm": {
      "url": "https://mcp.nomid.tech/emm/api/mcp",
      "headers": {
        "Authorization": "Bearer ${env:NOMID_API_KEY}"
      }
    }
  }
}

Other clients

Any MCP client that supports Streamable HTTP servers with custom headers can connect with the endpoint URL and an Authorization: Bearer header.

Available tools

Every tool runs in the company of the key or connection, or in the one its company argument names. A device is identified by its assetId, which is the pathName returned by search_devices and get_device. A policy is identified by its policyId, which is the pathName returned by list_policies. Where several capabilities share a tool, the tables show the tool and, under it, the argument that chooses the capability.

Read tools

Read tools never change anything. Most return the same data as the matching REST endpoints. diagnose, find_app, search_library, get_company_plan, list_companies, get_portal_link, search_nomid_site and the query argument of search_devices have no REST equivalent.

ToolRequired permissionWhat it does
search_devicesDEVICES_READSearch devices with optional status, policy, lastSyncBefore, lastSeenBefore and missing filters. lastSyncBefore is the portal's Last sync: use it for devices not seen or offline since a date. lastSeenBefore is when the asset record was last updated, which does not prove a device is offline. missing finds devices without an IMEI or a serial number. Results are paged: page starts at 0, and size defaults to 10 with a maximum of 25. fields set to names returns a compact table of what matches instead. To find a device the user names, pass query alone (2 to 100 characters), which matches name, serial number, IMEI, model or tag. It cannot be combined with the filters or page. It returns up to size best matches, each with its pathName and matchedField, and truncated says whether more matched.
count_devicesDEVICES_READCount devices with the same optional filters, or with policies for several policies at once. groupBy (policy, model, status) breaks the count down exactly across the whole fleet, largest groups first.
get_deviceDEVICES_READFull detail for one device, including battery level, hardware memory and storage totals, and policy non-compliance reasons.
get_fleet_summaryDEVICES_READAggregate fleet numbers: total devices, a breakdown by status and a security posture summary. It never returns a device list.
list_device_commandsDEVICES_READThe most recent commands sent to a device, newest first, with type, status, timestamps, a short outcome code and who sent them: requestedByType USER names a portal user by email in requestedBy, and API_KEY names an integration by its key's name. limit defaults to 20 and is capped at 50. Command payloads are never returned.
list_policiesPOLICIES_READList policies. Returns an overview only, without configuration detail.
GET /policies/{policyId}REST only, not an MCP toolPOLICIES_READOverview of one policy.
diagnosearea: "remote_access" or "policy_sync"DEVICES_READDiagnose a problem in one call, chosen with area. remote_access (with assetId): why a device cannot be reached or controlled remotely. policy_sync (with assetId): whether a device is in sync, with its current policy version applied and its required apps and the Nomid agent installed, and its screenshot state. enrollment (with policyId, serialNumber or both): why Android devices fail to enroll with a QR code. Returns findings (likely causes, most likely first, each with evidence and a next step) and unknowns (what to ask the user about), plus deviceChecks for enrollment (what only the person holding the device can check). It never returns credentials, keys or remote access IDs. remote_access and policy_sync need DEVICES_READ; enrollment needs POLICIES_READ.
get_portal_linkDEVICES_READ / POLICIES_READThe Nomid portal URL of a device (kind asset, by assetId), a policy (kind policy, by policyId), a library app (kind app, by package name) or a fixed page (kind page, by its key, such as dashboard, devices, policies, library, ai_agents or billing). A device needs DEVICES_READ; a policy or an app needs POLICIES_READ; a page needs any read permission. An object that does not exist in the company returns a tool error. The link only opens the page: the portal still applies the signed-in user's own permissions.
search_nomid_siteDEVICES_READ / POLICIES_READSearch Nomid's public website for plans and pricing: the plans and their device limits, list prices per Android and VR device in USD, EUR and BRL, what each plan includes and the pricing FAQ. locale is optional: en, es or pt. Returns up to 5 excerpts with their page URL. These are public list prices, not the company's own contract or invoice. Any one read permission is enough.
list_device_user_loginsDEVICES_READDevice User sessions, newest first, with the filters of GET /device-user-logins: who logged in on which asset, when, and who reported the login and the logout. Follows the caller's policy scope. Tool error if the asset is not found. Device User sessions API

Command tools

These commands go through send_device_command, chosen with its command argument, and run on real devices right away. Pass exactly one target: assetId for one device, assetIds for up to 50, or devicesInPolicy for every device of a policy that can take commands (at most 50; a larger policy is refused). For several devices, make one call with all of them, never one call per device. A device that cannot take the command does not stop the others: the result lists each device's outcome (SENT, NOT_SENT, UNCONFIRMED or FAILED), and retryAssetIds lists the NOT_SENT devices, which are safe to send again. Each needs DEVICES_COMMAND, and change_device_policy also needs POLICIES_READ. clear_app_data needs the same permission, but it erases data, so it goes through send_destructive_command, one device per call.

ToolRequired permissionWhat it does
send_device_commandcommand: "lock_device"DEVICES_COMMAND + DEVICES_READLock the device screen immediately. The user can unlock it normally.
send_device_commandcommand: "start_lost_mode"DEVICES_COMMAND + DEVICES_READLock the device and show a message, with optional contact details, on its lock screen. message is required and can be up to 4096 characters. phoneNumber, email, streetAddress and organization are optional.
send_device_commandcommand: "stop_lost_mode"DEVICES_COMMAND + DEVICES_READEnd lost mode. Nothing happens, and no error is returned, if the device was not in lost mode.
send_device_commandcommand: "send_device_message"DEVICES_COMMAND + DEVICES_READShow a plain-text push notification on the device. title (up to 60 characters) and body (up to 500 characters) are both required. Sending the same message again shows a second notification.
send_device_commandcommand: "request_status_report"DEVICES_COMMAND + DEVICES_READAsk the device to send a fresh status report now. The report arrives later: read it with get_device.
send_device_commandcommand: "force_location_update"DEVICES_COMMAND + DEVICES_READAsk the device to report its current location now. The location arrives later: read it with get_device.
send_device_commandcommand: "sync_policy"DEVICES_COMMAND + DEVICES_READSend the device its current policy again. Devices managed by the Nomid agent (AOSP) only. Android Management devices receive policy changes automatically.
send_device_commandcommand: "reboot_device"DEVICES_COMMAND + DEVICES_READRestart the device now. Whoever is using it is interrupted, and unsaved work may be lost.
send_device_commandcommand: "shutdown_device"DEVICES_COMMAND + DEVICES_READPower the device off now. It cannot be turned back on remotely. Devices managed by the Nomid agent (AOSP) only.
send_device_commandcommand: "launch_app"DEVICES_COMMAND + DEVICES_READOpen an installed app on the device by its packageName. Devices managed by the Nomid agent (AOSP) only.
send_destructive_commandcommand: "clear_app_data"DEVICES_COMMAND + DEVICES_READDelete all data of the apps in packageNames (1 to 20 package names), as if they had just been installed. It cannot be undone. Android Management devices only.
send_device_commandcommand: "change_device_policy"DEVICES_COMMAND + DEVICES_READ + POLICIES_READMove the device to another policy of the company, given by policyId. Anything only the current policy had is removed. Fails if the device already uses that policy. Also needs POLICIES_READ.

Destructive command tools

ToolRequired permissionWhat it does
send_destructive_commandcommand: "wipe_device"DEVICES_COMMAND_DESTRUCTIVE + DEVICES_READRemove the device from management and erase its managed data. A company-owned device is factory reset: every app and all data on it are erased. On a personally owned device with a work profile, only the work profile and its apps and data are removed; personal apps and data stay. Irreversible.
send_destructive_commandcommand: "reset_screen_lock"DEVICES_COMMAND_DESTRUCTIVE + DEVICES_READRemove the device's screen lock (PIN, pattern or password), so it can be unlocked without one. Android Management devices only.
send_destructive_commandcommand: "change_screen_lock_password"DEVICES_COMMAND_DESTRUCTIVE + DEVICES_READSet a new screen lock password, given as newPassword (4 to 128 characters, no leading or trailing spaces). The device locks, and only the new password unlocks it. The password is never stored, returned or logged. Android Management devices only.
send_destructive_commandcommand: "relinquish_ownership"DEVICES_COMMAND_DESTRUCTIVE + DEVICES_READRelease a company-owned device to its user. The work profile and its data are removed, and the device is no longer managed. Irreversible.
send_destructive_commandcommand: "uninstall_apps"DEVICES_COMMAND_DESTRUCTIVE + DEVICES_READUninstall the apps in packageNames (1 to 20 package names) with their data, never the Nomid agent. It runs when the device next checks in, even days later: follow it with list_device_commands. An app its policy installs comes back on the next sync: to keep it off, block it in the policy. Devices managed by the Nomid agent (AOSP) only, agent version 4.5.20 or later.

MCP clients that connect with Sign in with Nomid instead of an API key need the mcp:devices:command scope for send_device_command and for clear_app_data, and mcp:devices:destructive for the other commands of send_destructive_command.

Which devices can receive commands

  • Only enrolled devices can receive commands (status ACTIVE, INACTIVE or SYNCHRONIZING). Deleted, reprovisioned and unenrolled assets are rejected.
  • Some commands work only on one kind of device. Lock, lost mode, clear_app_data, reset_screen_lock and change_screen_lock_password need an Android Management (Google-managed) device. sync_policy, shutdown_device, launch_app and uninstall_apps need a device managed by the Nomid agent (AOSP). Other devices get a tool error.
  • A message is a push notification to the Nomid agent on the device, so the device needs a registered push token.
  • An asset that belongs to another company behaves exactly like an asset that does not exist.

Not available through MCP or the REST API: starting remote access sessions, and listing or revoking enrollment tokens. A provisioning QR code creates its own enrollment token. Policy changes have their own propose-and-apply flow.

Provisioning tool

Each call creates a new enrollment token, so the assistant should create a QR code only when the user asks for one, and never reuse an older one.

ToolRequired permissionWhat it does
create_provisioning_qr_codePROVISIONING + POLICIES_READCreate a QR code that enrolls a new or factory-reset Android device into the company with the policy given by policyId. personalUsage and a Wi-Fi network for setup (wifiSsid, wifiPassword, wifiSecurity, wifiHidden) are optional. The code stops working 24 hours after it is created. VR-only policies cannot be provisioned with a QR code.

The QR code comes back as an MCP image block next to the text result, so the client can show it to the user. The text result gives policyId, policyName, personalUsage, expiresAt and, when a network was given, wifiSsid. It never contains the enrollment token or the Wi-Fi password.

Sign in with Nomid connections need the mcp:provisioning scope and the company's provisioning setting under AI agent access. An API key with PROVISIONING does not need that setting.

Provisioning QR codes API

Policy changes

Every change takes two steps. First you propose it: the API records a proposal and returns its change list, with each setting's current and new value, the impact and when the proposal expires. Nothing changes on the policy yet. Then, after the person responsible has reviewed the change list, you apply a NORMAL proposal by its proposalId, and a person approves a HIGH proposal in the Nomid portal.

ToolRequired permissionWhat it does
get_policy_settingsPOLICIES_READRead a policy's editable settings with their current and allowed values, and its apps.
get_policy_documentPOLICIES_READRead a policy's full configuration as JSON, or one part of it by path, with secrets hidden and the fields that cannot be changed listed.
list_policy_revisionsPOLICIES_READList a policy's saved revisions, newest first.
get_policy_revision_documentPOLICIES_READRead an exact saved policy revision from list_policy_revisions using policyId and its positive 64-bit revision ID. Optional company selects an authorized company; JSON Pointer path selects a part, and fromIndex continues an object, array or long string. Omit path for the root, including apps; use numeric array indexes instead of current-document app package aliases. Secrets are redacted before selection and paging. Follow nextFromIndex at the same path or read narrower notShown paths. The result is historical and not editable; saved providerVersion does not prove a device applied it, and changedBy does not prove a person made the change.
get_policy_proposalPOLICIES_READRead a proposal made by the same key or connection, with its status.
propose_policy_changesettings partPOLICIES_WRITE + POLICIES_READPropose setting changes to an existing policy.
propose_policy_changeapps partPOLICIES_WRITE + POLICIES_READPropose adding apps to an existing policy (a Google Play or Nomid Store app by package name, or a web app for a URL), removing them, or changing how they are installed.
propose_policy_changeedits partPOLICIES_WRITE + POLICIES_READPropose changes to any editable part of an existing policy, such as Wi-Fi networks, password rules, restrictions, fences or an app's managed configuration, as JSON Pointer edits of the policy document.
create_policyPOLICIES_WRITE + POLICIES_READPropose a new policy, from scratch with Nomid's defaults or as a copy of an existing one, with optional setting changes.
rollback_policyPOLICIES_WRITE + POLICIES_READPropose restoring a policy to an earlier revision.
apply_policy_proposalPOLICIES_WRITE + POLICIES_READApply a pending proposal by its proposalId. A HIGH impact proposal is refused, and the error gives its approvalUrl.

An assistant must show the user the change list and get their explicit approval in the conversation before it calls apply_policy_proposal. For a HIGH impact proposal it does not call apply: it gives the user the proposal's approvalUrl and asks them to approve it in the Nomid portal. It reads the outcome with get_policy_proposal and does not ask the user to type anything.

Policy changes API

Set up devices with an AI agent

An assistant connected to the Nomid MCP server can set up a dedicated device fleet end to end, including kiosk mode, as long as the connection has the policy changes and provisioning permissions. It proposes every change, shows you the change list, and applies it only after you approve.

Where another section of this documentation says that kiosk mode, the kiosk app or the launcher dock stay in the portal, the homeScreen part of propose_policy_change described here applies. The portal remains available for the same settings.

Tool names on the server

The server offers one tool for each kind of action. Several capabilities named elsewhere on this page are called through a shared tool: device commands through send_device_command, wipe, screen lock and other irreversible commands through send_destructive_command, diagnosis through diagnose, and policy changes through propose_policy_change, which takes policyId and exactly one part: settings, apps, homeScreen, details or edits. create_policy, rollback_policy and apply_policy_proposal are tools of their own. get_policy is not an MCP tool: use list_policies, get_policy_settings and get_policy_document.

Tools added for setup tasks:

ToolWhat it does
propose_policy_changePart homeScreen switches the policy's home screen: STANDARD, NOMID_LAUNCHER, KIOSK_MULTI_APP or KIOSK_SINGLE_APP, with the kiosk app, the maintenance password, the launcher dock and the device's built-in apps. Part details changes the description, tags and policy group.
find_appWhere an app is: in the policy, the company's library, Google Play (by package name) or on a device. Use it to find the package name of the app to add before a kiosk is set up.
list_device_appsThe apps a device last reported, with package name, version and who installed them.
list_companiesThe companies a Sign in with Nomid connection can work in. Every other tool then accepts an optional company argument.
search_libraryThe company's Nomid library: published apps, and web links where the company has the VR library.
get_company_planThe company's own plan and billable device count. Prices and invoices stay in the portal.
diagnose_enrollmentPart of diagnose with area enrollment. Explains why Android devices fail to enroll with a QR code, checking the Wi-Fi in the saved codes first, then the policy and its enrollment tokens.

Setting up kiosk mode

The assistant follows these steps for tablets that should run one app or a fixed set of apps.

  1. 1

    Pick the policy. Create a new one with create_policy, or copy an existing one. A new policy has no devices yet, so its changes are not high impact.

  2. 2

    Add the apps with find_app and the apps part of propose_policy_change: Google Play or Nomid Store apps by package name, or a secure web app for a web address. Apply the proposal before the next step, because the kiosk app and the dock apps must already be in the policy.

  3. 3

    Switch the home screen with the homeScreen part: KIOSK_MULTI_APP shows the policy's apps in Nomid Kiosk, KIOSK_SINGLE_APP locks the device to the app named in kioskApp. A single-app kiosk is left only with a maintenance password of 6 to 64 characters that you provide. The assistant never invents one, and the password is never shown back.

  4. 4

    Adjust the kiosk controls, such as the status bar, navigation buttons, power button and device settings, with the edits part at /kioskCustomization. Read the current values with get_policy_document first. The dock can pin up to 6 apps.

  5. 5

    Review the change list, then approve it. A home screen change on a policy that already has devices is always high impact: the assistant gives you a link, and you approve it in the Nomid portal. A new policy has no devices, so the assistant applies its changes once you approve them in the conversation.

  6. 6

    Create the enrollment QR code with create_provisioning_qr_code, using personalUsage USERLESS for a dedicated device. The code is valid for 24 hours. On each new or factory-reset tablet, tap the welcome screen of the setup wizard six times, connect to Wi-Fi if asked, and scan the code.

  7. 7

    Check the result with search_devices, get_device and diagnose. If something is wrong, rollback_policy restores an earlier revision from list_policy_revisions, again as a proposal you approve.

Agent skills and discovery

Agents can install the nomid-kiosk-setup and nomid-mcp skills with the skills command-line tool pointed at www.nomidmdm.com. The skills index is at /.well-known/agent-skills/index.json, a capability summary is at /skill.md, and the MCP rules for agents are at /agents/nomid-mcp.md.

Safety and audit

A command changes something a person is holding. Treat each one as an action that needs a human decision.

  • Always confirm with the user before any command. The tool descriptions ask the model to do this, but nothing on the server enforces it. Keep your client's per-tool approval turned on for command tools instead of auto-approving them.
  • Never resend a command after an unconfirmed result. If the outcome is unknown, check list_device_commands after the device has had time to respond, and ask the user before sending again. A resend can duplicate a command that was already delivered, and a message shows a second notification.
  • A result that says the command was not sent is safe to retry. The command never left Nomid.
  • Every command is recorded in the device's command history in the Nomid portal. A command sent with an API key is attributed to the key, not to a person: the entry shows api-key, the key id and the key prefix. A command sent through a Sign in with Nomid connection is attributed to the user who signed in. The history that list_device_commands returns says who sent each command: a portal user by email, an integration by its key's name.
  • If a computer or configuration file is compromised, revoke the key from Settings, API. Revoked keys cannot be restored. To end a Sign in with Nomid connection, revoke it in the connections list of the AI agents page in the portal, or disconnect it in a client that revokes its tokens on disconnect. Either way the connection and all its tokens stop working at once. Each user can revoke their own connections, and a user who can manage API keys can revoke any connection of the company.

Rate limits

Limits are counted per API key, or per Sign in with Nomid connection, in fixed one-minute windows. When you exceed the MCP request limit, the server answers HTTP 429 Too Many Requests with a Retry-After header that gives the seconds until the window resets.

LimitAllowed
All MCP requests, every tool60 per minute per key or connection
Device commands, policy changes and provisioning QR codes, REST and MCP combined10 per minute per key or connection

A command tool call, each propose or apply call of a policy change tool, and each create_provisioning_qr_code call count against both limits. A command to several devices costs one request of the shared write limit per started group of 5 devices, so a call on 50 devices costs 10, and a call that does not fit what is left of the minute is refused whole before anything is sent. A command that needs DEVICES_COMMAND_DESTRUCTIVE also counts against its own limit of 5 per hour per key or connection. When a call exceeds one of these limits, the server returns a tool error instead of an HTTP 429. It is a normal response flagged as an error, and its text says how many seconds to wait. The REST read endpoints do not use the MCP limit.

Troubleshooting

SymptomLikely cause and fix
401 Unauthorized with an API keyThe key is missing, invalid, expired or revoked. Check that the client sends Authorization: Bearer followed by the key, and that the environment variable was set when you ran the setup command.
401 Unauthorized, or the client asks you to sign in again, with Sign in with NomidThe access token expired and could not be refreshed, or the connection was revoked. Requests are also refused while the user is no longer a member of the company, their role no longer allows any of the granted scopes, or the company has turned off AI agent access; a disabled user's connection is revoked. Sign in again or reconnect the connector. If it still fails, ask a company administrator to check your membership, your role and AI agent access in the portal.
Tool error saying the key lacks the required permission or the company has not enabled it (HTTP 403 on the REST API)The key was created without the permission this tool needs, or the company setting is off. send_device_command needs DEVICES_COMMAND and DEVICES_READ, and change_device_policy also needs POLICIES_READ. send_destructive_command needs DEVICES_COMMAND_DESTRUCTIVE and DEVICES_READ, and the company's destructive commands setting turned on; its clear_app_data command needs DEVICES_COMMAND and DEVICES_READ instead. Policy change tools need POLICIES_WRITE and POLICIES_READ, and the company's policy changes setting turned on. create_provisioning_qr_code needs PROVISIONING and POLICIES_READ.
Tool error saying you do not have the required permission, or that an administrator has not enabled AI agent access for it (Sign in with Nomid)The connection lacks the scope the tool needs, your role lacks the matching permission, or the company setting for it under AI agent access is off. Reconnect and approve the scope on the consent page; mcp:devices:destructive and mcp:policies:write appear only if the client asks for them. For a disabled setting, ask a company administrator to turn it on.
HTTP 429 Too Many Requests, or a tool error that says the rate limit was exceededYou exceeded a rate limit. For an HTTP 429, wait the number of seconds in the Retry-After header. For a tool error, wait the number of seconds its message gives.
Tool error about a device that was not found or cannot take the commandUse the pathName from search_devices as assetId. Check that the device is enrolled and that the command supports its device type (see Which devices can receive commands).
Tool error saying the outcome is unknownDo not resend. Check list_device_commands once the device has had time to respond, and ask the user before sending again.
The assistant does not list any Nomid toolsWith an API key, confirm that your client supports Streamable HTTP servers with custom headers, and that the URL matches the endpoint above exactly. With Sign in with Nomid, finish signing in, or disconnect the connector and connect it again. A signed-in connection lists every tool, so a missing scope shows up as a tool error, not as a missing tool.

Related documentation

Choose Your Time

Loading...
Open booking calendar