> For the complete documentation index, see [llms.txt](https://genos-docs.gitbook.io/default/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://genos-docs.gitbook.io/default/v1.9.3/basic-tutorials/guides/mcp/mcp-tool-labeling.md).
# MCP 도구 라벨링
MCP 도구의 동작 특성과 개인정보 처리 범위를 등록하고, Agent Gateway에서 라벨 기준의 접근 정책을 설정하는 방법을 안내합니다.
구현 구조와 API 계약은 MCP 도구 라벨 아키텍처를 참고하세요.
## 목차
1. [라벨과 개인정보 유형](#라벨과-개인정보-유형)
2. [MCP 도구에서 값 지정하기](#mcp-도구에서-값-지정하기)
3. [MCP 서버에서 런타임 도구 분류하기](#mcp-서버에서-런타임-도구-분류하기)
4. [변경 승인 확인하기](#변경-승인-확인하기)
5. [행위 라벨 기본값 관리하기](#행위-라벨-기본값-관리하기)
6. [Agent Gateway 정책 설정하기](#agent-gateway-정책-설정하기)
7. [개인정보 유형으로 서빙 호출 차단하기](#개인정보-유형으로-서빙-호출-차단하기)
8. [표시가 예상과 다를 때](#표시가-예상과-다를-때)
## 라벨과 개인정보 유형
행위 라벨은 한 도구에 여러 개 지정할 수 있습니다.
| 라벨 | 의미 |
| ----- | ------------------------- |
| 읽기 전용 | 데이터를 바꾸지 않고 조회만 합니다. |
| 파괴적 | 되돌리기 어려운 변경이나 삭제를 수행합니다. |
| 멱등성 | 같은 요청을 여러 번 보내도 결과가 같습니다. |
| 외부 연동 | GenOS 밖의 시스템과 통신합니다. |
읽기 전용을 선택하면 파괴적과 멱등성은 즉시 선택 해제되고 비활성화됩니다. 비활성화된 항목은 체크되지 않은 상태로 보입니다.
개인정보 유형은 다음 네 값 중 하나를 선택합니다.
| 값 | 의미 |
| --- | --------------------------- |
| 없음 | 개인정보를 다루지 않습니다. |
| 입력 | 요청에 개인정보가 포함될 수 있습니다. |
| 출력 | 응답에 개인정보가 포함될 수 있습니다. |
| 입출력 | 요청과 응답 모두 개인정보가 포함될 수 있습니다. |
아직 지정하지 않은 값은 빈칸으로 표시됩니다. `미지정` 칩은 따로 표시하지 않습니다.
## MCP 도구에서 값 지정하기
**도구 > MCP > MCP 도구**에서 목록을 열면 위험 라벨과 개인정보 유형을 별도 열에서 확인할 수 있습니다.
도구를 만들거나 수정할 때 **중요 정보**에서 행위 라벨과 개인정보 유형을 지정합니다. 저장 후 상세 화면을 다시 열어도 개인정보 유형이 유지됩니다.
## MCP 서버에서 런타임 도구 분류하기
**도구 > MCP > MCP 서버 > 서버 상세 > 행위 유형**에서 배포된 서버의 런타임 도구를 확인합니다.
**편집**을 누르면 행위 라벨과 개인정보 유형을 변경할 수 있습니다. 행위 라벨 입력란을 열면 네 라벨과 설명이 나옵니다.
읽기 전용을 고르면 파괴적과 멱등성은 선택 해제된 채 비활성화됩니다. 외부 연동은 함께 선택할 수 있습니다.
개인정보 유형은 같은 행의 선택 상자에서 지정합니다. **기본값으로 설정**을 선택하면 서버별 지정값을 해제하고 도구에 저장된 설정을 다시 따릅니다.
여러 도구를 바꾼 뒤 신청 사유를 입력하고 **저장**을 누르면 한 건의 승인 요청으로 묶입니다. 편집 내용을 적용하지 않으려면 **취소**를 누릅니다.
서버가 배포되지 않았거나 런타임 도구를 불러오지 못하면 목록 대신 안내 문구가 표시됩니다. 먼저 서버 배포 상태와 `tools/list` 응답을 확인하세요.
## 변경 승인 확인하기
변경 신청 직후에는 실제 도구 값이 바뀌지 않습니다. 화면에 **승인 대기**가 표시되고 같은 서버에 추가 변경을 신청할 수 없습니다.
승인 담당자가 결재를 승인하면 서버별 관리자 지정값에 반영됩니다. 반려된 요청은 기존 값을 유지합니다. 변경 이력에서는 신청 시점의 도구명, 신청자·결재자, 신청·결재 일시와 처리 사유를 확인할 수 있습니다.
## 행위 라벨 기본값 관리하기
최고 관리자는 **관리 > 환경 설정**에서 미선언 행위 라벨에 적용할 기본값을 정할 수 있습니다.
환경 설정의 행위 라벨 기본값
기본값을 바꾸면 해당 라벨을 선언하지 않은 도구의 해석도 함께 바뀝니다. 저장 전 안내 창에서 영향을 받는 도구 수를 확인한 뒤 진행하세요.
행위 라벨 기본값 변경 영향 안내
개인정보 유형에는 환경 공통 기본값이 없습니다. 서버 화면의 **기본값으로 설정**은 도구에 저장된 개인정보 유형을 상속하며, 도구에도 값이 없으면 빈칸으로 남습니다.
## Agent Gateway 정책 설정하기
**Agent Gateway > 접근 정책**에서 대상을 선택합니다.
Agent Gateway 접근 정책 대상 목록
대상 상세의 **접근 정책** 탭에서 **행위 라벨별 설정**을 펼쳐 정책을 설정합니다.
* 파괴적, 외부 연동: 차단 조건으로 사용
* 읽기 전용, 멱등성: 허용 조건으로 사용
* 기본값(상속): 상위 정책을 따름
차단 조건과 허용 조건이 동시에 맞으면 차단이 우선합니다. 차단 조건을 켜면 영향을 받는 도구 수가 저장 전에 표시됩니다.
행위 라벨을 사용하는 Agent Gateway 정책
도구별 설정이 있으면 라벨 정책보다 우선합니다. A2A 전용 대상은 요청에서 도구 이름을 확인할 수 없으므로 행위 라벨과 도구별 설정을 제공하지 않습니다.
## 개인정보 유형으로 서빙 호출 차단하기
개인정보를 다루는 도구가 실행된 대화 턴은, 그 뒤에 이어지는 서빙 호출을 서비스 라우터에서 막을 수 있습니다. 예를 들어 개인정보 입출력 도구를 쓴 턴은 외부 모델 리비전으로 나가지 못하게 할 수 있습니다.
도구가 실행되면 게이트웨이가 그 도구의 개인정보 유형을 같은 대화 턴에 기록해 둡니다. 관리자는 그 값을 조건으로 규칙을 만듭니다.
**서비스 라우터 > 라우터 정책 > 규칙 기반 라우팅**에서 **규칙 추가**를 누르고, 대상 유형에서 **임의 헤더**를 선택합니다.
규칙 기반 라우팅의 대상 유형 선택
헤더 이름과 값을 입력하고, **차단**을 선택한 뒤 막을 리비전을 지정합니다.
| 입력란 | 값 |
| ----- | ------------------------------------------------------------------------ |
| 헤더 이름 | `x-genos-mcp-tool-pii`(대화 턴 단위) 또는 `x-genos-mcp-tool-pii-session`(대화 전체) |
| 헤더 값 | `NONE` · `INPUT` · `OUTPUT` · `BOTH` 중 하나 |
**턴 단위와 대화 단위 중 무엇을 쓸까**
| 헤더 이름 | 판정 범위 | 유지 기간 |
| ------------------------------ | ------------------------- | ------- |
| `x-genos-mcp-tool-pii` | 도구를 호출한 **그 턴**의 후속 서빙 호출 | 약 10분 |
| `x-genos-mcp-tool-pii-session` | 그 도구를 한 번이라도 쓴 **대화 전체** | **무기한** |
대화 단위는 만료되지 않습니다. 개인정보 도구를 한 번 사용한 대화는 몇 달 뒤 다시 열어 이어서 대화해도 계속 차단 대상입니다. 새 대화를 시작하면 새로 판정합니다.
개인정보 유형 기반 차단 규칙
저장하면 해당 값이 기록된 턴의 요청은 지정한 리비전으로 가지 않습니다. 남은 리비전이 있으면 그쪽으로 흐르고, 후보가 모두 빠지면 요청은 오류로 응답합니다.
규칙은 위에서 아래 순서로 평가합니다. 여러 규칙을 두면 먼저 맞는 규칙이 적용됩니다.
**알아두기**
* 헤더 이름은 소문자 영문·숫자·하이픈만 입력할 수 있습니다. 대문자는 자동으로 소문자가 되고 그 외 문자는 지워집니다.
* 도구를 여러 번 호출하면 **가장 강한 값**이 남습니다(`없음` < `입력`·`출력` < `입출력`). 개인정보 도구 뒤에 일반 도구를 써도 표시가 지워지지 않습니다. 한 번에 여러 도구를 호출해도 마찬가지입니다.
* 차단된 도구 호출은 기록되지 않습니다. 도구가 실행되지 않았으므로 개인정보도 흐르지 않은 것으로 봅니다.
* 이 헤더를 호출자가 직접 실어 보내도 무시됩니다. 게이트웨이가 기록한 값만 사용합니다.
* 대화 단위 규칙은 채팅으로 들어온 호출에만 적용됩니다. 대화 식별자가 없는 외부 API 직접 호출은 이 규칙으로 판정할 수 없습니다.
## 표시가 예상과 다를 때
| 증상 | 확인할 내용 |
| ------------------------ | ---------------------------------------------------------------------------------------------------------------- |
| 개인정보 유형이 빈칸 | 아직 지정하지 않은 정상 상태입니다. `없음`으로 확정하려면 개인정보 유형에서 **없음**을 선택합니다. |
| 읽기 전용인데 파괴적·멱등성이 체크되어 보임 | 화면을 새로고침한 뒤 다시 확인합니다. 저장값은 읽기 전용 규칙에 따라 두 라벨을 `false`로 정규화합니다. |
| 변경 신청 뒤 값이 그대로임 | 승인 전에는 실제 값에 반영되지 않습니다. 승인 대기 배지와 결재 상태를 확인합니다. |
| 서버 상세에 도구가 없음 | MCP 서버 배포 상태와 런타임 `tools/list` 응답을 확인합니다. |
| gateway 정책이 예상대로 적용되지 않음 | 대상이 A2A 전용인지, 도구별 예외가 있는지, 정책 캐시가 승인 후 갱신됐는지 확인합니다. |
| 개인정보 유형 차단 규칙이 걸리지 않음 | 헤더 이름 철자와 값이 도구에 지정한 개인정보 유형과 같은지 확인합니다. 도구에 개인정보 유형이 지정되지 않았으면 기록 자체가 남지 않습니다. 대화 단위 규칙이면 채팅으로 들어온 호출인지도 확인합니다. |
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://genos-docs.gitbook.io/default/v1.9.3/basic-tutorials/guides/mcp/mcp-tool-labeling.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
