1단계는 백엔드와 AI 서버의 REST 계약을, 3단계는 데이터 소유권과 배포 경계를, 5단계는 취향 프로필로 상품을 찾는 검색 증강 추천을 정했다. 6단계는 이 기능을 외부 AI 에이전트가 어떻게 안전하게 사용하고, 니쥬가 외부 컨텍스트와 커머스 도구를 어디까지 이용할지를 정한다.

니쥬는 하나의 범용 Remote MCP 서버를 만들고 PlayMCP, Claude, ChatGPT 등 MCP를 지원하는 여러 AI Host에 같은 엔드포인트와 Tool 계약을 제공한다. 추천 Tool은 사용자 동의와 공개 범위 안에서 취향 요약, 어떤 물건이 적합한지에 대한 추천 의도, 니쥬가 보유한 실제 상품 후보를 한 번에 반환한다. MCP는 내부 REST를 대체하지 않고 외부 에이전트에 공개할 얇은 표준 어댑터로만 사용한다.

검증 기준일: 2026-09-14. MCP Host마다 지원 기능, 요금제, 관리자 설정과 결과 UI가 다르다. PlayMCP는 원격 Streamable HTTP 서버 등록을 지원하고, Claude는 Remote MCP custom connector를, ChatGPT는 MCP 기반 custom app 연결을 제공하지만 실제 사용 가능 범위는 계정·워크스페이스 정책에 따라 달라질 수 있다. 따라서 니쥬는 공통분모인 Tool, OAuth, structuredContent와 텍스트 폴백만 필수 계약으로 삼고 Host별 연결 시험을 통과한 경우에만 지원 대상으로 표시한다. 카카오 선물하기 도구의 상품 검색·구매 이동 범위 역시 tools/list와 실제 호출로 확인하기 전에는 가정하지 않는다.

flowchart LR
    U["사용자"] --> H["MCP Host<br/>PlayMCP · Claude · ChatGPT · 기타"]
    H -->|"① 취향 기반 추천 요청"| N["니쥬 Remote MCP"]
    N -->|"② 취향 요약 + 추천 의도<br/>+ 실제 상품 + 다음 행동"| H
    H -->|"③ Host 방식으로 설명·카드·링크 표시"| U

    subgraph OPTIONAL["Host가 선택적으로 조합"]
        K["커머스 MCP<br/>카카오 선물하기 등"]
        C["캘린더 · 지도 MCP"]
    end

    H -."검색·구매 이동".-> K
    H -."기념일·지역의 최소값".-> C

    subgraph NIJU["니쥬 서비스"]
        MG["mcp-gateway<br/>Streamable HTTP"]
        BE["Spring Backend<br/>프로필 · 추천 · 권한 소유"]
        AI["AI Server<br/>추천 생성"]
    end

    N --- MG
    MG -->|"내부 REST"| BE
    BE -->|"기존 계약"| AI

    W["기상청 API"] -."비동기 갱신".-> WC[("컨텍스트 캐시")]
    WC -."선택적 snapshot".-> BE

MCP를 도입하는 이유는 REST 호출을 한 번 더 감싸기 위해서가 아니다. tools/list로 기능을 발견하고, JSON Schema로 입력을 제한하며, PlayMCP·ChatGPT·Claude 같은 호스트에서 같은 추천 기능을 호출할 수 있게 만드는 것이 목적이다.

MCP가 없으면 니쥬의 취향 분석과 추천은 니쥬 앱 화면에서만 소비된다. MCP로 제공하면 사용자는 다른 AI 서비스에서 자연어로 니쥬의 추천 기능을 호출할 수 있다.

앱 전용 구조
사용자 → 니쥬 앱 진입 → 친구 선택 → 추천 목록 확인 → 선물하기 이동

범용 MCP 구조
사용자 → 사용 중인 AI에게 선물 요청
       → 니쥬가 취향 요약 + 추천 물건 유형 + 실제 상품 제공
       → Host가 설명·상품 카드·링크를 표시
       → 필요하면 Host가 연결된 커머스 도구로 추가 탐색

