MCP Server 빠른 시작¶

OWL MCP Server는 Guance이 Model Context Protocol을 기반으로 제공하는 서버 측 구현입니다. Guance의 메트릭, 로그, 이벤트, 모니터, APM, RUM, 인프라스트럭처, 노트 등의 기능을 MCP 도구로 캡슐화하여 MCP를 지원하는 AI 클라이언트에서 호출할 수 있도록 합니다.

이 문서에서는 streamableHttp를 통해 OWL MCP Server에 연결하는 방법을 설명합니다.

서버 측에서는 두 가지 도구 노출 방식을 지원합니다. 기본 facade 모드는 list_catalogs, list_tools, exec_tool의 세 가지 래핑 도구를 제공합니다. static 모드는 MCP tools/list에서 노출이 허용된 비즈니스 도구를 직접 반환합니다. 구체적인 모드는 서버 구성에 따라 결정되며, 클라이언트는 전송 프로토콜을 변경할 필요가 없습니다.

MCP 클라이언트에서 호출할 수 있는 대표적인 도구는 다음과 같습니다.

• 권한 기반 워크스페이스 간 DQL 쿼리는 필요할 때 owl.workspace.data_authorized.list로 대상을 검색한 후 workspace_uuids와 target_region을 전달합니다. 한 번에 하나의 사이트만 쿼리하며 범위를 생략하면 현재 워크스페이스를 쿼리합니다. CLI/MCP 예제와 페이지 처리는 워크스페이스 간 쿼리를 참조하세요.
• owl.incident.get은 장애 UUID(incident_*)를 받아 상세 정보와 related_event_refs를 반환합니다. 참조는 페이지당 기본 및 최대 100개입니다. page_info.has_more와 next_page_index에 따라 가져온 뒤 장애 UUID가 아닌 이벤트 참조로 owl.event.get을 호출하세요. 제공 가능한 참조 수와 장애에 기록된 이벤트 수는 다를 수 있으므로 누락된 근거를 명시하세요.
• 현재 워크스페이스는 직접 쿼리합니다. 동일 조직의 다른 워크스페이스는 UUID를 모를 때만 owl.account.workspace.same_org.list(CLI: owl workspace same-org list)로 검색합니다. 반환된 workspace_uuid를 owl.data.same_org.trace.query에 전달하고, 목록 페이지 처리 전용인 workspace_id는 사용하지 마세요.
• 노트: owl.nbook_note.list / owl.nbook_note.get / owl.nbook_note.add / owl.nbook_note.modify / owl.nbook_note.delete, 노트를 조회, 읽기, 생성, 수정 및 삭제하는 데 사용됩니다. normal과 runbook 두 가지 유형을 지원하며, list는 type으로 필터링할 수 있고, add는 type을 설정할 수 있습니다. get만 Markdown 본문을 반환하며, add, modify, delete는 쓰기 도구이므로 MCP 클라이언트에서 수동 확인을 구성하는 것이 좋습니다.
• 이벤트 조회: owl.event.list / owl.event.get, 시간 범위와 상태에 따라 이벤트 목록을 조회하고, 이벤트 문서 ID로 상세 정보를 가져오는 데 사용됩니다.
• Pipeline 조회 및 샘플 검증: owl.pipeline.list / owl.pipeline.validate, Pipeline을 조회하거나 샘플 데이터를 사용하여 처리 결과를 검증하는 데 사용됩니다. 검증은 테스트만 수행하며 Pipeline을 생성하거나 수정하지 않습니다.
• 간편 데이터 조회: owl.data.simple_query, 보다 사용하기 쉬운 데이터 조회 진입점을 제공합니다.
• 문서 검색: mdsearch_search / mdsearch_document / mdsearch_catalog, Guance 문서를 검색하는 데 사용됩니다.
• SLO 목록: owl.slo.list, 구성된 SLO를 나열합니다.

사전 준비¶

연결 전에 다음 준비가 완료되었는지 확인하세요.

1. 해당 비즈니스 권한이 있는 Guance API Key가 생성되어 있어야 합니다.
2. 워크스페이스가 속한 사이트에 해당하는 OWL MCP Endpoint를 확인해야 합니다.
3. MCP 클라이언트에서 OWL MCP 서비스 연결 구성이 완료되어야 합니다.
4. 현재 네트워크 환경에서 OWL MCP Endpoint에 접근 가능해야 합니다.

Endpoint¶

OWL MCP Server는 사이트별로 독립적인 Endpoint를 제공합니다. 워크스페이스가 속한 사이트에 따라 해당 주소를 선택하세요.

인증 방식¶

MCP 클라이언트에서 요청 헤더를 구성합니다.

Authorization: Bearer <API Key>

<API Key>는 Guance API Key입니다. 안전하게 보관하고, 공개 코드 저장소, 공유 문서 또는 장기 로그에 기록하지 마세요.

OWL MCP Server는 인증을 먼저 수행한 후 MCP 처리를 진행합니다. 인증되지 않았거나 자격 증명이 유효하지 않은 요청은 직접 거부되며, 401 Unauthorized와 응답 헤더 WWW-Authenticate: Bearer realm="mcp"를 반환합니다. 또한, 속도 제한에 걸리면 429를 반환하고, 출처 IP가 허용 목록에 없으면 403을 반환합니다.

클라이언트 구성¶

