文档/开发者接入
API 与代码示例
从一个只读设备查询开始,在自己的程序中调用 MCP,并正确处理权限和错误。
本页内容
选择程序接入方式
设备自动化优先使用 /mcp 的工具接口:它提供工具发现、参数 schema 和远程会话管理。网页工作区的 /api/devices 等接口使用用户登录身份,并不是任意 mk_ Key 都能调用的通用设备 REST API。
下面的示例在可信的本地或服务端 Node.js 环境运行,使用 MCP TypeScript SDK 的 v1 接口。先创建至少包含 devices.list 的 Key,并从 MCP 管理页面复制实际服务地址。MCP TypeScript SDK v1 文档。
运行一个只读查询
在示例项目中安装 SDK:
npm install @modelcontextprotocol/sdk@1
通过本地凭据工具或运行环境注入 AGENTWAN_MCP_URL 和 AGENTWAN_KEY。前者是实际 HTTPS MCP 地址,后者是完整 Key。将下面内容保存为 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();
}
执行 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 客户端完成连接和调用。
带上遇到的问题和操作步骤,我们会更容易定位。