새로운 추천 알고리즘을 만드는 것이 아니라, 이미 검증한 추천 기능을 사용자가 있는 채널로 확장하는 것이다. 모바일 화면, PlayMCP 대화, 다른 MCP Host가 같은 활성 추천 버전을 읽으므로 채널마다 추천 로직이 갈라지지 않는다.

니쥬의 핵심 산출물은 상품명 목록만도, 해석되지 않은 프로필만도 아니다. profileContext는 왜 이 추천이 맞는지, recommendationIntents는 어떤 물건을 찾으면 되는지, items는 지금 선택할 수 있는 실제 후보가 무엇인지를 담당한다. 세 정보를 함께 반환해야 외부 AI가 니쥬의 취향을 다시 추측하지 않고도 추천을 설명하거나 다른 커머스 도구로 탐색을 이어갈 수 있다.

공개용 취향 요약
→ 추천 물건 유형과 필수 조건
→ 니쥬 실제 상품 후보
→ 필요한 경우 외부 커머스 재탐색
→ 사용자 확인
→ 공식 구매 화면

니쥬는 취향 해석과 추천 근거를 담당하고, 각 커머스 서비스는 최신 판매·재고·구매 경험을 담당한다. PlayMCP에서는 카카오 선물하기와 이어질 수 있고, Claude·ChatGPT 등에서는 니쥬 상품 링크를 보여주거나 해당 Host에 연결된 다른 커머스 도구와 이어질 수 있다. 특정 사업자에 종속되지 않으면서 하나의 사용자 요청으로 연결되는 것이 MCP를 적용하는 가장 직접적인 이유다.

외부 AI가 추천을 이용한다고 해서 TasteProfile 전체를 읽을 필요는 없다. MCP Tool은 다음과 같이 공개 범위를 기능 단위로 좁힌다.

REST API를 그대로 외부에 공개하면 에이전트가 내부 DTO와 사용자 식별자를 알아야 한다. MCP Tool은 모델이 사용할 수 있는 이름·설명·입력 스키마를 제공하면서, 실제 사용자 식별과 권한 검사는 서버 안에 감춘다.

니쥬가 카카오의 캘린더, 지도, 선물하기 API를 모두 직접 연동하면 공급자별 토큰과 장애가 니쥬 서버에 집중된다. MCP에서는 사용자가 허용한 도구를 Host가 각각 호출한다.

MCP Host
├─ 니쥬: 취향 요약 + 추천 의도 + 실제 후보
├─ 캘린더·지도: 기념일과 지역 맥락(선택)
└─ 커머스: 실제 판매 상품 탐색과 공식 화면 이동(선택)

PlayMCP 조합 예시
└─ 니쥬 + 톡캘린더 + 카카오맵 + 카카오 선물하기

니쥬는 다른 MCP 서버의 계정 토큰을 보관하지 않고, 외부 서비스 하나의 장애가 니쥬 추천 조회를 실패시키지 않는다. 새로운 도구를 붙일 때도 니쥬 추천 파이프라인을 수정하기보다 Host의 조합 순서를 확장할 수 있다.

MCP가 REST보다 항상 우수해서 선택하는 것은 아니다. 호출자가 고정된 내부 통신은 REST가 단순하고, 호출 모델과 Host가 달라지는 외부 경계는 MCP의 발견·스키마·조합 기능이 유효하다.

외부 맥락은 추천의 보조 신호다. 사용자의 장기 취향과 섞지 않는다. 예를 들어 오늘 비가 온다는 사실은 TasteProfile에 저장하지 않고 만료 시간이 있는 ContextSnapshot으로만 사용한다.

sequenceDiagram
    actor U as 사용자
    participant H as MCP Host
    participant N as 니쥬 MCP
    participant B as 니쥬 Backend
    participant G as 선택적 커머스 MCP

    U->>H: 민수에게 5만원 이하 선물 추천해줘
    H->>N: get_friend_gift_recommendations(recipientKey, budget)
    N->>B: 인증 주체와 친구 접근권한으로 최신 gift 조회
    B-->>N: 공개용 취향 요약 + 추천 의도 + 상품
    N-->>H: structuredContent + text fallback

    alt Host에 커머스 검색 도구가 연결됨
        H->>G: 확인된 도구 스키마로 상품 검색
        G-->>H: 판매 중인 상품 후보 또는 공식 이동 정보
    else 상품 검색 도구가 없음
        H->>H: 니쥬 결과와 허용된 구매 링크 표시
    end

    H-->>U: 후보 비교와 이동 전 확인
    U->>H: 이 상품 구매 페이지 열어줘
    H->>G: 공식 화면 이동 요청
    G-->>U: 공식 커머스 화면

