MCP 도구 목록¶

이 문서는 OWL MCP Server가 현재 MCP를 통해 호출할 수 있는 비즈니스 도구 기능을 소개합니다. 도구 분류, 권한 유형, 사용 규칙, 도구 개요 및 일반적인 MCP 사용 경로를 포함합니다.

도구의 가시 범위와 호출 결과는 현재 사용 중인 API Key의 권한에 따라 달라집니다. API Key에 관련 리소스 또는 작업 권한이 없는 경우 해당 도구 호출이 실패하거나 빈 결과를 반환할 수 있습니다.

도구 범위¶

OWL MCP Server가 실행할 수 있는 비즈니스 도구는 플랫폼 기능이 지속적으로 업데이트됨에 따라 변경됩니다. 실제 실행 가능한 도구는 list_catalogs 및 list_tools가 반환하는 도구 목록을 기준으로 합니다.

현재 문서는 다음 비즈니스 분류를 다룹니다:

권한 유형¶

사용 규칙¶

facade 모드에서 MCP 클라이언트는 다음 순서로 호출해야 합니다:

1. list_catalogs를 호출하여 사용 가능한 분류를 확인합니다.
2. list_tools를 호출하고 catalog_id를 전달하여 해당 분류의 비즈니스 도구와 매개변수를 확인합니다.
3. exec_tool을 호출하고 tool_name과 parameters를 전달하여 비즈니스 도구를 실행합니다.

static 모드에서는 클라이언트가 세 가지 래퍼 도구를 거치지 않고 직접 tools/list가 반환하는 비즈니스 도구를 호출할 수 있습니다. 어떤 모드를 사용하든 도구 매개변수와 권한 요구 사항은 동일하게 유지됩니다.

도구 개요¶

Account¶

현재 API Key 워크스페이스와 동일 조직의 다른 워크스페이스를 검색하는 데 사용됩니다. 획득한 workspace_uuid는 owl.data.same_org.trace.query의 workspace_uuids 입력 매개변수로 사용하여 워크스페이스 간 Trace 조회에 활용할 수 있습니다.

참고: 반환 결과의 workspace_uuid가 이후 workspace_uuids 입력 매개변수로 사용됩니다. workspace_id는 목록 페이지 매김에만 사용되며 Trace 조회 도구에 전달하지 마십시오.

Catalog¶

통합 리소스 디렉터리의 엔터티 유형 검색, 엔터티 조회, 엔터티 상세 정보 획득 및 토폴로지 관계 조회에 사용됩니다.

참고: 대시보드 도구(owl.dashboard.create / owl.dashboard.replace / owl.dashboard.get)는 OWL CLI에서만 제공되며 MCP 도구 목록에 나타나지 않습니다. 관련 사용법은 OWL CLI 문서를 참조하십시오.

Data¶

권한 기반 워크스페이스 간 DQL 쿼리는 필요할 때 owl.workspace.data_authorized.list로 대상을 검색한 후 workspace_uuids와 target_region을 전달합니다. 한 번에 하나의 사이트만 쿼리하며 범위를 생략하면 현재 워크스페이스를 쿼리합니다. CLI/MCP 예제와 페이지 처리는 워크스페이스 간 쿼리를 참조하세요.

DQL namespace 탐색, 데이터 소스 및 필드 검색, 로그 인덱스 검색, SLO 조회, 로그 클러스터링 분석, 동일 조직 간 워크스페이스 Trace 조회, MCP 클라이언트를 위한 단순 데이터 조회에 사용됩니다. 현재 MCP 측에서는 단순 조회 및 조회 보조 도구를 제공하며, 전체 DQL 또는 PromQL 사용자 정의 실행 도구는 포함되지 않습니다.

owl.data.same_org.trace.query의 workspace_uuids를 생략하거나 빈 배열로 전달하면 현재 워크스페이스만 조회합니다. 동일 조직 간 워크스페이스 조회 기능이 비활성화된 경우 현재 워크스페이스만 조회할 수 있으며, 다른 워크스페이스 UUID를 전달하면 매개변수 오류가 반환됩니다.

Errors¶

오류 센터의 문제 목록 조회와 댓글 추가, 조회 및 업데이트에 사용됩니다.

Event¶

이벤트 센터 목록 조회 및 이벤트 상세 정보 획득에 사용됩니다.

