Google은 AI 기술을 사용하여 콘텐츠를 사용자의 기본 언어로 번역합니다. AI 번역에는 오류가 있을 수 있습니다.

MCP 연결 앱 통합 표준

MCP 서버는 앱의 기능(MCP 도구)을 연결된 앱 플랫폼에 연결하기 위한 프레임워크를 설정합니다. 서비스 결과를 더 안정적으로 선택, 호출, 처리할 수 있도록 하려면 MCP 구성이 다음 표준을 엄격하게 준수해야 합니다.

기본 원칙

각 함수에 대해 함수의 기능이 아닌 사용자 의도와 사용 사례에 초점을 맞춥니다. 설명은 도구의 용도와 도구가 응답할 수 있는 사용 사례를 모델에 알리는 기본 방법입니다.

버전 관리

확장 가능하고 강력한 MCP 배포를 지원하려면 경로 기반 버전 관리를 활용하는 구조화된 URI 아키텍처를 채택하세요(예: /v1, /v2). 이렇게 하면 이전 버전과의 호환성을 유지하고 새로운 기능을 제어할 수 있습니다. 이를 https://gemini.mcp.company.com/mcp/v1와 같은 제공업체별 하위 도메인으로 보완하면 세분화된 트래픽 관리와 다양한 AI 모델의 고유한 컨텍스트 및 처리 동작에 맞게 조정된 도구 정의 최적화가 가능합니다.

MCP 프로토콜 버전 호환성

연결된 앱 플랫폼은 버전 2025-11-25까지의 모델 컨텍스트 프로토콜(MCP) 사양을 지원합니다. 최신 사양 버전은 아직 지원되지 않습니다.

개발자 책임: initialize 핸드셰이크 중과 모든 도구 및 스키마 정의에서 MCP 서버가 연결된 앱 플랫폼(2025-11-25)에서 지원하는 프로토콜 버전을 엄격하게 준수하는지 확인할 책임은 개발자에게 있습니다.
플랫폼 하위 호환성: 연결된 앱 플랫폼은 향후 최신 MCP 사양 버전을 채택할 예정이지만, 클라이언트는 이전에 지원된 프로토콜 버전과의 하위 호환성을 유지하므로 기존 프로덕션 통합이 중단 없이 계속 작동합니다.
업그레이드 관리: 새로 지원되는 MCP 사양을 채택하거나 스키마 변경사항을 도입할 준비가 되면 활성 트래픽에 대해 기존 엔드포인트(/mcp/v1)를 유지하면서 새 버전이 지정된 URI 경로(예: /mcp/v2)에 해당 업데이트를 노출합니다.

앱 버전 간에 MCP 스키마를 변경할 수 있습니다. 이 기능을 활용하고 MCP 엔드포인트의 버전을 지정하여 새로운 기능을 원활하게 출시하거나 하위 호환 변경사항에 엄격하게 의존하는 것이 좋습니다.

전송 프로토콜 사양

연결된 앱 플랫폼은 스트리밍 가능한 HTTP 전송 모델 컨텍스트 프로토콜 사양 버전 2025-03-26 이상을 엄격하게 지원합니다. 2024-11-05 사양에 설명된 SSE 전송을 사용하는 기존 HTTP는 지원하지 않습니다.

단일 HTTP 엔드포인트. Connected Console에 제공된 MCP 엔드포인트(예: https://api.example.com/mcp)는 관련 Google 제품이 표준 HTTP POST를 통해 모든 JSON-RPC 요청(initialize, tools/list, tools/call)을 전송하는 단일 URL입니다.
스트리밍 가능한 HTTP 내의 SSE 스트리밍 기존 멀티 엔드포인트 SSE 전송은 지원되지 않지만 text/event-stream와 같은 서버 전송 이벤트는 스트리밍 가능한 HTTP 내에서 지원됩니다. 해당 Google 제품의 발신 요청에는 Accept: application/json, text/event-stream가 포함됩니다. 즉, 서버는 표준 application/json 페이로드를 반환하거나 HTTP POST 응답 본문에서 직접 Content-Type: text/event-stream를 사용하여 증분 응답을 스트리밍할 수 있습니다.
GET 스트림 및 405 허용되지 않는 메서드 클라이언트는 서버-클라이언트 알림을 위해 엔드포인트에서 선택적 GET 스트림을 시도할 수 있습니다. 서버가 스테이트리스(Stateless)이거나 요청-응답 전용인 경우 HTTP 405 Method Not Allowed 반환은 Google 관련 제품의 클라이언트 프록시에서 명시적으로 지원되고 깔끔하게 처리됩니다.

서버 안내

연결된 앱 플랫폼은 서버 요청 사항을 수집하도록 최적화되어 있어 다른 방법으로는 불가능한 수준으로 모델의 동작을 제어할 수 있습니다.

서버 안내를 따릅니다.

사용 컨텍스트가 있는 '모델 힌트'로 취급

모델에 힌트를 제공할 때는 다음 가이드라인을 따르세요.

LLM이 서버의 전반적인 목적과 기능을 이해하는 데 도움이 되는 상위 수준의 '힌트' 또는 가이드로 안내를 작성합니다.
기능을 나열하거나 모델이 서버의 도구와 리소스를 사용하는 방법을 설명하는 대신, 서버가 할 수 있는 작업을 설명합니다. 모델이 '무엇'을 올바르게 이해하면 사용자 여정을 기반으로 '어떻게'를 상당히 잘 결정할 수 있습니다.
이 텍스트는 모델의 시스템 프롬프트에 직접 추가된다고 가정합니다. 명확하고 지시적이며 토큰 효율적으로 유지합니다.

보완하되 중복하지 않기

이 공간은 모든 도구에 적용되는 전역 컨텍스트에 사용하며 개별 도구 설명과 중복되지 않도록 합니다.

서버 요청 사항 예시

다음 예는 서버 안내를 올바르게 작성하는 것과 관련된 권장사항과 권장하지 않는 사항을 보여줍니다.

권장됨 권장하지 않음

권장됨	권장하지 않음
전문적인 GitHub 저장소 관리자 역할을 해 줘. 이 서버는 저장소 메타데이터, Issue Tracker, PR 워크플로에 대한 심층 액세스를 제공합니다. 프로젝트 상태를 유지하고, 분류를 자동화하고, 코드 표준을 보장하는 데 사용하세요. 별도로 지정하지 않는 한 모든 작업은 인증된 조직의 컨텍스트 내에서 수행된다고 가정합니다. 오래된 대화목록이나 연결되지 않은 PR을 식별하여 저장소를 정리하는 데 우선순위를 두세요. 간결하고 지시적이며 모델을 보완하는 프롬프트 '방법'이 아닌 '무엇'(프로젝트 상태, 분류)을 정의함 모든 도구에 적용되는 인증 범위 언급	이 서버에는 GitHub용 도구가 있습니다. 사용자가 문제를 요청하면 `list_issues` 도구를 사용해야 합니다. `create_pull_request`를 사용하여 PR을 만들 수 있습니다. 이러한 도구를 신중하게 사용하여 사용자가 코드를 관리할 수 있도록 지원하세요. 도구를 호출하기 전에 항상 저장소 이름을 확인하세요. 사용자가 요약을 요청하는 경우 먼저 도구를 호출한 다음 출력을 요약합니다. 도구 이름을 다시 나열하지 않음, 모델에게 생각하는 '방법'을 알려주지 마세요. 이는 사용자 컨텍스트를 사용하여 올바른 선택을 하는 모델의 기본 제공 추론과 충돌할 수 있습니다. 서버 액세스의 특성이나 특정 제약 조건을 설명하지 않음)

