콘텐츠로 이동

MCP Server 빠른 시작


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

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

원격 OWL MCP Server에 연결할 때는 OWL CLI 또는 CLI와 함께 제공되는 Skill을 설치할 필요가 없습니다. Agent가 터미널 명령을 실행할 수 있다면 CLI 통합 흐름을 선택할 수도 있습니다. 두 방식의 선택은 연결 방식 설명을 참조하세요.

사용 전 준비 사항

연결하기 전에 다음 준비 사항을 완료했는지 확인하세요.

  1. 해당 비즈니스 권한을 가진 Guance API Key 생성
  2. 워크스페이스가 속한 사이트에 해당하는 OWL MCP Endpoint 확보
  3. 클라이언트가 Streamable HTTP를 지원하고 Authorization 요청 헤더 구성을 허용함
  4. 클라이언트가 실제로 요청을 보내는 환경에서 OWL MCP Endpoint에 접근할 수 있음

Endpoint

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

배포 유형 사이트 이름 Endpoint
SaaS 배포 중국 리전 1(항저우) https://owl-mcp.guance.com/mcp
SaaS 배포 중국 리전 2(닝샤) https://aws-owl-mcp.guance.com/mcp
SaaS 배포 중국 리전 4(광저우) https://cn4-owl-mcp.guance.com/mcp
SaaS 배포 중국 리전 6(홍콩) https://cn6-owl-mcp.guance.one/mcp
SaaS 배포 글로벌 리전 1(오리건) https://us1-owl-mcp.guance.com/mcp
SaaS 배포 유럽 리전 1(프랑크푸르트) https://eu1-owl-mcp.guance.one/mcp
SaaS 배포 아시아 태평양 리전 1(싱가포르) https://ap1-owl-mcp.guance.one/mcp
SaaS 배포 아시아 태평양 리전 2(싱가포르) https://ap2-owl-mcp.guance.com/mcp
SaaS 배포 아프리카 리전 1(남아프리카) https://za1-owl-mcp.guance.com/mcp
SaaS 배포 인도네시아 리전 1(자카르타) https://id1-owl-mcp.guance.com/mcp
SaaS 배포 무료 존(베이징) https://cn3-owl-mcp.guance.com/mcp
프라이빗 배포 플랜 프라이빗 배포 플랜 실제 배포에서 제공하는 OWL MCP Endpoint 기준

인증 방식

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

Authorization: Bearer <API Key>

사이트는 위의 Endpoint URL을 통해 선택하며, 별도의 Endpoint 요청 헤더를 추가할 필요가 없습니다. 또한 사이트 식별자를 Authorization 값에 추가하지 마세요.

MCP와 OWL CLI는 서로 다른 서비스 진입점과 요청 헤더를 사용하므로 구성 시 구분해야 합니다.

호출 진입점 사이트 선택 인증 구성
OWL MCP Server 이 페이지의 Endpoint 표에 있는 /mcp 주소 사용 MCP 클라이언트에서 Authorization: Bearer <API Key> 설정
OWL CLI OWL CLI Endpoint 사용 CLI 로그인 또는 Profile에서 API Key를 구성하면 CLI가 DF-API-KEY를 자동 전송합니다. 자세한 내용은 CLI 구성 및 인증을 참조하세요.

CLI의 DF-API-KEY 요청 헤더를 이 페이지의 MCP 클라이언트 구성에 그대로 적용하지 마세요.

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

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

클라이언트 구성

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

아래에서 사용할 클라이언트를 선택하고 동일한 연결 정보를 입력하세요.

  1. 워크스페이스가 속한 사이트의 OWL MCP Endpoint 선택
  2. Authorization: Bearer <API Key> 요청 헤더 구성
  3. 서비스를 저장하고 활성화한 뒤 현재 대화에서 해당 도구 사용 허용
  4. 검증 방식에 따라 도구 검색 및 읽기 전용 호출 1회 수행
클라이언트 구성 진입점
Codex MCP 구성
Claude Code MCP 구성
Cursor MCP 구성
Trae MCP 구성
VS Code + GitHub Copilot MCP 구성
Windsurf(Cascade) MCP 구성
Claude Desktop 원격 커넥터
Cherry Studio MCP 구성
OpenClaw MCP 구성
Hermes 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를 로컬 환경 변수로 두고, 팀에서 승인한 자격 증명 관리 방식을 통해 전체 Bearer <API Key>를 주입하세요. 실제 자격 증명을 .mcp.json에 직접 기록하거나 코드 저장소에 커밋하지 마세요. 저장한 후 Claude Code를 다시 시작하고 claude mcp list를 실행하세요. 세션에서 /mcp를 입력하여 owl이 연결되었고 도구를 검색할 수 있는지 확인할 수도 있습니다. 변수 확장 및 구성 범위는 Claude Code 공식 문서를 참조하세요.

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"는 읽기 전용으로 표시되지 않은 도구에 대해 확인을 요청하므로 유지하는 것이 좋습니다. facade 모드의 exec_tool도 확인 요청을 트리거합니다. 필드 설명은 Codex 공식 문서를 참조하세요.