• owl.event.list는 반드시 start_time과 end_time을 제공해야 합니다. status의 선택 값은 fatal, critical, error, warning, nodata이며, limit의 기본값은 20, 최대값은 100입니다. 반환 항목에는 이벤트 차원 태그 필드 df_dimension_tags가 포함될 수 있습니다.
• owl.event.get의 timeRange는 선택적 이중 요소 배열 [start, end]이며, 각 요소는 13자리 밀리초 타임스탬프이고 end는 start보다 커야 합니다. 매개변수명은 timeRange이므로 time_range로 변경하지 마십시오.

Incident¶

owl.incident.get은 장애 UUID(incident_*)를 받아 상세 정보와 related_event_refs를 반환합니다. 참조는 페이지당 기본 및 최대 100개입니다. page_info.has_more와 next_page_index에 따라 가져온 뒤 장애 UUID가 아닌 이벤트 참조로 owl.event.get을 호출하세요. 제공 가능한 참조 수와 장애에 기록된 이벤트 수는 다를 수 있으므로 누락된 근거를 명시하세요.

Infrastructure¶

인프라 객체 목록 및 상세 정보 조회에 사용되며, 호스트, 컨테이너, 프로세스 등 리소스 객체를 포함합니다.

LLM¶

LLM 관측 가능 애플리케이션 목록 조회에 사용됩니다.

Workspace¶

워크스페이스 간 데이터 쿼리 권한 검색 및 현재 워크스페이스 멤버.

새 workspace 범주에는 owl.workspace.data_authorized.list와 owl.workspace.member.list가 포함됩니다. 이전 member 범주는 제거됩니다. owl.member.list는 동일한 매개변수와 권한 검사를 사용하는 호출 별칭으로 유지되지만 별도 도구로 표시되지 않습니다.

Monitor¶

모니터 목록 조회, 상세 정보 획득, 생성 또는 업데이트 및 외부 이벤트 수신에 사용됩니다.

노트¶

현재 API Key 계정에서 볼 수 있는 노트 관리에 사용됩니다.

• owl.nbook_note.list의 page_index 기본값은 1, page_size 기본값은 20, 최대값은 100입니다.
• owl.nbook_note.get은 Markdown 본문 content를 반환하는 유일한 노트 도구이지만 path, etag, version은 반환하지 않습니다. list, add, modify는 요약만 반환하며 content, path, ETag, 버전 정보는 반환하지 않습니다. delete 응답은 백엔드의 기존 간결한 구조를 유지합니다.
• type은 normal과 runbook을 지원합니다. owl.nbook_note.list는 type으로 필터링할 수 있으며 생략 시 유형을 필터링하지 않습니다. owl.nbook_note.add는 type을 설정할 수 있으며 생략 시 백엔드에서 normal 노트를 생성합니다. get과 modify의 응답에는 type이 포함되지만 get, modify, delete는 type 입력 매개변수를 받지 않으며, 기존 노트 유형은 수정할 수 없습니다.
• owl.nbook_note.add는 반드시 title과 content를 제공해야 하며 path는 허용되지 않습니다. created_source는 서버 측에서 고정적으로 ai로 설정되며, 생성 계정은 현재 API Key에서 가져옵니다.
• owl.nbook_note.modify는 note_uuid 외에 title, content, tags, tag_kv 중 최소 하나를 제공해야 합니다. content를 생략하면 원본 본문이 유지됩니다.
• 획득, 수정 및 삭제는 모두 목록이 반환한 note_uuid를 사용합니다. path, etag, if_match, version, creator, created_source 등 백엔드에서 관리하는 필드는 전달하지 마십시오.
• tagkv_query는 목록 도구에서 사용하는 TagKV 표현식 문자열입니다. tag_kv는 생성 및 수정 도구에서 사용하는 키-값 객체이며, 둘을 혼용하지 마십시오.

Pipeline¶

Pipeline 목록 조회 및 샘플 검증에 사용됩니다.

mdsearch¶

통합 문서 코퍼스 검색, id 또는 path로 전체 문서 읽기 및 코퍼스 디렉터리 구조 탐색에 사용되며, 중국어, 영어 및 혼합 검색을 지원합니다.

MCP 사용 경로¶

다음 단계는 기본 facade 모드를 기준으로 합니다. 서버에서 static 모드가 활성화된 경우 동일한 이름의 비즈니스 도구를 직접 호출할 수 있으며 exec_tool을 거칠 필요가 없습니다.

데이터 조회형 문제¶

"메트릭, 로그, RUM, APM, Network, Profile 데이터 조회" 등의 문제에 적합합니다.