전문적인 GitHub 저장소 관리자 역할을 해 줘. 이 서버는 저장소 메타데이터, Issue Tracker, PR 워크플로에 대한 심층 액세스를 제공합니다. 프로젝트 상태를 유지하고, 분류를 자동화하고, 코드 표준을 보장하는 데 사용하세요. 별도로 지정하지 않는 한 모든 작업은 인증된 조직의 컨텍스트 내에서 수행된다고 가정합니다. 오래된 대화목록이나 연결되지 않은 PR을 식별하여 저장소를 정리하는 데 우선순위를 두세요.

간결하고 지시적이며 모델을 보완하는 프롬프트

'방법'이 아닌 '무엇'(프로젝트 상태, 분류)을 정의함
모든 도구에 적용되는 인증 범위 언급

이 서버에는 GitHub용 도구가 있습니다. 사용자가 문제를 요청하면 list_issues 도구를 사용해야 합니다. create_pull_request를 사용하여 PR을 만들 수 있습니다. 이러한 도구를 신중하게 사용하여 사용자가 코드를 관리할 수 있도록 지원하세요. 도구를 호출하기 전에 항상 저장소 이름을 확인하세요. 사용자가 요약을 요청하는 경우 먼저 도구를 호출한 다음 출력을 요약합니다.

도구 이름을 다시 나열하지 않음,
모델에게 생각하는 '방법'을 알려주지 마세요. 이는 사용자 컨텍스트를 사용하여 올바른 선택을 하는 모델의 기본 제공 추론과 충돌할 수 있습니다.
서버 액세스의 특성이나 특정 제약 조건을 설명하지 않음)

도구 가이드라인

다음 가이드라인에서는 앱 내의 다양한 함수 또는 도구에 대한 MCP 서버 구성을 만들기 위한 권장사항을 설명합니다.

도구 이름 지정 규칙

도구 이름을 지정할 때는 다음 가이드라인을 따르세요.

직관적이고 인간이 읽을 수 있는 이름 사용

모호한 이름 대신 명확하고 직관적인 의미를 가진 인간이 읽을 수 있는 이름을 사용하세요. 예를 들어 get_user_information는 userInfo보다 더 간단합니다.

적절한 대소문자 스타일 준수

도구 함수 이름 및 앱 트리거에 다음 대소문자 규칙을 준수하세요.

도구 함수 대소문자. MCP 스키마에 정의된 도구 함수 이름에 snake_case 또는 camelCase를 사용합니다(예: get_user_information 또는 publishDraft).
앱 트리거 핸들 케이스. 앱 트리거 및 멘션(예: @MyTwoWordApp)은 대소문자를 구분하지 않습니다. 플랫폼은 소문자(@mytwowordapp), PascalCase(@MyTwoWordApp), camelCase(@myTwoWordApp)에서 사용자 입력을 정규화합니다.
표시 이름 형식 지정. UI 요소에 명확하게 표시되도록 PascalCase 또는 표준 공백을 사용하여 공식 앱 제목을 등록합니다.
오타 처리. 대소문자 변형은 자동으로 처리되지만 문자 오타(예: @mytwowrodapp)는 직접 문자열 일치가 아닌 대체 인텐트 인식에 의존합니다. 개발자는 문서에서 정확한 핸들 철자를 사용하도록 권장해야 합니다.

명시적인 동사-명사 이름 지정 사용

구체적인 verb_noun 이름을 사용하고 모호함을 피합니다. 예를 들어 publish_draft이 handle_content보다 더 좋습니다.

도구 세부사항

도구 세분화와 관련하여 다음 가이드라인을 준수하세요.

도구를 원자 엔드포인트로 취급

도구를 내부 도구 조건이나 각각의 필수 매개변수가 있는 여러 기능이 없는 원자적 엔드포인트로 취급합니다. 세분화된 도구를 사용하면 모델이 단계를 논리적으로 연결하여 할루시네이션을 줄일 수 있습니다.

더 평평한 스키마 사용

입력을 검증하기 위해 깊게 중첩된 객체나 복잡한 oneOf / anyOf 스키마 로직이 필요한 경우 도구가 너무 광범위할 수 있습니다.

사전 집계 및 페이로드 가드레일 준수

소규모의 범위가 지정된 페이로드의 경우 프로토콜에 따라 데이터를 미리 집계하는 것이 엄격하게 적용되지는 않지만, 대규모 레코드 세트, 장기 기록, 다중 소스 데이터 세트를 사용할 때는 실제로 백엔드 사전 집계가 반드시 필요합니다. 연결된 앱 플랫폼은 컨텍스트 윈도우 한도, 실행 지연 시간, 모델 추론 단계에 대한 가드레일을 적용합니다. 이러한 가드레일을 준수하려면 다음 가이드라인을 따르세요.