OWL MCP Server는 표준 streamableHttp 연결 방식을 사용하며, 해당 전송 방식을 지원하는 MCP 클라이언트에 연결할 수 있습니다. 각 클라이언트의 구성 진입점과 필드 이름은 다를 수 있으므로 실제 클라이언트 문서를 기준으로 하세요.

다음은 Cherry Studio, Claude Code, Codex, OpenClaw 및 Hermes를 예시로 일반적인 MCP 클라이언트의 구성 방법을 설명합니다. streamableHttp를 지원하는 다른 MCP 클라이언트도 동일한 원칙으로 구성할 수 있습니다.

• URL에는 워크스페이스가 속한 사이트에 해당하는 OWL MCP Endpoint를 입력합니다.
• 요청 헤더에 Authorization: Bearer <API Key>를 구성합니다.
• 해당 MCP 서비스를 활성화합니다.

다음 예시에서는 플레이스홀더 주소 your-owl-mcp-endpoint를 사용합니다. 실제 연결 시에는 워크스페이스가 속한 사이트에 해당하는 OWL MCP Endpoint로 바꾸세요.

Cherry Studio¶

Cherry Studio에서 MCP 서비스를 새로 추가하고 다음과 같이 구성합니다.

• 유형: streamableHttp
• URL: your-owl-mcp-endpoint
• 요청 헤더: Authorization=Bearer <API Key>

구성을 완료한 후 저장하고 활성화한 다음, 클라이언트 홈페이지로 돌아가 해당 MCP 서비스를 선택합니다.

Claude Code¶

Claude Code는 http 유형을 사용하여 Streamable HTTP 서비스에 연결합니다. 프로젝트 루트 디렉터리에 .mcp.json을 생성하거나 편집하고 다음 구성을 추가합니다.

{
  "mcpServers": {
    "owl": {
      "type": "http",
      "url": "your-owl-mcp-endpoint",
      "headers": {
        "Authorization": "${OWL_MCP_AUTHORIZATION}"
      }
    }
  }
}

OWL_MCP_AUTHORIZATION을 로컬 환경 변수로 설정하고, 팀에서 승인한 자격 증명 관리 방식을 통해 전체 인증 정보를 주입합니다. 실제 자격 증명을 .mcp.json에 직접 기록하거나 코드 저장소에 커밋하지 마세요. 저장 후 Claude Code를 다시 시작하고 claude mcp list를 실행하거나, 세션에서 /mcp를 입력하여 owl이 연결되어 있고 도구를 발견할 수 있는지 확인합니다.

Codex¶

MCP JSON을 Codex에 복사하고 "이 MCP를 구성해 줘"라고 입력하면 Codex가 자동으로 관련 구성을 완료합니다.

수동 구성이 필요한 경우, Codex 데스크톱, CLI 및 IDE 확장은 MCP 구성을 공유합니다. ~/.codex/config.toml을 편집하고 다음 구성을 추가합니다.

[mcp_servers.owl]
url = "your-owl-mcp-endpoint"
bearer_token_env_var = "OWL_MCP_API_KEY"
default_tools_approval_mode = "writes"

Codex를 시작하는 환경에서 OWL_MCP_API_KEY를 Guance API Key로 설정합니다. Codex는 이 값을 Bearer Token으로 자동 전송하므로 변수 값에 Bearer를 중복해서 추가하지 마세요. 또한 실제 자격 증명을 config.toml에 직접 기록하거나 코드 저장소에 커밋하지 마세요.

구성을 저장한 후 Codex를 다시 시작하고 codex mcp list를 실행하거나, 세션에서 /mcp를 입력하여 owl이 연결되어 있고 도구를 발견할 수 있는지 확인합니다. 예시의 default_tools_approval_mode = "writes"는 데이터를 쓸 수 있는 도구 호출 전에 확인을 요청하므로 유지하는 것이 좋습니다.

OpenClaw¶

openclaw mcp set owl '{
  "type": "streamableHttp",
  "url": "your-owl-mcp-endpoint",
  "headers": {
    "Authorization": "Bearer <API Key>"
  },
  "enabled": true
}'

구성 확인:

openclaw mcp list
openclaw mcp show owl

Hermes¶

~/.hermes/config.yaml을 편집합니다.

mcp_servers:
  owl:
    type: streamableHttp
    url: your-owl-mcp-endpoint
    headers:
      Authorization: Bearer <API Key>
    enabled: true

구성 확인:

hermes mcp list
hermes mcp test owl

사용 규칙¶

OWL MCP Server를 사용할 때 다음 규칙을 따르는 것이 좋습니다.

확인 방법¶

구성을 완료한 후 MCP 클라이언트에서 다음과 같이 질문합니다.

현재 사용 가능한 메트릭 source를 나열해 줘.

facade 모드에서는 클라이언트가 list_catalogs, list_tools, exec_tool을 발견할 수 있으며, exec_tool을 통해 owl.metric.list를 호출할 수 있습니다. static 모드에서는 클라이언트가 owl.metric.list 등의 비즈니스 도구를 직접 발견합니다. 서버에 제외 목록이 구성된 경우 일부 도구는 나타나지 않습니다. 연결할 수 없거나, 인증에 실패하거나, 도구 목록이 비어 있거나, 반환 결과가 없는 경우 문제 해결을 참조하세요.