API and code examples

Choose a programmatic interface

Use the /mcp tools for device automation: they provide discovery, parameter schemas and remote-session management. Workspace web endpoints such as /api/devices use a signed-in user identity; they are not a general device REST API accepting every mk_ key.

The example below runs in a trusted local or server-side Node.js environment using the v1 MCP TypeScript SDK. Create a key with at least devices.list and copy the real endpoint from MCP management. See the MCP TypeScript SDK v1 documentation.

Run a read-only query

Install the SDK in your example project:

npm install @modelcontextprotocol/sdk@1

Use your local credential tool or runtime environment to provide AGENTWAN_MCP_URL and AGENTWAN_KEY: the actual HTTPS MCP endpoint and complete key. Save the following as list-devices.mjs:

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';

const endpoint = process.env.AGENTWAN_MCP_URL;
const key = process.env.AGENTWAN_KEY;
if (!endpoint || !key) throw new Error('Missing MCP endpoint or key');
const url = new URL(endpoint);
if (url.protocol !== 'https:') throw new Error('Use an HTTPS endpoint');

const client = new Client({ name: 'device-reader', version: '1.0.0' });
try {
  await client.connect(
    new StreamableHTTPClientTransport(url, {
      requestInit: { headers: { Authorization: `Bearer ${key}` } },
    })
  );
  const { tools } = await client.listTools();
  if (!tools.some((tool) => tool.name === 'devices_list')) {
    throw new Error('This key needs devices.list permission');
  }
  const result = await client.callTool({
    name: 'devices_list',
    arguments: {},
  });
  if (result.isError)
    throw new Error('Device query failed; review client diagnostics');
  console.log(JSON.stringify(result.content, null, 2));
} finally {
  await client.close();
}

Run node list-devices.mjs. This only reads the device list; it does not open a desktop or terminal session. The output can contain workspace information, so review it locally. Keep headers and complete keys out of logs.

Interpret results and errors

MCP tool results use content, and operation failures can be indicated by isError. Checking HTTP status alone is insufficient. Connection failures may throw in the client and should be handled separately from tool execution failures.

See MCP setup for coordinate actions, file replacement and session cleanup rules.

Building a low-level controller

POST /api/credentials/exchange accepts a workspace Bearer key to request a short-lived operation ticket for a device and scope. Write operations also involve an action digest. Browser-session callers supply tenantId; key authentication derives the workspace from the key.

The response contains a credential for the connection flow, not the result of a completed device operation. Tickets have an activation deadline and are single-use. Do not cache, log or reuse them as permanent keys. A complete controller must also implement the activation and channel contracts. For most integrations, use the MCP client above to handle connection and invocation.