1. exec_tool을 통해 owl.data.show_dql_namespace를 호출하여 데이터 namespace를 확인합니다.
2. 데이터 도메인에 따라 exec_tool을 통해 검색형 도구를 호출합니다:
3. 메트릭: owl.metric.list
4. RUM: owl.rum.list
5. APM: owl.apm.list
6. Network: owl.network.list
7. Profile: owl.profile.list
8. 로그: owl.logging.list
9. 클라우드 요금: owl.billing.list
10. 로그 인덱스: owl.log_index.list
11. 필드 디렉터리: owl.field_schema.get
12. 필요한 source, field, index를 획득한 후 exec_tool을 통해 owl.data.simple_query를 호출하여 조회를 실행합니다.

장애 대응형 문제¶

"인시던트 조회, 인시던트 처리 과정 추적, 인시던트 댓글 추가" 등의 문제에 적합합니다.

1. 장애 UUID를 알면 owl.incident.get을 호출하고, 모르면 먼저 owl.incident.list로 찾습니다.
2. 관련 이벤트 참조의 모든 페이지를 읽은 뒤 owl.event.get으로 이벤트 내용을 조회합니다.
3. owl.incident_comment.list로 댓글을, owl.incident_operation.list로 작업 기록을 확인합니다.
4. 진행 상황을 추가해야 하면 owl.incident_comment.add를 호출합니다.

리소스 객체 위치 파악형 문제¶

"호스트, 컨테이너, 프로세스 등 인프라 객체 상세 정보 조회" 문제에 적합합니다.

1. exec_tool을 통해 owl.infrastructure.list를 호출하여 대상 객체를 찾습니다.
2. 반환 결과의 식별 정보를 기반으로 exec_tool을 통해 owl.infrastructure.get을 호출하여 객체 상세 정보를 획득합니다.

워크스페이스 간 Trace 조회형 문제¶

"trace_id로 동일 조직의 여러 워크스페이스에 걸친 Trace 조회" 문제에 적합합니다.

1. 현재 워크스페이스는 직접 쿼리합니다. 동일 조직의 다른 워크스페이스는 UUID를 모를 때만 owl.account.workspace.same_org.list(CLI: owl workspace same-org list)로 검색합니다. 반환된 workspace_uuid를 owl.data.same_org.trace.query에 전달하고, 목록 페이지 처리 전용인 workspace_id는 사용하지 마세요.
2. 반환 결과에서 workspace_uuid를 가져옵니다(workspace_id를 가져오지 마십시오).
3. exec_tool을 통해 owl.data.same_org.trace.query를 호출하고 필수 trace_id를 전달하며, 선택한 workspace_uuid를 workspace_uuids로 전달합니다. 생략하거나 빈 배열로 전달하면 현재 워크스페이스만 조회합니다.
4. 추가 필터링이 필요한 경우 중괄호가 없는 where_clause를 사용하고 trace_id 조건을 중복으로 추가하지 마십시오. 워크스페이스 간 Trace 조회는 owl.data.simple_query로 대체하지 마십시오.

노트 관리형 문제¶

"노트 검색, 읽기, 생성, 수정 또는 삭제" 등의 문제에 적합합니다.

1. exec_tool을 통해 owl.nbook_note.list를 호출하여 노트를 검색하고 note_uuid를 획득합니다.
2. Markdown 본문을 읽어야 하는 경우 owl.nbook_note.get을 호출합니다.
3. 노트 생성 시 owl.nbook_note.add를 호출하고, 업데이트 시 owl.nbook_note.modify를 호출합니다.
4. 삭제 시 owl.nbook_note.delete를 호출합니다. add, modify, delete는 쓰기 도구이므로 실행 전에 클라이언트에서 수동 확인이 이루어져야 합니다.

모니터 관리형 문제¶

"모니터 조회, 모니터 생성 또는 업데이트, 외부 이벤트 전송" 등의 문제에 적합합니다.

1. exec_tool을 통해 owl.monitor.list를 호출하여 모니터를 조회합니다.
2. 반환 결과의 rule_uuid를 기반으로 exec_tool을 통해 owl.monitor.get을 호출하여 모니터 상세 정보를 확인합니다.
3. 모니터를 생성하거나 업데이트해야 하는 경우 exec_tool을 통해 owl.monitor.upsert를 호출합니다.
4. 외부 이벤트를 전송해야 하는 경우 exec_tool을 통해 owl.monitor.receive를 호출합니다.