MCP 서버끼리 서로의 토큰을 넘겨 호출하지 않는다. 여러 도구를 가진 Host가 순서를 정하고 각각의 권한으로 호출한다. 이 구조는 니쥬가 카카오 계정 토큰이나 다른 커머스 권한을 보관하지 않게 한다.

첨부 화면과 같은 경험은 프로토콜과 UI를 구분해서 설계한다.

MCP만으로 모든 Host에서 동일한 카드 모양을 강제할 수는 없다. 이미지 자체를 매번 바이너리로 실어 보내면 지연과 응답 크기가 커지므로 초기 버전은 허용 도메인의 HTTPS imageUrl을 반환한다. 카드를 지원하지 않는 Host에서도 내용을 잃지 않도록 상품명·가격·이유를 content 텍스트로 함께 반환한다.

공식 도구가 제공하는 입력 스키마에 니쥬를 맞춘다. 도구 이름이나 파라미터를 추측해서 코드에 먼저 고정하지 않는다.

mcp-gateway는 외부 인바운드를 받는 무상태 서비스다. 사용자 데이터와 추천 로직을 갖지 않고, 인증된 도구 호출을 내부 REST 요청으로 변환한다.

flowchart LR
    P["PlayMCP · Claude · ChatGPT<br/>기타 MCP Host"] -->|"HTTPS · Streamable HTTP"| M["mcp-gateway"]
    M --> A["OAuth 토큰 검증<br/>scope · audience"]
    A --> Z["입력 스키마 검증<br/>크기 · enum · limit"]
    Z --> B["Backend Client Port"]
    B -->|"mTLS 또는 서비스 토큰"| S["Spring Backend"]
    S --> ACL["사용자 · 친구 ACL"]
    S --> R["활성 추천 리스트"]

    M --> O["도구 호출 감사 로그<br/>원문·프로필 제외"]

이 분리는 기존 3단계의 소유권 결정을 유지한다.

• Spring Backend와 AI Server의 계약은 서비스 전용이고 이미 버전이 관리된다.
• MCP는 모델이 발견하고 호출하는 공개 도구 표면이다. 내부 서비스 간 호출은 호출자가 고정되어 있어 발견 기능이 필요 없다.
• 내부까지 MCP로 바꾸면 장애 지점, 프로토콜 버전, 인증 경로만 늘어난다.
• MCP가 바뀌어도 추천 생성 파이프라인과 모바일 앱이 영향을 받지 않아야 한다.

초기 버전은 Tool만 제공한다. TasteProfile을 Resource로 노출하면 Host가 필요 이상으로 전체 취향을 반복 조회할 수 있고, Prompt는 니쥬 도구 없이도 Host가 작성할 수 있어 추가하지 않는다. 추천 Tool은 취향·추천 유형·상품을 하나의 원자적 응답으로 묶어 서로 다른 프로필 버전이 섞이는 문제와 추가 왕복 호출을 피한다.

결제, 선물 발송, 프로필 원문 조회, 대화 원문 조회 도구는 만들지 않는다.

추천 요청에서는 profileContext, recommendationIntents, items를 항상 함께 반환한다. get_my_preference_context는 상품 추천이 아닌 일반 대화 개인화가 필요할 때만 쓰며, 친구 프로필만 단독 조회하는 Tool은 만들지 않는다.

