AI 原生开放教材

外观

御舆：解码 Agent Harness工程手册·中文原文 ↗原件 ↓仓库 ↗

实战练习 ​

练习 1：配置一个 stdio 类型的 MCP 服务器 ​

在项目根目录创建 .mcp.json：

json
{
  "mcpServers": {
    "filesystem": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
      "env": {}
    }
  }
}

启动 Claude Code 后，验证工具是否加载：

  • 观察启动日志中的 MCP 连接状态
  • 尝试使用 mcp__filesystem__* 前缀的工具

进阶挑战：

  • 修改 .mcp.json，为文件系统服务器添加自定义环境变量（如限制只读模式）
  • 在 .claude/settings.local.json 中配置权限规则，自动允许 mcp__filesystem__read_file 但保留 mcp__filesystem__write_file 的确认提示
  • 测试在启动后禁用文件系统服务器，观察工具列表的变化

练习 2：理解工具名称解析 ​

根据 mcp__\{server\}__\{tool\} 的命名规则，分析以下场景：

  • 解析 mcp__github__create_issue 会得到什么结果？
  • 构建 mcp__my_server__read_file 需要什么输入？
  • 包含双下划线的工具名 mcp__my__special__tool 会如何解析？

进阶挑战：

  • 如果同时配置了名为 github 和 git_hub 的两个服务器，它们提供同名工具时，如何通过权限配置分别控制？
  • 在 SDK 模式下（设置 CLAUDE_AGENT_SDK_MCP_NO_PREFIX），如果一个 MCP 工具名为 Read，它会如何与内置的 Read 工具交互？

练习 3：配置企业级 MCP 安全策略 ​

在企业管理配置中设置白名单和黑名单：

json
{
  "allowedMcpServers": [
    { "serverName": "approved-server" },
    { "serverCommand": ["npx", "-y", "@modelcontextprotocol/server-filesystem"] },
    { "serverUrl": "https://mcp.company.com/*" }
  ],
  "deniedMcpServers": [
    { "serverName": "dangerous-server" }
  ]
}

测试不同配置的服务器是否能被正确允许或阻止。

进阶挑战：

  • 设计一个安全策略，只允许公司内部的 MCP 服务器（*.company.com），同时阻止所有外部公共服务器
  • 考虑如何处理"同一服务器在不同作用域中被配置"的情况——当 enterprise 配置允许了某个服务器，但 local 配置中该服务器在黑名单中，结果会怎样？

练习 4：多服务器集成实战 ​

配置一个包含多个 MCP 服务器的复杂环境，模拟真实的开发工作流：

json
{
  "mcpServers": {
    "github": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxxx" }
    },
    "database": {
      "type": "sse",
      "url": "https://internal-mcp.company.com/database",
      "headers": { "Authorization": "Bearer internal-token" }
    },
    "docs": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
      "env": { "BRAVE_API_KEY": "BSA_xxxx" }
    }
  }
}

分析任务：

  • 每个服务器注册了哪些工具？工具的完整名称是什么？
  • 如果 GitHub 服务器连接失败，其他服务器会受到影响吗？
  • 如何为每个服务器配置不同级别的权限（如 GitHub 完全允许，数据库只允许只读操作）？

练习 5：理解 Bridge 通信流程 ​

分析以下场景中的 Bridge 通信行为：

场景 A：用户在 VS Code 中通过 Claude Code 扩展发送消息"修复所有 TypeScript 错误"

  1. 消息如何从 VS Code 到达 Claude CLI？
  2. Claude Code 如何调用 getDiagnostics 获取错误信息？
  3. 修复代码后如何通过 executeCode 在 IDE 中应用？

场景 B：用户在 claude.ai 网页端远程控制一个正在运行的 CLI 会话

  1. 网页端发出 set_model 请求切换到 Opus 模型，CLI 如何处理？
  2. 如果 CLI 当前正在执行一个长时间的工具调用，interrupt 命令如何中断它？
  3. 如果用户没有 claude.ai 订阅，会在哪一层门控被拒绝？