Claude Agent SDK 可观测性代理实战：使用 MCP 集成 Git 与 GitHub

本教程深入讲解如何利用模型上下文协议（MCP）将外部系统集成到Claude Agent SDK中，构建可观测性代理。通过Git和GitHub MCP服务器，代理能操作本地仓库、管理GitHub资源，并监控CI/CD工作流。文章涵盖环境配置、代码实现、最佳实践及故障排查，并展示了如何封装为可复用模块，实现多轮对话和实时监控。最终，代理从被动工具转变为主动的DevOps助手，为生产级AI系统奠定基础。

技术背景

在构建AI代理时，一个关键限制是它们通常只能访问预定义的工具集，如网络搜索或文件系统。然而，现实世界的应用需要代理与数据库、API、CI/CD系统等外部服务交互。MCP（模型上下文协议）应运而生，它提供了一种标准化方式，让AI模型通过统一的接口调用外部工具，从而打破数据孤岛。本教程聚焦于可观测性代理，它利用MCP连接Git和GitHub，使代理能够监控仓库活动、分析CI状态，并辅助事件响应。这种能力对于现代DevOps至关重要，因为系统复杂性和规模要求自动化监控和快速故障定位。

核心原理

MCP的核心是客户端-服务器架构：AI应用（如Claude）作为MCP客户端，通过JSON-RPC与MCP服务器通信，服务器暴露一组工具。在本教程中，ClaudeAgentOptions的mcp_servers参数定义了要连接的服务器，每个服务器通过命令（如uv或docker）启动。代理通过allowed_tools限制只能使用MCP工具（如mcp__git、mcp__github），而disallowed_tools则禁止使用Bash等通用工具，确保代理只能通过MCP与外部系统交互，增强安全性和可控性。数据流为：用户查询→代理解析→调用MCP工具→服务器执行操作（如git log）→返回结果→代理整合并生成响应。

架构分析

本教程展示了两种MCP服务器集成模式：本地进程（Git）和容器化（GitHub）。Git MCP服务器通过uv运行Python模块，直接访问本地仓库，适合低延迟操作。GitHub MCP服务器则运行在Docker容器中，通过环境变量传递令牌，确保隔离和安全。代理配置中，allowed_tools和disallowed_tools共同定义了工具边界，permission_mode控制权限提示。此外，可观测性代理被封装为observability_agent/agent.py模块，内部复用可视化工具，提供send_query函数，支持多轮对话，实现了关注点分离和代码复用。

完整实战教程

import os
import shutil
import subprocess
from typing import Any

from dotenv import load_dotenv
from IPython.display import Markdown, display
from utils.agent_visualizer import (
    display_agent_response,
    print_activity,
    reset_activity_context,
    visualize_conversation,
)

from claude_agent_sdk import ClaudeAgentOptions, ClaudeSDKClient

Claude Agent SDK 可观测性代理实战：使用 MCP 集成 Git 与 GitHub

可观测性代理是用于收集、处理和转发系统遥测数据（如日志、指标和追踪）的组件。它在现代分布式系统中扮演着关键角色，帮助团队了解系统状态并快速定位问题。

主要功能

部署方式

可观测性代理可以以多种方式部署，包括作为独立进程、容器边车（sidecar）或集成到应用程序中。选择哪种方式取决于具体需求和环境。

最佳实践

通过合理使用可观测性代理，团队可以更有效地监控和管理其系统，确保高可用性和可靠性。

在前面的笔记本中，我们构建了一个基础的研究代理和一个Chief of Staff多代理框架。虽然我们构建的代理已经非常强大，但它们的能力仍然受限：网络搜索代理仅限于搜索互联网，而我们的Chief of Staff代理仅限于与其自身的文件系统交互。

这是一个严重的限制：现实世界中的代理通常需要与其他系统交互，如数据库、API、文件系统和其他专业服务。MCP（模型上下文协议）是一个用于AI工具集成的开源标准，它允许我们的代理与这些外部系统轻松连接。在本笔记本中，我们将探讨如何将MCP服务器连接到我们的代理。

需要更多关于MCP的详细信息？ 有关全面的设置说明、配置最佳实践和故障排除技巧，请参阅Claude Code MCP文档。

MCP 服务器简介

1. Git MCP 服务器

首先，让我们赋予我们的代理理解和操作 Git 仓库的能力。通过将 Git MCP 服务器 添加到我们的代理中，它就能访问 13 个 Git 专用工具，从而可以检查提交历史、查看文件更改、创建分支，甚至进行提交。这使我们的代理从被动的观察者转变为开发工作流中的积极参与者。在本例中，我们将配置代理仅使用 Git 工具来探索仓库的历史。这非常简单，但了解了这一点，就不难想象代理可以自动创建拉取请求、分析代码演变模式，或帮助管理跨多个仓库的复杂 Git 工作流。