{
  "name": "get_friend_gift_recommendations",
  "description": "니쥬에서 접근 권한이 있는 친구의 공개용 선물 추천을 조회한다. 상품을 구매하거나 발송하지 않는다.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "recipientKey": { "type": "string", "maxLength": 64 },
      "budgetMax": { "type": "integer", "minimum": 1000 },
      "occasion": {
        "type": "string",
        "enum": ["birthday", "anniversary", "thanks", "casual", "other"]
      },
      "usageContext": { "type": "string", "maxLength": 200 },
      "limit": { "type": "integer", "minimum": 1, "maximum": 10, "default": 3 },
      "cursor": { "type": "string", "maxLength": 256 }
    },
    "required": ["recipientKey"],
    "additionalProperties": false
  }
}

get_my_recommendations는 recipientKey 없이 mode(self 또는 gift), budgetMax, occasion, usageContext, limit, cursor를 받는다. userId는 어떤 Tool에서도 입력으로 받지 않는다. 호출자는 액세스 토큰의 sub에서 구하고, 친구 관계와 공개 범위를 Backend가 확인한다. 모델이 다른 사용자 ID를 만들어 넣어 권한을 우회할 수 없어야 한다.

DB에는 self와 gift 활성 목록을 각각 최대 20개 보관하되, 대화 응답은 기본 3개·최대 10개만 반환한다. 더 필요한 Host는 불투명한 nextCursor로 다음 페이지를 요청한다. 이는 화면과 토큰 크기를 제한할 뿐 기존 추천 저장 구조를 바꾸지 않는다.

Tool 정의에는 아래 구조와 동일한 outputSchema를 선언하고 서버와 Host가 검증한다. 아래 예시는 structuredContent의 값이다. 실제 MCP 결과는 이 객체를 structuredContent에 넣고, 하위 호환성을 위해 같은 객체를 compact JSON으로 직렬화한 TextContent도 content에 함께 넣는다.

{
    "schemaVersion": "niju.recommendation.v1",
    "subject": {
      "type": "friend",
      "displayName": "민수"
    },
    "profileContext": {
      "summary": "야외 활동을 즐기고, 실용적이며 휴대하기 쉬운 물건을 선호합니다.",
      "tasteKeywords": ["실용적", "휴대성", "미니멀"],
      "interests": ["캠핑", "커피"],
      "visibility": "external_gift_summary",
      "profileVersion": "profile-v12",
      "generatedAt": "2026-09-14T08:30:00Z"
    },
    "requestContext": {
      "mode": "gift",
      "occasion": "birthday",
      "budget": { "maxAmount": 50000, "currency": "KRW" },
      "usageContext": "가벼운 야외 활동"
    },
    "recommendationIntents": [
      {
        "intentId": "intent_1",
        "label": "휴대용 커피 도구",
        "description": "야외에서도 번거롭지 않게 커피를 즐길 수 있는 물건",
        "priority": 1,
        "requiredTraits": ["휴대성", "세척 용이", "5만원 이하"],
        "categoryHints": ["커피용품", "캠핑용품"],
        "searchQuery": "휴대용 커피 드리퍼 캠핑 5만원 이하"
      }
    ],
    "items": [
      {
        "recommendationId": "r_51",
        "productId": "p_102",
        "intentId": "intent_1",
        "rank": 1,
        "name": "휴대용 커피 드리퍼",
        "category": "커피용품",
        "price": { "amount": 32000, "currency": "KRW" },
        "imageUrl": "https://cdn.needu.example/p_102.jpg",
        "sellerName": "판매자명",
        "purchaseUrl": "https://shop.example/products/p_102",
        "shortDescription": "접어서 휴대할 수 있는 야외용 드리퍼",
        "reason": "캠핑 관심사와 휴대성을 중시하는 취향에 맞습니다.",
        "matchedSignals": ["캠핑", "휴대성"]
      }
    ],
    "nextActions": [
      {
        "type": "commerce_search",
        "label": "다른 판매 상품도 찾아보기",
        "searchQuery": "휴대용 커피 드리퍼 캠핑 5만원 이하",
        "categoryHints": ["커피용품", "캠핑용품"]
      },
      {
        "type": "open_url",
        "label": "1순위 상품 보기",
        "url": "https://shop.example/products/p_102"
      }
    ],
    "metadata": {
      "recommendationVersion": "gift-v7",
      "rankerVersion": "rar-v1",
      "generatedAt": "2026-09-14T09:00:00Z",
      "expiresAt": "2026-09-15T09:00:00Z",
      "resultCount": 3,
      "nextCursor": null
    }
}

