<!-- 来源: https://hostanagent.com/docs/mcp/recipes/ | 协议: 1.0 | 更新: 2026-09-30 -->

# 常见 MCP 配置任务

这些步骤适用于已经连接并授予相应权限的客户端。每次写操作前先读现状，向用户说明将改变的 Agent、上下文配置或服务状态；完成后回读，报告实际 ID、revision 与版本。

## 创建并发布文本 Agent

1. 用 `list_models` 查看模型是否开放、支持哪些思考强度，再用 `get_model_pricing` 了解价格与参考预留。它不是针对具体消息的报价。
2. `list_agents` 检查是否已有目标 Agent，避免误建重复对象。
3. 用 `create_agent` 创建草稿。下面只展示形状；模型和上下文配置需按当前目录、工具 Schema 和用户意图填写；无需配置累计预算或输出额度。

```json
{
  "data": {
    "request_id": "由客户端生成并保存的稳定请求号",
    "name": "任务整理助手",
    "description": "整理用户授权的任务资料",
    "config": {
      "system_prompt": "只根据用户提供的信息回答，不执行未授权业务操作。",
      "model": null
    },
    "publish": false
  }
}
```

4. 读取新 Agent 的配置，选定真实平台模型后调用 `validate_configuration`。`ready=true` 时按 `get_agent` 返回的 `revision` 用 `update_agent` 提交 `expected_revision` 和 `publish=true`。回读 `get_agent` 与 `list_agent_versions` 核对新版本。没有可用模型时保留草稿。

## 更新工具集与 Agent

先 `list_executor_bindings` 和 `list_toolsets` 复用现有对象。需要新绑定才调用 `create_executor_binding`；`create_toolset`/`update_toolset` 只保存 Schema。工具集更新基于 `base_version`，每个 `upsert_tools` 项是该工具的完整定义；移除用 `remove_tools`。用 `set_agent_toolset` 关联新的固定版本，带 `expected_revision` 和新 `request_id`，再校验并按需发布。最后回读 Agent 的版本与工具集引用。配置成功不代表业务执行器已经连接。[工具页](/docs/console/tools/)。

## 调整上下文窗口或工具结果大小

Agent 的 `config.limits.max_context_tokens` 控制单次输入窗口，默认 256,000 Token，可设 1,024–1,000,000；Run 覆盖只能收紧，不能突破模型容量。每个外部工具的 `max_result_context_bytes` 控制执行结果的字节预算，默认 16,384，可设 1,024–32,768。两者单位和作用不同，不按比例换算。

先读取完整 Agent 和工具定义。修改工具时，在 `update_toolset` 的 `data.upsert_tools` 中保留其名称、Schema、绑定、权限与执行语义，只改变目标预算；每一项是完整定义。保存后将新工具集版本关联到 Agent，再校验、发布并回读固定版本。新建 Session 才使用新配置。MCP 不执行 dry-run；预览通过控制台或具备 `runtime:read` / `configuration:read` / `tools:execute` 其中一项权限的应用 Key 调用 REST。[迁移步骤](/docs/reference/configuration/)和[结果预览](/docs/reference/tools/)。

不要提交 `max_context_chars`、`max_result_bytes` 或 `max_result_tokens`，服务端会拒绝旧字段。工具结果经常超过 32 KiB 时，应让产品增加分页、筛选或按需读取能力；提高整体 Token 窗口不能取消单工具裁剪。

## 比较、回滚或停用

- `list_agent_versions` → `get_agent_version` → `compare_agent_versions` 先向用户展示差异。`rollback_agent` 重新校验并发布**新版本**；既有历史和草稿不改写。
- `copy_agent` 创建新的独立草稿，不复制 Key、Session 或业务资产。
- `set_agent_state` 设为 `paused` 会阻止所有版本的新 Run；设为 `archived` 也从默认列表隐藏。恢复归档后是否启用需显式处理。已接受 Run 不因状态切换自动终止。
- `get_agent_references` 看引用后才考虑 `request_agent_deletion`。删除申请仅归档与记录，可撤回；D08 物理清理尚未实施。

响应丢失时重用原 `request_id` 与完全相同的正文核对。`REVISION_CONFLICT` 需要重新读配置，不能用旧 revision 覆盖。MCP 无 Run、余额或充值工具；需要对话时改走[运行接入](/docs/integration/overview/)。