# Get the git repository root (mcp_server_git requires a valid git repo path)
# os.getcwd() may return a subdirectory, so we find the actual repo root
git_executable = shutil.which("git")
if git_executable is None:
    raise RuntimeError("Git executable not found in PATH")

git_repo_root = subprocess.run(  # noqa: S603
    [git_executable, "rev-parse", "--show-toplevel"],
    capture_output=True,
    text=True,
    check=True,
).stdout.strip()

# Define our git MCP server (installed via uv sync from pyproject.toml)
git_mcp: dict[str, Any] = {
    "git": {
        "command": "uv",
        "args": ["run", "python", "-m", "mcp_server_git", "--repository", git_repo_root],
    }
}

messages = []
async with ClaudeSDKClient(
    options=ClaudeAgentOptions(
        model="claude-opus-4-6",
        mcp_servers=git_mcp,
        allowed_tools=["mcp__git"],
        # disallowed_tools ensures the agent ONLY uses MCP tools, not Bash with git commands
        disallowed_tools=["Bash", "Task", "WebSearch", "WebFetch"],
        permission_mode="acceptEdits",
    )
) as agent:
    await agent.query(
        "Explore this repo's git history and provide a brief summary of recent activity."
    )
    async for msg in agent.receive_response():
        print_activity(msg)
        messages.append(msg)

display(Markdown(f"\nResult:\n{messages[-1].result}"))

2. GitHub MCP 服务器

现在让我们从本地 Git 操作升级到完整的 GitHub 平台集成。通过切换到官方 GitHub MCP 服务器，我们的代理可以访问超过 100 个工具，这些工具与 GitHub 的整个生态系统交互——从管理 issue 和拉取请求到监控 CI/CD 工作流和分析代码安全警报。该服务器可以处理公共和私有仓库，使您的代理能够自动化复杂的 GitHub 工作流，而这些工作流通常需要多个手动步骤。

步骤 1：设置你的 GitHub 令牌

你需要一个 GitHub 个人访问令牌。在此处获取一个，并将其放入 .env 文件中，格式为 GITHUB_TOKEN="<token>"

注意：获取令牌时，请选择“细粒度”令牌并使用默认选项（即公共仓库，无账户权限），这是让此演示运行的最简单方式。

另外，对于此示例，你需要在你的机器上运行 Docker。需要 Docker 是因为 GitHub MCP 服务器在容器化环境中运行，以确保安全性和隔离性。

Docker 快速设置：

步骤 2：定义 mcp 服务器并启动代理循环！

# define our github mcp server
load_dotenv(override=True)
github_mcp: dict[str, Any] = {
    "github": {
        "command": "docker",
        "args": [
            "run",
            "-i",
            "--rm",
            "-e",
            "GITHUB_PERSONAL_ACCESS_TOKEN",
            "ghcr.io/github/github-mcp-server",
        ],
        "env": {"GITHUB_PERSONAL_ACCESS_TOKEN": os.environ.get("GITHUB_TOKEN")},
    }
}

# run our agent
messages = []
async with ClaudeSDKClient(
    options=ClaudeAgentOptions(
        model="claude-opus-4-6",
        mcp_servers=github_mcp,
        allowed_tools=["mcp__github"],
        # disallowed_tools ensures the agent ONLY uses MCP tools, not Bash with gh CLI
        disallowed_tools=["Bash", "Task", "WebSearch", "WebFetch"],
        permission_mode="acceptEdits",
    )
) as agent:
    await agent.query(
        "Search for the anthropics/claude-agent-sdk-python repository and give me a few key facts about it."
    )
    async for msg in agent.receive_response():
        print_activity(msg)
        messages.append(msg)

display(Markdown(f"\nResult:\n{messages[-1].result}"))

实际用例：可观测性代理

现在，通过这样简单的设置，我们已经可以拥有一个充当自愈软件系统的代理了！

load_dotenv(override=True)

prompt = """Analyze the CI health for facebook/react repository.

Examine the most recent runs of the 'CI' workflow and provide:
1. Current status and what triggered the run (push, PR, schedule, etc.)
2. If failing: identify the specific failing jobs/tests and assess severity
3. If passing: note any concerning patterns (long duration, flaky history)
4. Recommended actions with priority (critical/high/medium/low)

Provide a concise operational summary suitable for an on-call engineer.
Do not create issues or PRs - this is a read-only analysis."""

github_mcp: dict[str, Any] = {
    "github": {
        "command": "docker",
        "args": [
            "run",
            "-i",
            "--rm",
            "-e",
            "GITHUB_PERSONAL_ACCESS_TOKEN",
            "ghcr.io/github/github-mcp-server",
        ],
        "env": {"GITHUB_PERSONAL_ACCESS_TOKEN": os.environ.get("GITHUB_TOKEN")},
    }
}

