MCP 서버 PingZen: 126 모니터링 도구

PingZen을 MCP 서버로 통합: AI 에이전트를 위한 126가지 도구

MCP 서버는 메인 애플리케이션과 동일한 프로세스 내에서 실행되지만, 고립된 엔드포인트를 갖습니다. STDIO는 데스크톱 에이전트가 파이썬 스크립트를 stdin/stdout를 통해 실행할 때 최적입니다. HTTP 전송은 클라우드 기반 서비스에 적합하도록 FastAPI 내부에 구현되어 있습니다.

126개의 도구 등록은 SDK 데코레이터를 통해 처리됩니다. 도구들은 다음과 같이 그룹화됩니다:

• 모니터링: create_monitor, update_monitor, delete_monitor, get_monitor_status, list_monitors, pause_monitor, resume_monitor.
• 알림: create_alert, update_alert, test_alert, list_alerts.
• 사고 관리: list_incidents, get_incident_details, resolve_incident, add_incident_update.
• 하트비트: create_heartbeat, send_heartbeat_ping, get_heartbeat_status.
• 상태 페이지: create_status_page, add_monitor_to_status_page, update_status_page.
• 웹후크: create_webhook, list_webhooks.
• 보고서: create_scheduled_report, get_report_history.
• API 키: create_api_key, revoke_api_key.

예시 등록 코드

from mcp.server import Server
import mcp.types as types

server = Server("pingzen-mcp")

@server.list_tools()
async def handle_list_tools() -> list[types.Tool]:
    return [
        types.Tool(
            name="create_monitor",
            description="새 모니터 생성",
            inputSchema={
                "type": "object",
                "properties": {
                    "name": {"type": "string"},
                    "type": {"type": "string", "enum": ["http", "tcp", "udp", "icmp", "dns", "smtp", "transaction", ...]},
                    "target": {"type": "string"},
                    "interval": {"type": "integer", "minimum": 60},
                },
                "required": ["name", "type", "target"]
            }
        ),
    ]

@server.call_tool()
async def handle_call_tool(name: str, arguments: dict) -> list[types.TextContent]:
    if name == "create_monitor":
        monitor = await monitor_service.create(arguments)
        return [types.TextContent(type="text", text=json.dumps(monitor.to_dict()))]

인수는 JSON 스키마 형식으로 전달되며, Playwright를 활용한 트랜잭션 프로토콜과 같은 복잡한 프로토콜 정의를 간편하게 만듭니다.

OAuth 2.0 인증

OAuth 2.0은 RFC 9728 기준으로 구현되며, 설정 없이 바로 사용 가능합니다. 에이전트는 텔레그램, 구글, 또는 유안덱스를 통해 브라우저를 열어 인증을 진행합니다. 동의 후 토큰이 발급됩니다. CI/CD 파이프라인에서는 환경 변수를 통해 API 키를 제공합니다. 단순히 에이전트 설정에서 https://pingzen.dev/mcp URL을 지정하면 됩니다.

실용적인 도구 사용법

HTTP 모니터 생성 예시:

{
  "name": "create_monitor",
  "arguments": {
    "name": "Habr",
    "type": "http",
    "target": "https://habr.com",
    "interval": 60,
    "alert_channels": ["telegram"]
  }
}

결과: 모니터 ID와 확인 메시지. list_monitors, resolve_incident, 또는 24시간 간격, 1시간 여유 시간을 가진 하트비트에도 동일하게 적용됩니다.

구현 시 주의사항

• 검증: JSON 스키마는 엄격한 타입 검사를 수행합니다. 핸들러에서는 AI가 문자열을 반환해도 명시적으로 타입 변환을 적용합니다(예: interval는 정수).

• 동기화: 모든 도구는 동기식이며 타임아웃을 지원합니다. 간단함을 위해 백그라운드 작업은 없습니다.

• 오류 처리: 중앙 집중식 오류 메시지는 errors.py에 정의되어 있습니다:

_ERROR_MESSAGES = {
    "INVALID_PROTOCOL": "지원되지 않는 모니터 유형 '{type}'. 사용 가능한 유형: http, tcp, udp, icmp, dns, smtp, transaction, ...",
    "TIMEOUT": "{timeout}초 후 요청 시간 초과",
}

• 로그 기록: STDIO를 통해 stderr로 출력되며, 호출 인수도 포함됩니다.

핵심 요약

• 126개의 도구는 모니터 생성부터 사고 관리, 보고서까지 전 생애주기를 커버합니다.
• 로컬 및 클라우드 에이전트 모두를 위한 두 가지 전송 방식으로 유연성을 확보했습니다.
• 설정 없이 사용 가능한 OAuth로 설정 부담을 줄였으며, API 키를 통해 자동화를 가능하게 합니다.
• 타임아웃과 엄격한 검증을 갖춘 동기식 설계로 예측 가능한 동작을 보장합니다.
• 컨텍스트 전환 없이 CI/CD 및 IDE와 원활하게 통합됩니다.

— Editorial Team