profileContext는 외부 AI가 추천 이유를 설명할 만큼만 제공하고 내부 TasteProfile을 복제하지 않는다. 정확한 confidence, 대화 원문, 추출 중간값, 알레르기, 비공개 기피 조건은 넣지 않는다. 알레르기와 기피 조건은 니쥬 내부에서 후보를 제외하는 데만 사용한다. recommendationIntents는 특정 판매처 ID가 아닌 물건의 종류와 조건을 표현하므로 어느 Host든 추가 검색에 사용할 수 있다. items는 니쥬가 이미 확보한 상품 후보이며 URL과 이미지 도메인은 allowlist로 검증한다.

nextActions는 실행 명령이 아니라 Host가 선택할 수 있는 다음 행동의 데이터다. commerce_search를 카카오 선물하기나 다른 커머스 Tool로 변환할지는 Host의 연결 도구와 사용자 요청에 달려 있다. 결제·발송 파라미터는 포함하지 않는다.

대표 오류 코드는 NOT_AUTHENTICATED, NOT_AUTHORIZED, NOT_ACCESSIBLE, NO_ACTIVE_RECOMMENDATION, INVALID_ARGUMENT, UPSTREAM_TIMEOUT으로 제한한다. 친구가 존재하지 않는 경우와 권한이 없는 경우는 모두 NOT_ACCESSIBLE로 반환해 사용자 열거를 막는다. outputSchema가 있는 Tool의 structuredContent는 반드시 그 스키마를 만족한다. JSON 중복 비용은 존재하지만 기본 결과를 3개로 제한하고 이미지 바이너리를 보내지 않아 호환성을 우선한다.

사용자별 비공개 추천을 제공하는 니쥬는 공용 API Key가 아니라 MCP 원격 인증 규격에 맞춘 OAuth 2.1 Authorization Code + PKCE 기반 연결을 사용한다. Host마다 화면과 등록 절차가 달라도 토큰 대상은 니쥬 MCP이며 권한 검증 규칙은 같다.

sequenceDiagram
    actor U as 사용자
    participant P as MCP Host
    participant A as 니쥬 Authorization Server
    participant M as 니쥬 MCP

    U->>P: 니쥬 도구 연결
    P->>A: Authorization Code + PKCE
    A->>U: 니쥬 로그인과 scope 동의
    U-->>A: 승인
    A-->>P: authorization code
    P->>A: code + verifier 교환
    A-->>P: audience가 니쥬 MCP인 access token
    P->>M: tools/call + access token
    M->>M: 서명 · 만료 · audience · scope 검증

profile:read:raw, chat:read, purchase:write 같은 scope는 만들지 않는다. 도구가 존재하지 않으면 해당 권한도 요청할 이유가 없다.

• 액세스 토큰의 서명, 만료, 발급자, audience, scope를 매 호출 검증한다.
• 어느 Host에서 받은 토큰도 카카오 선물하기나 다른 외부 API로 전달하지 않는다.
• 친구 접근권한은 토큰 scope만으로 결정하지 않고 Backend의 현재 친구 관계와 친구 소유자의 externalGiftSummaryEnabled 설정을 매번 확인한다.
• 도구 결과에는 대화 원문과 전체 프로필을 넣지 않는다.
• 호출 로그에는 toolName, 익명화된 주체, 결과 개수, 지연, 오류 코드만 남긴다.
• 쓰기 도구는 멱등 키를 받고, 호스트에서 사용자 확인 후 호출하도록 명시한다.
• 외부 URL은 허용된 상품·이미지 도메인만 반환해 임의 URL 실행과 SSRF 경로를 막는다.
• 외부 도구 결과의 자연어는 명령으로 신뢰하지 않고 데이터로 취급한다.