messages = []
async with ClaudeSDKClient(
    options=ClaudeAgentOptions(
        model="claude-opus-4-6",
        mcp_servers=github_mcp,
        allowed_tools=["mcp__github"],
        # IMPORTANT: disallowed_tools is required to actually RESTRICT tool usage.
        # Without this, allowed_tools only controls permission prompting, not availability.
        # The agent would still have access to Bash (and could use `gh` CLI instead of MCP).
        disallowed_tools=["Bash", "Task", "WebSearch", "WebFetch"],
        permission_mode="acceptEdits",
    )
) as agent:
    await agent.query(prompt)
    async for msg in agent.receive_response():
        print_activity(msg)
        messages.append(msg)

display(Markdown(f"\nResult:\n{messages[-1].result}"))

reset_activity_context()
visualize_conversation(messages)

reset_activity_context()
display_agent_response(messages)

可观测性代理作为模块

observability_agent/agent.py 模块将可观测性模式封装为一个可复用的 send_query 函数。它在内部导入并使用 utils.agent_visualizer 中的共享可视化工具：

这意味着你可以用最少的代码使用该模块：

# Reload the module to pick up any changes (useful during development)
from observability_agent.agent import send_query

# The module handles activity display, context reset, and result visualization internally
result = await send_query(
    "Check the CI status for the last 2 runs in anthropics/claude-agent-sdk-python. Just do 3 tool calls, be efficient."
)

多轮对话可以无缝工作——只需传递 continue_conversation=True：

# Example 2: Multi-turn conversation for deeper monitoring
result1 = await send_query("What's the current CI status for facebook/react?")

# Continue the conversation to dig deeper
result2 = await send_query(
    "Are there any flaky tests in the recent failures? You can only make one tool call.",
    continue_conversation=True,
)

结论

我们已经演示了 Claude Code SDK 如何通过模型上下文协议（MCP）实现与外部系统的无缝集成。从通过 Git MCP 服务器进行本地 Git 操作开始，我们逐步扩展到完整的 GitHub 平台集成，可访问超过 100 个 GitHub 专用工具。这使我们的代理从一个本地助手转变为一个强大的可观测性系统，能够监控工作流、分析 CI/CD 故障，并为生产系统提供可操作的见解。

通过将 MCP 服务器连接到我们的代理，我们创建了一个自主的可观测性系统，用于监控 GitHub Actions 工作流，区分真实故障与安全限制，并提供对测试失败的详细分析。该系统展示了代理如何积极参与您的 DevOps 工作流，从被动监控转向智能事件响应。

目前，我们通过 Claude Code SDK 教程系列的旅程到此结束。我们从简单的研究代理发展到复杂的多代理编排，最后通过 MCP 实现外部系统集成。这些模式共同为构建生产级代理系统奠定了基础，这些系统能够处理现实世界的复杂性，同时保持治理、合规性和可观测性。

您在所有笔记本中学到的内容

来自笔记本 00（研究代理）

来自笔记本 01（参谋长）

来自笔记本 02（可观测性代理）

所有三个代理的完整实现都位于各自的目录中（research_agent/、chief_of_staff_agent/、observability_agent/），随时可以作为您集成到生产系统中的灵感来源。

常见问题

常见错误包括：1) Git仓库路径错误，导致MCP服务器启动失败，需使用git rev-parse获取正确根目录。2) GitHub令牌未设置或权限不足，需在.env中配置GITHUB_TOKEN，并选择细粒度令牌。3) Docker未运行或未安装，导致GitHub MCP服务器无法启动，需确保Docker Desktop运行并检查虚拟化设置。4) 代理仍使用Bash而非MCP工具，因为allowed_tools仅控制权限提示，必须同时设置disallowed_tools来真正限制工具。排查时，可检查MCP服务器日志、验证环境变量、测试Docker容器启动。

企业应用扩展

生产环境优化包括：1) 使用MCP服务器池化或复用连接，减少启动开销。2) 实现缓存机制，避免重复查询相同数据。3) 添加监控和告警，跟踪代理性能和MCP服务器健康状态。4) 扩展更多MCP服务器，如数据库、云服务，以覆盖更广泛的可观测性场景。5) 利用MCP的流式响应和进度更新，提升用户体验。6) 实施安全策略，如最小权限令牌、网络隔离，确保代理操作安全。

总结

本教程深入讲解如何利用模型上下文协议（MCP）将外部系统集成到Claude Agent SDK中，构建可观测性代理。通过Git和GitHub MCP服务器，代理能操作本地仓库、管理GitHub资源，并监控CI/CD工作流。文章涵盖环境配置、代码实现、最佳实践及故障排查，并展示了如何封装为可复用模块，实现多轮对话和实时监控。最终，代理从被动工具转变为主动的DevOps助手，为生产级AI系统奠定基础。

内容来源与验证

继续系统学习

站内还有更多完整实战教程

加入会员，解锁全部教程、完整代码与持续更新内容。

加入会员
查看全部AI 智能体教程