Cursor

프로젝트의 .cursor/mcp.json 또는 사용자 수준 ~/.cursor/mcp.json에 다음을 추가하세요.

{
  "mcpServers": {
    "owl": {
      "url": "your-owl-mcp-endpoint",
      "headers": {
        "Authorization": "Bearer ${env:OWL_MCP_API_KEY}"
      }
    }
  }
}

Cursor를 시작하는 환경에서 OWL_MCP_API_KEY를 API Key로 설정하고, 환경 변수 참조를 통해 요청 헤더로 전달하세요. 저장한 후 MCP 설정에서 owl이 활성화되었는지 확인하고, Agent 대화에서 검증 방식에 따라 읽기 전용 호출을 한 번 수행하세요. 진입점 및 변수 구문은 Cursor 공식 문서를 참조하세요.

Trae

설정의 MCP 관리로 이동하여 수동 추가를 선택하고 다음 구성을 입력하세요.

{
  "mcpServers": {
    "owl": {
      "url": "your-owl-mcp-endpoint",
      "headers": {
        "Authorization": "Bearer <API Key>"
      }
    }
  }
}

<API Key>를 실제 값으로 바꿀 때는 클라이언트의 비공개 구성에서만 작업하고, 자격 증명이 포함된 구성을 대화, 공유 문서 또는 코드 저장소에 게시하지 마세요. 저장한 후 현재 Agent에서 owl을 활성화하고 검증 방식에 따라 호출을 수행하세요. 구체적인 진입점은 Trae 공식 문서를 참조하세요.

VS Code + GitHub Copilot

VS Code 명령 팔레트에서 MCP: Add Server를 실행하고 HTTP를 선택한 다음, OWL MCP Endpoint를 입력하고 이름을 owl로 지정하세요. 다음은 VS Code 형식의 .vscode/mcp.json 구성입니다.

{
  "servers": {
    "owl": {
      "type": "http",
      "url": "your-owl-mcp-endpoint",
      "headers": {
        "Authorization": "Bearer ${env:OWL_MCP_API_KEY}"
      }
    }
  }
}

VS Code를 실행하는 환경에서 OWL_MCP_API_KEY를 설정하세요. 원격 개발이나 컨테이너를 사용하는 경우 실제로 MCP 클라이언트가 실행되는 환경에서 설정해야 합니다. Agent 대화에서 해당 도구를 활성화하고 검증 방식에 따라 호출을 수행하세요.

VS Code 형식은 최상위 servers를 사용하고, Portable Copilot 형식은 mcpServers를 사용합니다. 두 구조를 직접 혼용하지 마세요. 구체적인 구성 범위와 실행 모드는 VS Code 공식 문서를 참조하세요.

Windsurf(Cascade)

Cascade의 MCP 관리 진입점에서 mcp_config.json을 열고 다음을 추가하세요.

{
  "mcpServers": {
    "owl": {
      "serverUrl": "your-owl-mcp-endpoint",
      "headers": {
        "Authorization": "Bearer ${env:OWL_MCP_API_KEY}"
      }
    }
  }
}

클라이언트를 시작하는 환경에서 OWL_MCP_API_KEY를 설정하고, 저장한 후 MCP 서비스를 새로 고치고 owl을 활성화한 다음 검증 방식에 따라 호출을 수행하세요.

이 구성은 Cascade에 적용됩니다. 다른 Agent 모드에서는 다른 구성 진입점을 사용할 수 있습니다. serverUrl, headers 및 환경 변수 구문은 Cascade 공식 문서를 참조하세요.

Claude Desktop

원격 사용자 지정 커넥터를 사용하여 연결합니다.

  1. 커넥터 설정에서 사용자 지정 원격 커넥터를 추가하고 OWL MCP Endpoint를 입력합니다.
  2. 고정 API Key를 사용하는 경우 Authentication에서 No sign in(OAuth 로그인 사용 안 함)을 선택한 다음, Request headers에 Authorization을 추가하고 값을 Bearer <API Key>로 설정합니다. 서버는 계속 이 요청 헤더를 통해 인증을 완료합니다.
  3. 저장한 후 현재 대화에서 커넥터를 활성화하고 검증 방식에 따라 호출을 수행하세요.

원격 커넥터의 요청은 로컬이 아니라 Anthropic 클라우드에서 전송됩니다. 프라이빗 네트워크 또는 IP 허용 목록에서 실제 요청 소스를 허용해야 합니다. 조직 계정에서는 관리자가 먼저 커넥터를 추가해야 할 수 있습니다. 진입점, 권한 및 요청 헤더 구성은 Claude 공식 문서를 참조하세요.

