MCP Server 빠른 시작¶

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

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

MCP 클라이언트가 호출할 수 있는 주요 도구는 다음과 같습니다.

• 동일 조직 내 크로스 워크스페이스 Trace 조회: 먼저 owl.account.workspace.same_org.list로 후보 워크스페이스를 검색한 후, 반환된 workspace_uuid를 workspace_uuids로 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, 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이 연결되어 있고 도구를 검색할 수 있는지 확인합니다.

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를 나열해 주세요.

클라이언트는 list_catalogs, list_tools, exec_tool을 검색할 수 있어야 하며, exec_tool을 통해 owl.metric.list를 호출할 수 있어야 합니다. 연결이 불가능하거나, 인증에 실패하거나, 도구 목록이 비어 있거나, 반환 결과가 비어 있는 경우 문제 해결을 참조하세요.