MCP 표준은 원격 HTTP 인증에서 OAuth 2.1 계열의 보호 리소스 메타데이터와 토큰 대상 검증을 요구한다. Host가 지원하는 프로토콜 버전과 메타데이터 형식은 연결 테스트에서 확정하고 호환성 매트릭스로 관리한다. 동의 철회 또는 친구 공개 설정 변경은 다음 호출부터 즉시 반영하고, 이미 외부 Host로 전달된 데이터의 보존 정책은 연결 동의 화면에 명시한다.

날씨가 추천에 의미가 있는 경우는 제한적이다.

날씨로 사용자의 취향을 추론하지 않는다. 날씨는 관련 상품에 작은 컨텍스트 가중치를 주는 용도이며 기본 취향 유사도를 뒤집지 않는다. 정확한 가중치는 골드셋으로 검증하기 전에는 확정하지 않는다.

{
  "type": "weather",
  "regionKey": "11B10101",
  "observedAt": "2026-09-14T09:00:00+09:00",
  "validUntil": "2026-09-14T10:00:00+09:00",
  "signals": {
    "temperatureC": 24,
    "precipitationType": "rain",
    "severeAlert": false
  }
}

ContextSnapshot은 TTL이 지나면 사용하지 않으며 TasteProfile이나 장기 피드백에 병합하지 않는다.

기상청 API허브는 초단기·단기예보의 기온, 강수형태, 강수량, 습도와 특보를 제공한다. 일반회원 기준 안내 호출량은 일 20,000건이고 무료지만 인증키 발급과 이용조건 확인이 필요하다.

sequenceDiagram
    participant B as Backend
    participant C as Context Cache
    participant W as Weather API
    participant A as AI API

    B->>C: 지역·시간 snapshot 조회
    alt fresh cache hit
        C-->>B: ContextSnapshot
        B->>A: 대화 요청 + snapshot
    else stale hit
        C-->>B: stale snapshot
        B->>A: 대화 요청 + stale 표시
        B-->>W: 비동기 갱신
    else cache miss
        C-->>B: 없음
        B->>A: 대화 요청, 날씨 생략
        B-->>W: 비동기 갱신
    end

모델이 응답을 생성하다가 날씨 Tool을 호출하게 하지 않는다. Backend가 구조화된 snapshot을 준비한 경우에만 프롬프트의 선택 블록으로 주입한다. 따라서 외부 API 지연과 장애가 SSE TTFT에 더해지지 않는다.

[OPTIONAL_CONTEXT]
type=weather
region=서울
validUntil=2026-09-14T10:00:00+09:00
precipitation=rain
temperatureBand=mild
instruction=현재 사용 상황을 묻거나 답할 때만 참고하고 장기 취향으로 저장하지 말 것

캘린더와 지도 도구가 해당 Host에 함께 연결되어 있다면 니쥬 MCP가 그 도구를 직접 호출하지 않는다. 사용자가 기념일이나 지역 정보를 제공하도록 동의했을 때 Host가 최소값만 니쥬 도구 입력으로 넘긴다. PlayMCP에서는 톡캘린더·카카오맵이 그 예가 될 수 있다.

캘린더 원문 전체 → 니쥬 전달 금지
필요한 최소값      → occasion=birthday, daysUntil=5

정확한 현재 위치   → 니쥬 장기 저장 금지
필요한 최소값      → region=서울, contextTtl=1h

캘린더 도구가 없거나 권한이 없으면 사용자가 occasion을 직접 입력하면 된다. 외부 도구 부재 때문에 추천 기능이 막히지 않는다.

추천은 프로필 확정 시 미리 생성해 Backend에 저장한다. MCP 호출에서 LLM, 임베딩, pgvector 검색을 다시 실행하지 않는다.

MCP tools/call
→ 토큰 검증
→ 입력 검증
→ Backend의 활성 추천 조회
→ 공개 필드 투영
→ 구조화 응답

수치는 운영 보장이 아니라 7단계 부하 테스트의 초기 SLO다. PlayMCP·Claude·ChatGPT 등 Host 구간과 커머스 MCP 지연은 니쥬 MCP 지표와 분리해 측정한다. 외부 도구가 느리다고 니쥬 추천 조회의 회귀로 판정하지 않는다.