OpenClaw

openclaw mcp set owl '{
  "transport": "streamable-http",
  "url": "your-owl-mcp-endpoint",
  "headers": {
    "Authorization": "Bearer ${OWL_MCP_API_KEY}"
  },
  "enabled": true
}'

OpenClaw가 실제로 실행되는 프로세스 환경에서 OWL_MCP_API_KEY를 API Key로 설정하세요. 위의 작은따옴표는 환경 변수 참조를 유지하며 실제 자격 증명을 명령에 기록하지 않습니다. 저장된 구성을 확인하고 서비스를 점검하세요.

openclaw mcp list
openclaw mcp show owl

list / show는 구성만 확인할 뿐 서비스 연결 가능성을 증명하지 않습니다. mcp doctor를 지원하는 버전에서는 openclaw mcp doctor owl --probe를 계속 실행하여 서비스를 점검할 수 있습니다. 이전 버전에서는 실제 도구 호출 결과로 검증하세요. Gateway가 다른 프로세스에서 실행되는 경우 해당 프로세스가 구성과 환경을 다시 로드하도록 한 후 최초 호출을 완료해야 합니다. 필드와 명령은 OpenClaw 공식 문서를 참조하세요.

Hermes

~/.hermes/config.yaml을 편집하세요.

mcp_servers:
  owl:
    url: your-owl-mcp-endpoint
    headers:
      Authorization: "Bearer ${OWL_MCP_API_KEY}"
    enabled: true

Hermes 실행 환경 또는 현재 Profile의 자격 증명 구성에서 OWL_MCP_API_KEY를 설정하세요. url은 원격 HTTP 서비스에 대응하며 기본적으로 Streamable HTTP를 사용하므로 type: streamableHttp가 필요하지 않습니다. 구성을 검증하세요.

hermes mcp list
hermes mcp test owl

현재 Hermes의 안내에 따라 MCP를 다시 로드하거나 새 세션을 만든 후 최초 호출을 완료하세요. 필드 및 변수 참조는 Hermes 공식 문서를 참조하세요.

검증 방식

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

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

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

다음을 각각 확인하세요.

확인 항목 성공 시 동작
연결 및 인증 서비스 연결에 성공하고 인증 또는 네트워크 오류가 없음
도구 검색 facade 래퍼 도구 또는 static 모드의 비즈니스 도구를 검색할 수 있으며 현재 대화에서 활성화됨
실제 호출 호출 기록에 메트릭 source 조회가 한 번 있고, MCP 및 비즈니스 결과 모두 오류가 없으며 데이터 또는 성공적인 빈 목록을 반환함; 답변은 해당 결과를 기반으로 생성됨

“연결됨”만 표시되거나 Agent가 “구성 성공”이라고 응답하는 것만으로는 비즈니스 도구를 사용할 수 있음을 증명할 수 없습니다. 성공적인 빈 목록도 워크스페이스에 반드시 메트릭 데이터가 있다는 것을 의미하지는 않으므로 데이터 연동 및 API Key 권한 확인과 함께 판단해야 합니다. 다음 단계로 대표 질문을 시도할 수 있습니다.

사용 가능한 도구

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

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

  • 권한이 부여된 크로스 워크스페이스 데이터 쿼리: owl.workspace.data_authorized.list를 통해 권한이 부여된 워크스페이스를 검색한 다음, owl.data.simple_query에 workspace_uuids와 target_region을 전달합니다. 한 번의 쿼리는 하나의 대상 사이트로 제한됩니다. 자세한 내용은 크로스 워크스페이스 쿼리를 참조하세요.
  • 인시던트 상세: owl.incident.get을 사용하여 인시던트 UUID로 상세 정보와 페이지네이션된 관련 이벤트 참조를 가져온 다음, owl.event.get을 사용하여 이벤트 내용을 읽습니다.
  • 동일 조직 크로스 워크스페이스 Trace 쿼리: 현재 워크스페이스에서는 직접 쿼리합니다. 동일 조직의 다른 워크스페이스이며 대상 UUID가 확정되지 않은 경우 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를 나열합니다.

사용 규칙

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

유형 규칙
시간 범위 도구 일관되게 13자리 밀리초 타임스탬프를 사용합니다.
페이지네이션 도구 일반적으로 page_size 및 page_index를 지원합니다.
상세 도구 일반적으로 목록 도구에서 반환된 식별자 필드에 의존합니다. 예: rule_uuid, incident_uuid, issue_id, note_uuid
데이터 쿼리 도구 “먼저 검색, 이후 쿼리” 순서로 사용하는 것이 좋습니다. 먼저 검색 도구를 통해 사용 가능한 source, field, index를 가져온 다음 실제 쿼리를 수행하세요.

문서 평가

이 페이지가 도움이 되었나요?