백엔드에서 필터링 및 요약 관련 Google 제품에 응답을 반환하기 전에 항상 MCP 서버에서 대규모 데이터 스트림을 필터링, 사전 집계 또는 요약하세요.
원시 덤프를 피합니다. 원시 데이터베이스 행이나 색인이 생성되지 않은 전체 로그를 도구 반환 페이로드에 덤프하지 마세요.

내부 및 메타 도구 생략

서버의 tools/list 응답에서 모델 관련 기능만 노출합니다.

도우미 도구 필터링: 모델에서 호출할 수 없는 내부, 관리 또는 메타 도구(예: 서버 상태 점검, 내부 설정 루틴, 개발자 유틸리티 도우미)를 생략합니다.
컨텍스트 윈도우 효율성: 불필요한 도구를 제외하면 MCP 스키마가 간결해지고, 컨텍스트 윈도우 토큰 소비가 줄어들며, 모델 도구 라우팅 혼동이 방지됩니다. 수십 개의 도구 또는 깊게 중첩된 '메가 도구' 스키마를 노출하는 MCP 서버는 검토 중에 수정이 필요한 것으로 신고됩니다.

도구 세분화 권장사항 및 금지사항

다음 예시에서는 도구 이름 지정 및 세분화 사용과 관련된 권장사항과 권장하지 않는 사항을 보여줍니다.

권장됨 권장하지 않음

권장됨	권장하지 않음
명확한 이름과 파라미터를 사용하는 세분화된 도구 각 도구의 입력 스키마는 엄격합니다. LLM이 사용자를 만들려면 이메일을 제공해야 합니다. 삭제하려면 ID를 제공해야 합니다. 추측할 필요가 없습니다. `... @mcp.tool() def create_user(email: str, role: str = "viewer") -> str: """Register a new user. Returns the new User ID.""" # Logic is purely creation return "user_123" @mcp.tool() def delete_user(user_id: str) -> str: """Permanently remove a user by their ID.""" # Logic is purely deletion return f"User {user_id} deleted" @mcp.tool() def update_user_role(user_id: str, new_role: str) -> str: """Change an existing user's permission level.""" return f"User {user_id} is now {new_role}" ...`	도구 이름: manage_user 설명: '이 도구를 사용하여 사용자를 생성, 업데이트, 삭제 또는 검색합니다.' ... @mcp.tool() def manage_user( action: Literal["create", "update", "delete", "get"], user_id: Optional[str] = None, email: Optional[str] = None, role: Optional[str] = "viewer" ) -> str: """ Use this to manage users. WARNING: logic is hidden inside Python, not visible in the schema. """ if action == "create": if not email: return "Error: Email required for creation" # Runtime error, not schema error return f"Created user {email}" elif action == "delete": if not user_id: return "Error: User ID required" return f"Deleted {user_id}" return "Action completed" """ ...

명확한 이름과 파라미터를 사용하는 세분화된 도구

각 도구의 입력 스키마는 엄격합니다. LLM이 사용자를 만들려면 이메일을 제공해야 합니다. 삭제하려면 ID를 제공해야 합니다. 추측할 필요가 없습니다.

...
@mcp.tool()
def create_user(email: str, role: str = "viewer") -> str:
    """Register a new user. Returns the new User ID."""
    # Logic is purely creation
    return "user_123"

@mcp.tool()
def delete_user(user_id: str) -> str:
    """Permanently remove a user by their ID."""
    # Logic is purely deletion
    return f"User {user_id} deleted"

@mcp.tool()
def update_user_role(user_id: str, new_role: str) -> str:
    """Change an existing user's permission level."""
    return f"User {user_id} is now {new_role}"

    ...

도구 이름: manage_user

설명: '이 도구를 사용하여 사용자를 생성, 업데이트, 삭제 또는 검색합니다.'