읽기 호출도 foreground에서 연쇄 재시도하지 않는다. 에이전트가 같은 도구를 자동 반복하면 지연과 비용이 증폭되므로 retryAfterMs, 안정적인 오류 코드와 사용자별 rate limit을 제공한다.

from typing import Protocol

class RecommendationPort(Protocol):
    async def get_active(self, subject: str, mode: str, limit: int): ...
    async def get_friend_gift(self, subject: str, recipient_key: str, limit: int): ...

class ContextProvider(Protocol):
    async def get_cached(self, region_key: str, at: str): ...
    async def refresh(self, region_key: str, at: str): ...

class GiftHandoffProvider(Protocol):
    async def capabilities(self): ...
    async def search(self, plan): ...
    async def open_product(self, provider_product_id: str): ...

초기 mcp-gateway는 RecommendationPort만 사용한다. ContextProvider는 Backend의 선택적 컨텍스트 모듈이 구현한다. GiftHandoffProvider는 공식 커머스 API가 별도 파트너 계약으로 제공되어 니쥬가 직접 호출할 근거가 생길 때만 추가한다. Host가 다른 MCP를 조합하는 동안에는 니쥬 서버 안에 넣지 않는다.

# MCP SDK의 구체 문법이 아니라 권한과 호출 순서를 보여주는 의사코드다.
async def get_friend_gift_recommendations(ctx, recipient_key, budget_max=None, limit=3):
    token = ctx.verified_token
    require_scope(token, "recommendations:read:friends")

    if limit < 1 or limit > 10:
        raise InvalidArgument("limit")

    result = await backend.get_friend_gift(
        subject=token.subject,              # 입력 userId를 신뢰하지 않는다
        recipient_key=recipient_key,
        budget_max=budget_max,
        limit=limit,
        timeout_ms=500,
    )

    public_result = project_public_gift_fields(result)  # 원문·민감 취향 제거
    return build_mcp_result(
        text=summarize_for_text_fallback(public_result),
        structured_content=build_recommendation_contract(public_result),
        schema_version="niju.recommendation.v1",
    )

외부 공급자별 타임아웃, 재시도, rate limit, 회로 차단기는 각 Adapter에 둔다. 도메인 추천 로직은 공급자 SDK와 HTTP 오류 코드를 import하지 않는다.

비용이 미공개인 항목을 임의 숫자로 계산하지 않는다. 구현 스파이크에서 실제 쿼터와 호출 조건을 확인한 뒤 예상 DAU, 사용자당 호출 수, 캐시 적중률로 월 비용을 산정한다.

새 외부 도구를 추가할 때 다음 순서를 지킨다.

1. 사용자가 얻는 기능과 필요한 최소 데이터를 정의한다.
2. 연결 대상 Host의 기존 도구를 조합할 수 있는지 먼저 본다.
3. 니쥬 서버가 직접 호출해야 할 근거가 있을 때만 Provider Port를 추가한다.
4. 공급자 응답을 내부 표준 DTO로 변환하고 원문을 도메인에 넘기지 않는다.
5. timeout, rate limit, cache, fallback, 개인정보 보존 기간을 Adapter 계약에 포함한다.
6. 외부 호출이 없어도 니쥬의 기본 추천이 동작하는지 장애 테스트한다.

새 Provider
→ capability 확인
→ Adapter
→ 내부 DTO
→ 정책 검증
→ 기존 Tool 출력

Provider가 늘어나도 MCP Tool 이름을 공급자별로 늘리지 않는다. 추천 Tool의 recommendationIntents와 nextActions는 공급자 중립적으로 유지하고, Host 또는 내부 Adapter가 확인된 공급자 스키마로 변환한다. 단, 실제 구매나 발송처럼 위험과 권한이 다른 기능은 읽기 Tool에 섞지 않고 별도 도구와 scope로 분리한다.

