Earth Resources

Agent / MCP 接入手册

1. 连接方式

MCP 端点为：

POST/GET/DELETE https://resources.example.com/mcp

它实现 MCP Streamable HTTP，而不是自定义 JSON RPC。初始化响应返回 MCP-Session-Id；后续 POST、GET SSE 和 DELETE 必须携带该 header。所有请求都要发送 bearer token。可给管理员 token 增加 X-Tenant-Id，把会话固定到单一租户；租户 token（etk_）必须带 X-Tenant-Id，会话天然限定在本租户内。

通用 Agent 配置示例（字段名以所用 Agent 客户端为准）：

{
  "mcpServers": {
    "earth-resources": {
      "type": "streamable-http",
      "url": "https://resources.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${EARTH_RESOURCES_API_KEY}",
        "X-Tenant-Id": "acme"
      }
    }
  }
}

Node.js SDK 示例：

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

const client = new Client({ name: 'ops-agent', version: '1.0.0' });
const transport = new StreamableHTTPClientTransport(
  new URL('https://resources.example.com/mcp'),
  { requestInit: { headers: {
    Authorization: `Bearer ${process.env.EARTH_RESOURCES_API_KEY}`,
    'X-Tenant-Id': 'acme',
  } } },
);
await client.connect(transport);
console.log(await client.listTools());

2. 工具

| 工具 | 权限 | 作用 | | --- | --- | --- | | list_resources | 管理员、租户或本资源 | 列出资源与最新状态 | | get_resource | 管理员、租户或本资源 | 获取资源快照和最近遥测 | | query_resource_events | 管理员、租户或本资源 | 按可靠序号查询遥测与命令日志 | | get_fleet_summary | 管理员、租户或本资源 | 汇总在线、离线、仅注册资源数 | | send_resource_command | 管理员或租户 | 幂等地写入并下发资源命令 |

未使用 X-Tenant-Id 的全局管理员在每次工具调用中必须传 tenantId。租户 token 只能操作本租户，跨租户调用返回 tenant_forbidden。资源 token 只能读取自身；命令工具会返回权限错误。

调用示例：

const response = await client.callTool({
  name: 'query_resource_events',
  arguments: { resourceId: 'sensor-01', afterSequence: 128, limit: 50 },
});

await client.callTool({
  name: 'send_resource_command',
  arguments: {
    resourceId: 'sensor-01',
    eventId: 'agent-plan-2026-09-10-step-3',
    command: { action: 'sample', intervalSeconds: 5 },
  },
});

写操作应由 Agent 生成稳定 eventId。工具调用超时后重试同一 ID，避免同一计划步骤生成多条命令。建议 Agent 在执行前调用 get_resource，检查资源状态和命令有效期；高风险物理动作应在 Agent 层加入人工确认。

3. 会话和安全

  • MCP 会话绑定首次初始化时的 principal，不能换 token 接管。
  • 客户端结束时发送 DELETE 关闭会话。
  • 本服务使用静态 bearer token，不内置 OAuth 授权服务器。面向第三方用户时应在前置身份网关增加 OAuth 2.1，并把验证后的租户身份映射为受限 token/header。
  • 不要把管理员或租户 token 写进 prompt、工具参数、日志或 URL。给 Agent 配租户 token 而不是管理员 token，可以把它的影响面限制在一个租户内。
  • send_resource_command 的 MCP annotation 标记为非破坏、幂等写操作；具体命令是否危险仍由部署方的业务策略决定。

4. REST 备用路径

不支持 MCP 的 Agent 仍可读取 /openapi.json 并直接使用 REST API。两条路径共享认证、租户隔离、持久化和审计语义，因此不会形成第二套数据模型。