...
@mcp.tool()
def manage_user(
    action: Literal["create", "update", "delete", "get"],
    user_id: Optional[str] = None,
    email: Optional[str] = None,
    role: Optional[str] = "viewer"
) -> str:
    """
    Use this to manage users.
    WARNING: logic is hidden inside Python, not visible in the schema.
    """
    if action == "create":
        if not email: return "Error: Email required for creation" # Runtime error, not schema error
        return f"Created user {email}"
    elif action == "delete":
        if not user_id: return "Error: User ID required"
        return f"Deleted {user_id}"
    
    return "Action completed"
    """
    ...

안전을 위한 도구 주석 선언

도구 정의 내에서 프로토콜 주석을 구성하여 실행 동작을 전달하고 해당 Google 제품 전반에서 기본 제공되는 안전 게이트를 트리거합니다.

런타임 확인 게이트: 해당 Google 제품은 annotations.destructiveHint: true 및 annotations.openWorldHint: true를 런타임 사용자 확인 메시지를 트리거하는 키 플래그로 사용합니다. 상태 변경, 쓰기 또는 파괴적인 작업에 destructiveHint: true를 선언하고, 개방형 환경 또는 외부 환경과 상호작용하는 도구에 openWorldHint: true를 설정하여 실행 전에 인터페이스가 사용자에게 확인을 요청하도록 합니다.
읽기 전용 쿼리 힌트: 백엔드 상태를 수정하지 않고 데이터만 가져오는 쿼리 도구에 readOnlyHint: true를 설정합니다.
명시적 주석 기본값: Model Context Protocol 사양에 따라 readOnlyHint를 생략하면 클라이언트는 안전을 위해 기본적으로 readOnlyHint: false 및 destructiveHint: true를 가정합니다. 모든 도구에 주석을 명시적으로 선언하면 예측 가능한 모델 라우팅과 적절한 실행 안전성이 보장됩니다.

도구 설명

설명은 모델이 도구로 현재 문제를 해결할 수 있는지 결정하는 데 사용할 수 있는 유일한 컨텍스트입니다. 설명을 작성할 때는 다음 가이드라인을 따르세요.

의견이 아닌 요청 사항 작성하기

도구 설명은 수동적인 경우가 많은 코드 주석이 아닌 안내로 작성합니다. LLM은 지시문에 잘 반응합니다.

'방법' 설명

좋은 설명은 '도구가 있다'와 '이 도구를 대화에 연결하는 방법을 알고 있다' 사이의 격차를 해소합니다.

'이유' 설명

이 도구를 유사한 도구와 구분합니다(예: '내부 사용자의 경우 이 도구를 사용하고 외부 사용자의 경우 customer_update를 사용').

링크 제공

인수를 찾을 위치를 모델에 알려줍니다(예: 'order_search 도구에서').

형식 지정

단위(미터 또는 피트)와 형식(ISO 날짜, 시맨틱 버전)을 지정합니다.

모델 재량 방지

모델에 '최선의 판단'을 사용하도록 지시하거나 안내되지 않은 선택적 작업을 제안하지 마세요.

도구 설명 예시

다음 예시는 도구 설명을 작성할 때 권장사항과 피해야 할 사항을 보여줍니다.

권장됨 권장하지 않음

권장됨	권장하지 않음
정보 소스 "사용자의 이메일을 업데이트합니다. `search_users` 도구에서 반환된 UUID 'id'를 엄격하게 사용해야 합니다. 사용자 ID를 추론하거나 추측하지 마세요." (한 도구의 출력을 이 도구의 입력에 명시적으로 연결합니다.)	'사용자의 이메일 주소를 업데이트합니다.' (모델이 12345와 같은 ID를 추측할 수 있습니다.)
형식 및 제약조건 "회의 일정 예약해 줘. 'date'는 ISO 8601 형식(YYYY-MM-DD)이어야 합니다. 사용자가 '내일' 또는 다른 상대적 참조를 말하는 경우 현재 컨텍스트를 기반으로 날짜를 계산합니다."	"지정된 날짜에 회의 일정을 예약해 줘." (사람에게는 올바르게 보이지만(예: '내일') 스키마 검증에 실패함('2025-10-12' 필요))
출력 기대치 "서버 로그를 검색합니다. 원시 텍스트의 마지막 50줄을 반환합니다. 분석을 위해 토큰 한도를 초과하지 않도록 더 짧은 기간을 요청하세요."	서버 로그를 가져옵니다. (모델이 요약을 예상하는 도구를 호출하고 원시 5MB JSON 덤프를 가져와 사용자 환경이 저하될 수 있습니다.)
`@mcp.tool() def update_campaign_status(campaign_id: str, status: str) -> str: """ Promotes or pauses an advertising campaign. CRITICAL USAGE RULES: 1. 'campaign_id': Must be the 32-character UUID retrieved from 'list_campaigns'. 2. 'status': Must be exactly one of: ['active', 'paused', 'archived']. Returns: A confirmation string with the new status and timestamp. """ # Logic... ...` 이 설명은 미니 설명서 역할을 합니다. 소스(ID를 가져올 위치), 제약 조건(유효한 enum), 작업을 처리합니다.	`@mcp.tool() def update_campaign_status(id: str, status: str) -> str: """ Updates the campaign status in the database. """ # Logic...` 이 방법은 변수 이름을 사용하여 모든 작업을 수행합니다. 모델이 'status'의 유효한 값을 추측하게 합니다.

정보 소스

"사용자의 이메일을 업데이트합니다. search_users 도구에서 반환된 UUID 'id'를 엄격하게 사용해야 합니다. 사용자 ID를 추론하거나 추측하지 마세요."

(한 도구의 출력을 이 도구의 입력에 명시적으로 연결합니다.)

'사용자의 이메일 주소를 업데이트합니다.'

(모델이 12345와 같은 ID를 추측할 수 있습니다.)

형식 및 제약조건

"회의 일정 예약해 줘. 'date'는 ISO 8601 형식(YYYY-MM-DD)이어야 합니다. 사용자가 '내일' 또는 다른 상대적 참조를 말하는 경우 현재 컨텍스트를 기반으로 날짜를 계산합니다."

"지정된 날짜에 회의 일정을 예약해 줘."

(사람에게는 올바르게 보이지만(예: '내일') 스키마 검증에 실패함('2025-10-12' 필요))

출력 기대치

"서버 로그를 검색합니다. 원시 텍스트의 마지막 50줄을 반환합니다. 분석을 위해 토큰 한도를 초과하지 않도록 더 짧은 기간을 요청하세요."

서버 로그를 가져옵니다.

(모델이 요약을 예상하는 도구를 호출하고 원시 5MB JSON 덤프를 가져와 사용자 환경이 저하될 수 있습니다.)

@mcp.tool()
def update_campaign_status(campaign_id: str, status: str) -> str:
    """
    Promotes or pauses an advertising campaign.
    
    CRITICAL USAGE RULES:
    1. 'campaign_id': Must be the 32-character UUID retrieved from 'list_campaigns'.
    2. 'status': Must be exactly one of: ['active', 'paused', 'archived'].
    
    Returns: A confirmation string with the new status and timestamp.
    """
    # Logic...

    ...

이 설명은 미니 설명서 역할을 합니다. 소스(ID를 가져올 위치), 제약 조건(유효한 enum), 작업을 처리합니다.

@mcp.tool()
def update_campaign_status(id: str, status: str) -> str:
    """
    Updates the campaign status in the database.
    """
    # Logic...

이 방법은 변수 이름을 사용하여 모든 작업을 수행합니다. 모델이 'status'의 유효한 값을 추측하게 합니다.

도구 파라미터

도구 자체 외에도 매개변수를 명확하게 설명합니다.

명시적 유형

강력하고 구체적인 유형(string, integer, boolean, array)을 사용합니다.

고정 값 집합에 enum 사용

매개변수가 고정된 값 집합(예: daylight, cool, warm)만 허용하는 경우 enum 배열에 나열합니다. 이렇게 하면 정확도가 크게 향상됩니다.

필수 매개변수를 명확하게 명시

함수가 작동하는 데 필수인 파라미터를 명확하게 정의합니다.

시맨틱 스키마 일치 적용

앱을 통합할 때 도구 매개변수와 개발 중인 카테고리의 시맨틱 스키마 일치가 필요할 수 있습니다. 온보딩 프로세스 중에 예상 카테고리 스키마(JSON 스키마)를 받게 됩니다.

도구 파라미터 예시

다음 예시에서는 도구 매개변수 처리와 관련된 권장사항과 권장하지 않는 사항을 보여줍니다.

권장됨	권장하지 않음
인수 형식 및 단위 radius: '반경(미터)입니다. 0보다 큰 부동 소수점 수여야 합니다." (단위 할루시네이션 방지)	radius: '원의 반지름'
ID 형식 및 컨텍스트 user_id: "데이터베이스 UUID(예: 550e8400-e29b…). 이메일 주소를 사용하지 마세요." 참고: 모든 숫자 ID 필드는 문자열 값으로 처리하는 것이 좋습니다. 특히 ID가 10자리 이상인 경우 내부 시스템에 의해 잘리거나(32비트 컨테이너로 강제 변환) 이 버전이 향후 도구 호출에서 모델에 의해 사용될 위험이 있습니다. (유형 오류 방지)	user_id: "사용자의 ID입니다."
반환 값 기대치 "레코드를 업데이트하고 새 타임스탬프를 포함한 업데이트된 JSON 객체를 반환합니다." (모델에 변경사항을 확인하기 위해 'update' 직후에 'get' 도구를 호출할 필요가 없다고 알려줍니다.)	"기록을 업데이트합니다."
`@mcp.tool() def search_logs(query: str, limit: int = 10) -> str: """ Searches server error logs using Lucene syntax (e.g. 'level:ERROR AND service:auth'). Args: query: A Lucene-formatted search string. limit: Max results to return. capped at 50. Returns: A formatted string of log entries with timestamps. """ ...`	`@mcp.tool() def search_logs(query: str, limit: int = 10) -> str: """Searches the logs.""" ...` LLM은 '쿼리'가 지원하는 문법(SQL? 정규식? 일반 텍스트?) 최대 '한도'가 무엇인지 알 수 없습니다.

응답 및 오류 처리

대답은 다음 프롬프트라는 핵심 원칙에 따라 도구는 데이터 페이로드를 반환하여 기본 실행 결과를 보고하고, 이 페이로드는 LLM의 컨텍스트 창에 직접 붙여넣어집니다. 결과의 성공 또는 실패에 따라 다음 단계가 결정됩니다.

성공한 경우: 모델은 다음 단계를 결정하기 위해 어떤 일이 발생했는지 알 수 있는 반환 값이 필요합니다.
실패하는 경우: 모델은 실패한 이유와 해결 방법을 알아야 합니다. 비정상 종료(500 오류)는 대화를 중지합니다. 설명 오류 메시지를 사용하면 모델이 자체 수정할 수 있습니다.

도구의 기본 로직이 성공하든 실패하든 모델이 쉽게 파싱할 수 있도록 반환 값 페이로드의 형식을 지정해야 합니다. 응답 페이로드를 패키징할 때는 다음 권장사항을 따르세요.

JSON 사용

TextContent에서 구조화된 데이터의 형식을 지정합니다(임시 제약 조건). structuredContent은 아직 연결된 앱 플랫폼에서 지원되지 않으므로 데이터를 수동으로 직렬화합니다. 간단한 목록을 반환하더라도 json.dumps()합니다.

대답에 URL 포함

반환되는 URL은 비교적 짧고 매개변수가 많지 않아야 합니다. 토큰 수를 절약하고 할루시네이션 위험을 줄이려면 URL 단축 서비스를 사용하는 것이 좋습니다.

자체 설명적 할루시네이션 방지 페이로드

원시 코드 또는 내부 ID는 항상 인간이 읽을 수 있는 표시 이름, 명시적인 측정 단위, 참조 범위와 함께 표시합니다. 모델이 컨텍스트를 추론하도록 강제하는 압축된 사전 키나 매핑되지 않은 숫자 코드를 반환하지 마세요.

오류를 효과적으로 처리합니다.

모델이 무엇이 잘못되었는지 이해하고 사용자에게 알릴 수 있도록 명확하고 의미 있는 오류 메시지를 반환합니다. MCP 오류 처리를 참고하세요.

try/except 사용

도구 로직을 try/except 블록으로 래핑하고 문자열화된 오류를 반환합니다.

조치 가능한 오류 제공

오류 메시지에서 다음 단계를 제안합니다(예: '먼저 X 도구를 사용해 보세요').

작업 확인

부작용 도구(만들기/업데이트/삭제)에 빈 문자열을 반환하지 마세요.

응답 및 오류 처리 예시

다음 예는 응답 및 오류 처리와 관련된 권장사항과 권장하지 않는 사항을 보여줍니다.

권장됨	권장하지 않음
명시적 직렬화 `... import json @mcp.tool() def query_metrics(metric_id: str) -> str: result = {"id": metric_id, "value": 42, "unit": "ms"} # GOOD: Returns '{"id": "cpu", "value": 42}' -> Valid JSON return json.dumps(result, indent=2)`	`... @mcp.tool() def query_metrics(metric_id: str) -> str: result = {"id": metric_id, "value": 42, "unit": "ms"} # BAD: Returns "{'id': 'cpu', 'value': 42}" -> Invalid JSON return str(result)`
포착 및 알림 `... @mcp.tool() def get_user_details(user_id: str) -> str: try: user = db.get_user(user_id) if not user: # GOOD: Informative error returned as content return f"Error: User with ID '{user_id}' not found. Please verify the ID using 'search_users'." return json.dumps(user) except Exception as e: return f"Error: Database connection failed ({str(e)}). Please try again later."` 도구는 기술적으로 '성공'하여 문자열을 반환하지만, 문자열에 오류 세부정보가 포함되어 있습니다. 모델은 이를 읽고 '아, 해당 ID가 존재하지 않는구나'라고 인식하고 사용자에게 올바른 ID를 요청할 수 있습니다.)	`... @mcp.tool() def get_user_details(user_id: str) -> str: # BAD: Unhandled exception if ID not found user = db.get_user(user_id) return json.dumps(user)` (`get_user`가 실패하면 서버에서 500 오류가 발생합니다. LLM은 일반적인 실행 오류를 수신하며 그 이유를 알지 못합니다(ID가 잘못되었나요? 데이터베이스가 다운되었나요? 권한이 거부되었나요?) 잘못된 입력을 정확히 동일하게 다시 시도할 가능성이 높습니다.)
비어있는 응답 `... @mcp.tool() def post_story(story_content: str) -> str: service_name = "story_service" api_client.post("/stories", json={"content": story_content}) # GOOD: Explicit confirmation of state change. return f"Service '{service_name}' successfully posted content. Status is now 'posted'."`	`... @mcp.tool() def post_story(storyContent: str): subprocess.post(["postsrv", "story", storyContent]) # BAD: Returns null/empty string. Model is confused.` LLM은 빈 응답으로 인해 혼동을 일으키는 경우가 많습니다. '도구 실패'라는 할루시네이션을 일으키거나 호출을 반복할 수 있습니다.
자체 설명적 할루시네이션 방지 페이로드 원시 코드 또는 내부 ID는 항상 사람이 읽을 수 있는 표시 이름, 명시적인 측정 단위, 정상 기준 범위와 함께 표시해야 합니다. `{"lab_code": "2345-7", "display_name": "Glucose [Mass/volume] in Blood", "value": 105, "unit": "mg/dL", "reference_range": "70-99 mg/dL"}` (이렇게 하면 모델이 단위나 참조 기준점을 추론하지 않고도 값의 의미를 정확하게 파악할 수 있습니다.)	원시 ID, 맞춤 압축 또는 매핑되지 않은 코드 라벨 없이 원시 내부 ID, 맞춤 사전 약어 또는 숫자 코드를 반환합니다. `{"code": "2345-7", "v": 105}` (모델이 105가 무엇을 의미하는지 추측해야 하므로 단위가 잘못되거나, 컨텍스트가 누락되거나, 설명이 부정확해질 수 있습니다.)

MCP 오류 처리

오류를 원활하게 처리하는 것이 중요합니다.

복구 가능한 오류(예: 잘못된 사용자 ID 또는 누락된 선택적 매개변수)의 경우 도구 응답에 설명적인 오류 세부정보가 포함된 일반 텍스트 문자열을 반환합니다. 이를 통해 모델은 피드백을 검사하고, 무엇이 잘못되었는지 이해하고, 자체 수정하거나 사용자에게 설명을 요청할 수 있습니다.
터미널 오류(예: 비율 제한, 인증 또는 권한 실패, 백엔드 서버 중단)의 경우 플랫폼이 실패를 체계적으로 처리할 수 있도록 적절한 오류 코드와 함께 McpError를 발생시킵니다.

오류 응답 본문 예시(JSON)

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32302,
    "message": "User permission denied for the requested operation.",
    "data": null
  },
  "id": 1
}

Message에는 MCP의 ErrorData 필드의 JSON 덤프가 포함됩니다. 연결된 앱 플랫폼은 올바른 code와 모델에 표시되는 message를 반환하여 오류 메시지를 읽고 유용한 자연어 설명을 사용자에게 다시 전달할 수 있습니다. 예를 들어 "죄송합니다. 해당 ID의 공연 무대를 찾을 수 없습니다. 이름을 확인해 주시겠어요?"

MCP를 사용하면 클라이언트가 JSON-RPC 2.0 사양을 사용하여 MCP 서버에 연결할 수 있습니다. JSON-RPC에는 잘못된 요청, 파싱 오류 등 일반적으로 발생하는 오류에 대해 전송되는 사전 정의된 오류가 있습니다. 이 가이드에서는 MCP 서버가 커스텀 오류를 다시 전송하는 방법을 설명합니다.

상태 코드	메시지	사용	명시적으로 반환 해야 하나요?
사용자/고객 오류
-32300	USER_RATE_LIMITED	사용자가 최대 사용량 한도에 도달했습니다.	예
-32301	MISSING_REQUIRED_INFORMATION	입력 요청에 필요한 정보가 모두 포함되어 있지 않습니다.	예
-32302	USER_PERMISSION_DENIED	사용자가 도구 사용 권한을 거부했습니다. 예를 들어 사용자에게 회사 계정, 연령 제한, 언어 등이 필요하거나 도구의 기업 구독이 없어야 합니다.	예
애플리케이션 오류/비즈니스 로직 오류
-32400	RUNTIME_ERROR	서버 코드 실행에서 오류가 발생했습니다.	예
-32401	NULL_POINTER_EXCEPTION	null 포인터/객체 실행 시도	예
-32402	OUT_OF_MEMORY	서버 코드에서 객체에 할당할 메모리가 부족함	예
인프라 오류
-32500	DEADLINE_EXCEEDED	요청이 허용된 시간보다 오래 걸립니다. 서버 과부하, 네트워크 문제 등 다양한 이유로 발생할 수 있습니다.	예
-32501	RESOURCE_EXHAUSTED	서버의 메모리, 디스크 공간, 스레드, CPU 시간 등이 부족합니다.	예
-32502	SERVICE_UNAVAILABLE	종속 서비스(예: 다른 마이크로서비스, 데이터베이스, 캐시 등)를 사용할 수 없음	예
JSON-RPC 오류(이 오류는 MCP 전송의 일부임)
-32700	PARSE_ERROR	서버에서 요청을 파싱할 수 없음	아니요
-32600	INVALID_REQUEST	잘못된 형식의 클라이언트 요청	아니요
-32601	METHOD_NOT_FOUND	잘못된 MCP 도구 이름	아니요
-32602	INVALID_PARAMS	잘못된 요청 매개변수(누락된 매개변수 또는 일치하지 않는 매개변수 유형 포함)	아니요
-32603	INTERNAL_ERROR	기본 대응	아니요

다음은 공식 Python SDK(mcp)를 사용하여 서버에서 MCP 오류를 발생시키는 방법의 예입니다. ErrorData 페이로드가 포함된 McpError를 발생시키면 SDK가 오류 상태가 채워진 필수 JSON-RPC 오류 형식으로 자동으로 직렬화합니다.

from mcp import types
from mcp.shared.exceptions import McpError

@mcp.tool()
def foo_tool() -> list[types.TextContent]:
  """Always returns an error."""
  raise McpError(
    types.ErrorData(
        code=-32302, # USER_PERMISSION_DENIED
        message="Message to show to the model."
    ),
  )

도구 정보

해당 Google 제품은 MCP 서버에 신호를 전달하기 위한 Tool Context API를 지원합니다. 이 API는 민감한 정보가 필요한 유효한 사용 사례에 사용됩니다. 예를 들어 현지화가 필요한 도구의 언어와 같이 핵심 도구 정의의 일부가 아닌 메타데이터가 있습니다. Tool Context API는 Connected Console을 통해서만 노출됩니다.

Connected Console에서 앱에 current_user_location_fine와 같은 신호를 등록하면 관련 Google 제품에서 요청된 데이터를 제공하는 추가 _meta 항목으로 MCP tools/call 요청을 보강합니다. 지원되는 신호 집합은 다음과 같습니다.

current_user_location_fine(Gemini만 해당, 허용된 카테고리)
user_locale
current_user_location_coarse

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "find-restaurant",
    "arguments": {"query": "restaurants near me"},
    "_meta": {
      "current_user_location_fine": {
        "latitude_degrees": 37.7749,
        "longitude_degrees": -122.4194,
        "accuracy_meters": 112.4221
      },
      "user_locale": {
        "language_code": "en",
        "region_code": "US"
      }
    }
  }
}

이 데이터를 분석하려면 다음 단계를 따르세요.

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("remote_mcp")

@mcp.tool()
async def find_restaurants(query: str, ctx: Context) -> str:
   # Access context directly from _meta
   request_context = ctx.request_context
   meta_dict = ctx.request_context.meta.model_dump() if ctx.request_context.meta else {}

   location_context = meta_dict.get("current_user_location_fine", {})
   lat = location_context.get("latitude_degrees")
   lng = location_context.get("longitude_degrees")
   if lat and lng:
       return f"Finding '{query}' near ({lat}, {lng})"
   return f"Finding '{query}' (no location provided)"

UX 렌더링

MCP 앱

해당 Google 제품은 맞춤 사용자 인터페이스를 빌드할 수 있도록 선택한 사용자 여정에 대한 MCP 앱 통합을 지원합니다. 일반 통합 안내는 사양을 따르세요.

해당 Google 제품에 MCP 앱을 통합할 때는 다음과 같은 주의사항이 있습니다.

등록 시 리소스 수집

해당 Google 제품은 도구 목록 및 도구 설명과 마찬가지로 도구 수집 시 UI 리소스를 가져옵니다. 즉, JavaScript 변경사항과 같은 리소스 업데이트가 자동으로 선택되지 않으며 도구 재수집이 필요합니다.

단일 UI 리소스의 크기는 15MB를 초과해서는 안 되며, 서버 전체의 누적 UI 리소스는 100MB를 초과해서는 안 됩니다.

UI 리소스는 지원되는 MIME 유형(text/html, text/javascript, text/css, text/html;profile=mcp-app) 중 하나를 사용해야 합니다. 비표준 또는 플랫폼별 MIME 유형은 미리보기에 푸시할 때 유효성 검사에 실패합니다.

CSP 가이드라인

해당 Google 제품은 CSP [1], [2]를 포함하는 공식 MCP 앱 사양을 따르며 CSP 지시어를 위반하는 모든 요청을 차단합니다.

해당 Google 제품은 사용하는 경우 CSP에 blob: 및 data:를 추가해야 합니다. 이러한 항목은 기본적으로 추가되지 않습니다. CSP에 추가할지 여부는 개발자가 선택합니다.

script-src는 예외

허용되는 유일한 지시문은 unsafe-inline(기본적으로 추가됨), wasm-unsafe-eval, data:(resource_domains에 포함된 경우)입니다. iframe이 외부 스크립트를 로드하는 경우 JS를 HTML로 번들링하거나 하위 리소스 무결성(SRI) 해시를 사용하여 해결할 수 있습니다.

옵션 1: JS를 HTML에 인라인/번들로 포함(가장 간단함)
- 번들 JS 코드:
  - UI 리소스에 반환된 HTML 페이로드의 <script> 태그 내에 component-init.js의 콘텐츠를 직접 인라인합니다.
```
<script>
// Paste component-init.js content directly here
</script>
```
- 원격 <script src> 태그 삭제
  - HTML 문서에서 <script src="https://api.mycompany.com/..."> 참조를 삭제합니다.
- 재수집/업데이트 도구
옵션 2: 하위 리소스 무결성(SRI) 해시 사용:

스크립트가 https://api.company.com/...에서 외부 호스팅 상태를 유지해야 하는 경우에 사용합니다.
- 스크립트의 SHA-256 해시 계산
  - component-init.js의 base64 SHA-256 해시를 생성합니다.
- resourceDomains에 해시 추가(integrity 속성과 일치하도록 sha256- 프리픽스를 포함해야 함)
- HTML <script> 태그 업데이트
  - HTML 위젯의 스크립트 태그에 integrity 및 crossorigin 속성을 추가합니다.
- CDN/서버에서 CORS 헤더 확인
  - 브라우저가 SRI 확인을 위해 응답 본문을 읽을 수 있도록 api.company.com가 Access-Control-Allow-Origin: *를 사용하여 component-init.js를 제공하거나 scf.usercontent.goog를 허용하는지 확인합니다.
- 재수집/업데이트 도구

MCP 도구 설명에 관한 보안 가이드라인

설명은 모델이 도구의 기능을 이해하는 데 필요한 유일한 컨텍스트이므로 의도하지 않은 동작을 방지하기 위해 정확하고 안전하게 작성해야 합니다. 도구 설명을 작성할 때는 다음 가이드라인을 준수하세요.

기능을 설명하되 동작을 지시하지 마세요. 설명은 모델이 후속 작업을 수행하도록 명령하는 것이 아니라 도구의 기능을 정확하게 설명해야 합니다.
범위 및 요구사항을 정의합니다. 도구의 기본 목표, 사용해야 하는 특정 상황(시기), 필요한 모든 입력(파라미터/인수)을 명확하게 명시합니다.
진실성 보장. 설명은 도구의 기본 코드를 정확하게 표현해야 합니다. 도구가 쓰기 또는 삭제 작업을 수행하는 경우 도구가 읽기 전용이라고 주장하지 마세요.

보안 위험 및 방지 방법

위험 영역	권장됨	이러한 관행은 반드시 피해야 합니다
프롬프트 인젝션	객관적이고 선언적인 언어를 사용하여 도구의 목적과 기능을 명확하게 설명합니다.	명령형 명령어를 사용하여 모델 동작을 재정의하거나 시스템 흐름을 변경합니다(예: '…라고 말해야 합니다', '실행 후에는 반드시…'). MUST 또는 CRITICAL과 같은 명령형 용어는 구조화된 매개변수 제약 조건 또는 사용 규칙을 정의할 때만 허용됩니다.
	도구 설명 텍스트에는 표준 일반 서식을 사용합니다.	과도한 대문자 사용, `VERY IMPORTANT:` 또는 `CRITICAL`와 같은 태그 등 시선을 끄는 서식을 사용합니다.
	도구의 기능과 예상되는 동작에만 집중합니다.	역할극 지침 또는 이전 지침을 무시하는 명령어를 포함합니다.
도구 섀도잉 및 하이재킹	설명은 구체적이어야 하며 도구의 실제 관련 기능으로 제한되어야 합니다.	도구 설명을 지나치게 광범위하거나 모호하게 작성하거나, 하나의 도구가 관련 없는 여러 기능을 수행한다고 주장합니다.
	고유하고 설명이 포함된 적절한 도구 이름을 선택합니다.	신뢰할 수 있는 도구의 이름을 약간 변형한 도구 이름 또는 일반적인 이름(예: `do_everything_tool`, `assistant_tool`)을 사용합니다.
	설명에 다른 앱이나 외부 플랫폼 도구의 이름을 언급하지 마세요.	다른 도구를 명시적으로 참조하거나 다른 도구를 언제 어떻게 사용해야 하는지에 관한 새로운 규칙을 만듭니다.
	모델의 플래너가 사용자 컨텍스트를 기반으로 가장 적절한 도구를 선택하도록 허용합니다.	반경쟁적 표현이나 유사한 도구보다 내 도구를 선호하도록 모델에 지시하는 모든 종류의 SEO 프롬프트를 포함합니다.
트리거 조작	설명이 일반적인 대화 기록 문구를 참조하거나 이에 반응하지 않습니다.	일반적이고 무해한 사용자 문구(예: '감사합니다', '요약하자면')를 기반으로 유해한 작업을 트리거하는 조건부 로직을 만듭니다.
매개변수 악용	도구의 기능에 필요한 파라미터만 정의하고 입력 데이터에 맞는 이름(예: `file_id`, `search_term`)을 사용합니다.	에이전트의 내부 상태를 반영하는 이름(예: `system_prompt`, `conversation_history`, `full_context`)으로 함수 파라미터를 정의합니다.
데이터 무단 반출	개인 정보 보호 중심 설계 - 불투명 식별자 및 호스트 관리 인증 원시 PII가 아닌 민감하지 않은 ID를 사용합니다. 모든 데이터 처리는 승인된 보안 경계 내에서 이루어져야 하며, 공개 설명에서 외부로 전송되는 것으로 참조되어서는 안 됩니다. 도구 실행은 OAuth 핸드셰이크를 통해 권한을 자동으로 상속합니다. 민감한 정보는 관련 Google 제품으로 전송하기 전에 삭제해야 합니다.	사용자, 개인 또는 비즈니스 데이터, 법인으로부터 관련 Google 제품의 서비스 약관을 위반하는 방식으로 PII, PHI 또는 기타 개인 정보 및/또는 민감한 정보를 요청합니다. 사용자 데이터(질문, 위치, 컨텍스트)를 승인되지 않은 서드 파티 URL, 로깅 서비스 또는 외부 시스템으로 전송하도록 언급하거나 요구합니다.

기능 및 이름 지정 권장사항

도구의 설명을 보호하는 것 외에도 모델이 혼동 없이 안정적으로 도구를 선택하고 실행할 수 있도록 해야 합니다. 다음 기능 및 이름 지정 권장사항을 준수합니다.

매개변수 정확성. 설명의 모든 매개변수 이름과 유형이 도구의 실제 구현과 정확히 일치하는지 확인합니다.
합리적인 이름 지정. 도구 이름은 기능에 관한 강력하고 명확한 힌트여야 합니다. 'execute'와 같이 지나치게 일반적인 이름은 사용하지 마세요. 이름은 더 광범위한 도구 생태계와도 일치해야 합니다.

부록: 인프라 및 네트워크 허용 목록 추가

호스팅 인프라, API Gateway, 또는 방화벽이 소스 IP 주소로 수신 연결을 제한하는 경우 다음 Google 아웃바운드 CIDR 블록을 허용 목록에 추가합니다.

108.177.64.0/20
142.250.88.0/22
172.217.80.0/20
192.178.20.0/22
192.179.0.0/20
74.125.232.0/24
136.121.40.0/21

해당 Google 제품이 MCP 초기화, 도구 검색, 요청 실행을 위해 원격 MCP 서버에 도달할 수 있도록 환경에서 HTTPS 포트 443의 이러한 IP 범위에서 발생하는 트래픽을 허용해야 합니다.

MCP 연결 앱 통합 표준 컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

기본 원칙

버전 관리

MCP 프로토콜 버전 호환성

전송 프로토콜 사양

서버 안내

사용 컨텍스트가 있는 '모델 힌트'로 취급

보완하되 중복하지 않기

서버 요청 사항 예시

도구 가이드라인

도구 이름 지정 규칙

직관적이고 인간이 읽을 수 있는 이름 사용

적절한 대소문자 스타일 준수

명시적인 동사-명사 이름 지정 사용

도구 세부사항

도구를 원자 엔드포인트로 취급

더 평평한 스키마 사용

사전 집계 및 페이로드 가드레일 준수

내부 및 메타 도구 생략

도구 세분화 권장사항 및 금지사항

안전을 위한 도구 주석 선언

도구 설명

의견이 아닌 요청 사항 작성하기

'방법' 설명

'이유' 설명

링크 제공

형식 지정

모델 재량 방지

도구 설명 예시

도구 파라미터

명시적 유형

고정 값 집합에 enum 사용

필수 매개변수를 명확하게 명시

시맨틱 스키마 일치 적용

도구 파라미터 예시

응답 및 오류 처리

JSON 사용

대답에 URL 포함

자체 설명적 할루시네이션 방지 페이로드

오류를 효과적으로 처리합니다.

try/except 사용

조치 가능한 오류 제공

작업 확인

응답 및 오류 처리 예시

MCP 오류 처리

도구 정보

UX 렌더링

MCP 앱

등록 시 리소스 수집

CSP 가이드라인

MCP 도구 설명에 관한 보안 가이드라인

부록: 인프라 및 네트워크 허용 목록 추가

MCP 연결 앱 통합 표준