1. MCP Inspector에서 tools/list, tools/call, 입력·출력 스키마와 OAuth를 먼저 검증한다.
2. 동일한 원격 엔드포인트를 PlayMCP, Claude, ChatGPT 지원 계정에 각각 연결한다.
3. Host별 프로토콜 버전, 인증, structuredContent, 텍스트 폴백, URL·이미지 표시 결과를 호환성 매트릭스에 기록한다.
4. PlayMCP에서 공개된 선물하기 도구의 tools/list 결과와 실제 읽기 호출을 기록한다.
5. 상품 검색, 상품 식별자, 구매 URL, 받은 선물 조회 중 지원 범위를 구분한다.
6. 테스트 계정과 샌드박스가 없으면 쓰기·구매 호출은 수행하지 않는다.
7. 확인된 기능과 Host만 지원 대상으로 표시한다.

MCP 도입의 최종 효과는 Tool 호출 수가 많아지는 것이 아니다. 사용자의 취향 분석이 권한과 프라이버시를 유지한 채 실제 선물 탐색으로 이어지고, 그 과정에서 외부 서비스가 느리거나 실패해도 니쥬의 기본 추천이 유지되는 것이다.

report.md의 설계 과제도 다음과 같이 충족한다.

추가되는 계약은 두 가지다.

1. 지원 대상 Host가 공통으로 호출하는 공개 /mcp Streamable HTTP 엔드포인트
2. mcp-gateway가 활성 추천과 친구 ACL을 조회할 Backend 내부 API

날씨 snapshot을 대화에 넣기로 확정하면 POST /v1/chat/sessions에 선택 필드 contextSnapshot을 추가한다. 날씨를 채택하지 않으면 기존 API 계약은 바뀌지 않는다.

1. 읽기 전용 get_my_recommendations와 niju.recommendation.v1 output contract를 만든다.
2. MCP Inspector에서 Tool 발견, 구조화 결과와 텍스트 폴백을 검증한다.
3. 원격 Stateless Streamable HTTP로 배포하고 OAuth와 scope 검증을 붙인다.
4. PlayMCP 연결을 우선 검증하고 같은 엔드포인트로 Claude·ChatGPT 호환 시험을 진행한다.
5. 친구 소유자의 외부 공유 설정, 친구 ACL과 공개용 gift 응답을 붙인다.
6. 선물하기 MCP의 실제 capability를 조사한다.
7. 지원되면 공급자 중립 nextActions를 공식 Tool 입력으로 연결해 E2E 흐름을 만든다.
8. 날씨는 기본 흐름이 안정된 뒤 cache-only 실험으로 추가한다.
9. p95, 오류율, 외부 API 호출량을 측정해 7단계 모니터링 설계로 넘긴다.

MCP 서버와 선물하기 연동을 동시에 만들지 않는다. 먼저 니쥬 Tool의 권한과 출력 계약을 고정해야 외부 커머스 도구의 문제와 니쥬 문제를 분리해서 검증할 수 있다.

• PlayMCP: 제로부터 시작하는 MCP 플랫폼 개발 — 원격 Streamable HTTP, Stateless 선택, 인증과 서버 등록 구조
• 카카오 PlayMCP 베타 오픈 보도자료 — 개발자 서버 등록·대화 테스트와 선물하기 등 카카오 도구 공개
• PlayMCP 도구함 보도자료 — 카카오 계정 연결과 외부 AI 서비스에서의 도구 사용
• PlayMCP 오픈클로 연동 보도자료 — 등록 서버 규모, 연결 해제와 원타임 토큰 사례
• MCP Server concepts — Tool·Resource·Prompt의 역할과 사용자 통제
• MCP Tools specification — inputSchema, outputSchema, structuredContent, 텍스트 폴백과 Tool 보안 원칙
• MCP Authorization specification — OAuth 보호 리소스, audience와 토큰 검증 원칙
• Claude Remote MCP custom integrations — Remote MCP connector, 인증과 Tool·Resource·Prompt 지원 범위
• ChatGPT apps and connectors — MCP 기반 custom app과 워크스페이스 연결 개요
• ChatGPT developer mode and MCP — 계정·워크스페이스별 full MCP 사용 조건과 관리 제약
• 기상청 API허브 이용 안내 — 인증키, 일반회원 호출량, 비용과 운영 조건
• 기상청 예특보 API — 초단기·단기예보 변수와 발표 주기
• 카카오톡 메시지 API 안내 — 공유·메시지 기능과 권한 범위