文档
API 与代码示例

文档/开发者接入

API 与代码示例

从一个只读设备查询开始,在自己的程序中调用 MCP,并正确处理权限和错误。

更新于 6 分钟阅读
本页内容

选择程序接入方式

设备自动化优先使用 /mcp 的工具接口:它提供工具发现、参数 schema 和远程会话管理。网页工作区的 /api/devices 等接口使用用户登录身份,并不是任意 mk_ Key 都能调用的通用设备 REST API。

下面的示例在可信的本地或服务端 Node.js 环境运行,使用 MCP TypeScript SDK 的 v1 接口。先创建至少包含 devices.list 的 Key,并从 MCP 管理页面复制实际服务地址。MCP TypeScript SDK v1 文档

运行一个只读查询

在示例项目中安装 SDK:

sh
npm install @modelcontextprotocol/sdk@1

通过本地凭据工具或运行环境注入 AGENTWAN_MCP_URLAGENTWAN_KEY。前者是实际 HTTPS MCP 地址,后者是完整 Key。将下面内容保存为 list-devices.mjs

js
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();
}

执行 node list-devices.mjs。示例只读取设备清单,不建立桌面或终端会话。设备清单可能包含工作区信息,请只在本地查看输出,日志中不要记录请求头或完整密钥。

理解结果与错误

MCP 工具结果使用 content,业务失败还可能通过 isError 表示;不要只检查 HTTP 状态。连接异常也可能由客户端抛出,需要和工具执行失败分别处理。

现象检查与处理
Unauthorized / 认证失败检查 Key 是否有效、过期、撤销或来源被阻止
工具不存在刷新工具目录,检查对应 scope 与功能是否启用
设备列表为空检查当前 Key 所属工作区与设备组授权
设备操作被拒绝检查成员权限、目标在线状态和能力
画面或会话过期重新截图或打开新会话,不能无限重放旧参数
请求被限流或暂时失败使用有上限的退避;修改操作先核对结果再重试

桌面坐标、文件覆盖和会话关闭规则见MCP 指南

需要自定义底层控制器时

POST /api/credentials/exchange 可使用工作区 Bearer Key 申请指定设备、scope 的短期操作票据;写操作还涉及动作摘要绑定。浏览器会话调用需额外提供 tenantId,Key 调用则从 Key 确定工作区。

该接口返回的是连接流程中的短期凭证,不是已经完成的设备操作结果。票据有激活期限且只能使用一次,不能缓存、记录或当成永久 API Key。完整控制器还需遵守激活与通道契约;一般集成请使用上面的 MCP 客户端完成连接和调用。

还需要帮助?

带上遇到的问题和操作步骤,我们会更容易定位。

联系支持