스탠포트 강의 2주차 노트

README.md

CS146S: The Modern Software Developer 2주차 정리

https://kr.themodernsoftware.dev/#syllabus

느낀점 (과정 전체에 관해서)

====================================================================================

실습

그냥 Cursor 써서 프로그램 만드는 거였는데, Claude Code로 Opus 4.6 써서 하니까 모델 성능이 좋아선지 별로 노력 안하고 성공함.

뭐 매일 하는게 AI 써서 코딩하는거니까 굳이 더 안파고 대충 넘김

====================================================================================

발표 자료

Opus 4.6 사용해서 요약 & 이해 안가는거 추가 메모

코드랑 발표 자료는 링크타고 가서 보기

Building a Coding Agent From Scratch

1. 코딩 에이전트 구조 - 사용자가 코딩 에이전트 클라이언트(Windsurf, Cursor, Claude Code)와 상호작용하면, 내부적으로 LLM과 루프를 돌며 필요 시 tool call을 발행하고 클라이언트가 이를 실행함.
2. 용어 정의 - System prompt(LLM 행동 지시), User prompt(사용자 요청), Assistant prompt(LLM 응답).
3. 구축 단계:
   • 터미널 입력을 읽어 대화에 계속 추가
   • LLM에 사용 가능한 도구 목록 전달 (Read_file, List_dir, Edit_file 등)
   • LLM이 적절한 시점에 tool use를 요청
   • 도구를 오프라인 실행 후 결과 반환
4. 라이브 코딩 - 코딩 에이전트를 처음부터 직접 구축하는 데모.
5. Claude의 "비밀 소스":
   • 작은 타겟 프롬프트로 컨텍스트 선제 주입 - 목적별로 짧고 구체적인 프롬프트 조각들을 미리 컨텍스트로 제공 (예: 파일 수정/추가 시 ~해라)
   • System/User prompt, tool call, tool result 곳곳에 <system-reminder> 태그를 삽입하여 drift(초기 지시를 잊는 현상) 방지
   • Command prefix 추출 - 슬래시 명령어 처리
   • Sub-agent 스폰(Spawn, 배정하다) 특정 작업을 별도 에이전트에게 위임, 컨텍스트 과부하 방지 목적

실습 자료 설명

1. get_full_system_prompt()가 보유한 도구 정보 목록과 적절할 때 사용하라는 지시가 포함된 시스템 프롬프트 텍스트를 생성한다.
2. 해당 텍스트가 LLM 호출 시 시스템 프롬프트로 들어간다.
3. LLM이 도구 사용이 필요하다면 tool: 함수({인자}) 형태로 응답한다. 아니라면 자연어 텍스트로 답변한다.
4. 코드는 이 응답을 받고 분기 처리한다.
   • 도구가 아닌 경우: 텍스트 답변이므로 출력하고 대화에 추가
   • 도구 사용인 경우:
     • extract_tool_invocations()로 응답 텍스트에서 도구 이름과 인자를 파싱
     • 파싱 결과를 기반으로 해당 도구 함수를 실행하고 결과를 대화 내역에 삽입 (그대로 넣는건 아니고 tool 결과임을 인식 가능하게 포맷)
     • LLM을 다시 호출하여 도구 결과를 바탕으로 자연어 답변을 생성
5. 다음 사용자 입력을 기다린다.

To MCP and Beyond

1. Why (동기) - LLM은 방대하지만 정적인 지식을 보유. 자율 시스템 구축에는 동적 데이터 주입이 필수. 현재 최선의 방법은 RAG와 tool-calling.
2. MCP 기본 개념:
   • Model Context Protocol - LLM에 도구를 노출하는 표준 포맷 (2024년 11월 도입).
   • 3rd party API 통합 시 문서 부실, 인증, 에러 처리 등의 문제를 해결.
   • M×N 커넥터 문제를 M+N으로 축소.
   • JSON-RPC 기반 일관된 출력 포맷, Language Server Protocol에서 확장.
3. MCP 아키텍처 용어:
   • Host: Cursor, Claude Desktop 등
   • MCP Client: Host에 내장된 라이브러리 (서버당 stateful 세션)
   • MCP Server: 도구 앞단의 경량 래퍼
   • Tool: 호출 가능한 함수 (데이터 소스, API)
4. MCP 흐름:
   • Client → tools/list 호출 → Server가 JSON 스키마 반환 → Host가 모델 컨텍스트에 주입 → 사용자 프롬프트 → 모델이 tool call 발행 → MCP Server 실행 → 대화 재개
   • 전송 계층: stdio, Streamable HTTP(SSE, 강의에선 SSE라 하는데 바뀜, 최근 공식 스팩에선 Streamable HTTP를 권장함. 일반적인 HTTP로 쓰거나, 필요하면 SSE로 업그레이드가 가능한 방식임. 관련 글)
5. 라이브 코딩 - 커스텀 MCP 서버를 처음부터 구축하는 데모 (list_files, edit_file 테스트).
6. 한계:
   • 에이전트가 많은 도구를 잘 처리하지 못함 (Cursor 도구 수 하드 리밋 존재)
   • API가 컨텍스트 윈도우를 빠르게 소모
   • API를 rigid(경직된)하게 아닌 AI-native하게 설계해야 함
     • 잘 이해 안되서 찾아보니까, LLM이 쉽게 이해하고 사용할 수 있도록 설계하라는 의미
     • 예:
       • 파라미터/API 이름을 자연어에 가깝게 (축약어는 LLM이 매핑하기 어려움)
       • 필수 필드를 최소화하고 나머지는 합리적인 기본값 제공 (필수 필드가 많을수록 LLM이 누락하거나 잘못 채울 확률 증가)
       • 입력 형식을 유연하게 (복잡한 형식 규칙은 LLM이 이해하기 어려움)

실습 자료 설명

그냥 FastMCP 사용한 간단한 예시. 이미 통신규칙 구현된 라이브러리를 가져다 씀. 실무든 뭐가 되었든 MCP 내부 통신을 만드는 일은 드물거라 그런 듯.

====================================================================================

학습 자료

문서

• Model Context Protocol (MCP): A comprehensive introduction for developers
  • AI 모델과 외부 데이터·서비스를 연결하는 개방형 표준 (JSON-RPC 2.0 기반의 RPC 프로토콜)
  • Plug & Play 방식으로 AI에 도구 사용 능력을 부여. 제공자와 사용자 모두 커스텀 연동 없이 표준 인터페이스로 빠르게 기능을 연결할 수 있음
  • 사실상 표준 위치
  • 구조: 클라이언트(AI 애플리케이션) ↔ 서버(MCP 서버, Tools 제공)
  • 아직 초기 단계라 한계 있음. OAuth 2.1 인증 추가 등 스펙이 빠르게 변화 중 (메모: 이와 관련한 불만은 따로 적을 듯)
• Build a Remote MCP Server
  • Cloudflare에 자체 원격 MCP 서버를 배포하는 가이드
  • OAuth2를 사용한 인증 기능도 다룸. 여기선 Github OAuth Provider를 사용한다. (Github은 리다이렉트 경로가 하나만 가능해서 환경별로 생성했지만, 여러개를 지원하면 하나로도 가능해보인다.)
• APIs don't make good MCP tools
  • 에이전트는 기존 API의 전형적 소비자와 근본적으로 다르다. 기존 API를 MCP 도구로 자동 변환할 수는 있지만 잘 동작하지 않는다.
    1. JSON 응답의 토큰 비효율: JSON은 토큰 소비가 크다. CSV/TSV 등으로 변환하면 절반 수준으로 줄일 수 있다.
    2. 도구 수 폭발: API 엔드포인트를 그대로 매핑하면 도구가 수십~수백 개가 되고, 매번 컨텍스트에 올라가므로 모델의 도구 선택 정확도가 떨어진다.
    3. 에이전트 고유 능력 미활용: 에이전트는 자연어 힌트("다음엔 get_city_details를 호출하세요")도 이해할 수 있는데, API 자동 변환은 고정된 구조화 데이터만 반환한다.
    4. 직접 API 호출이 나을 수 있음: 에이전트가 직접 코드를 작성해 API를 호출할 수 있으므로, 샌드박싱이 안전하다면 MCP를 거칠 필요가 없다. (메모: Skill.md를 사용하게 하면 더 안전하게 쓸 수 있을 듯?)

공식 사이트 및 GitHub

MCP는 Anthropic에서 만들었지만, Linux Foundation에 기부되어 별도 조직으로 관리되고 있다. (관련 글)

다양한 회사의 지원을 통해 여러 레지스트리(규칙을 지키는 서브 레지스트리가 있을 수 있다, 아직 프리뷰 단계), 언어의 SDK, 명세, 도구(MCP Inspector 등)를 관리하고 있다.

• 문서 및 명세
  • modelcontextprotocol.io - MCP 공식 문서. 프로토콜 스펙, 가이드, 튜토리얼 포함
  • Anthropic - MCP 기부 및 Agentic AI Foundation 설립 발표 - MCP를 Linux Foundation에 기부한 공식 발표
• 레지스트리
  • MCP Registry 프리뷰 발표 - 공개 MCP 서버의 중앙 메타데이터 카탈로그. 서버 등록·검색 표준화. 2025년 9월 프리뷰 출시, GA 미정 (2026/02/11 기준 아직임)
  • registry.modelcontextprotocol.io - 레지스트리 UI. 등록된 MCP 서버 검색 가능
• 서버 및 SDK
  • modelcontextprotocol/servers - 공식 MCP 서버 목록
  • modelcontextprotocol/typescript-sdk - TypeScript SDK
• 개발 도구
  • MCP Inspector 문서 - MCP 서버 테스트·디버깅용 웹 UI 도구. 도구 호출, 리소스 탐색, JSON-RPC 로그 확인 가능
  • modelcontextprotocol/inspector - MCP Inspector GitHub 저장소.

MCP의 문제와 불만

개인적으로 이전에 MCP 서버 잠깐 시도했다가 겪은 불만들이 좀 있다.

동작하는 서버를 만드는 건 쉬운데, 인증을 추가하려고하면 직접 OAuth Provider 구현해야 한다... 뭐 그러고 복잡한데다 자료도 없어서 시간에 쫒기다가 결국 인증 없이 IP 화이트리스트 기반으로 처리했었다.

이런 불만이 나만 겪은건 아닌지, 해커뉴스에 많은 투표를 받은 글의 코멘트에서도 비슷한 의견이 종종 보였다.

아래는 비슷한 의견이 담긴 해커뉴스(링크가 있는 Geeknews) 링크다. 글 자체에선 인증을 메인으로 다루는건 아니고, 그 글의 의견중에 비슷한게 있다.

• A critical look at MCP(MCP를 비판적으로 살펴보기)
• Everything Wrong with MCP(MCP에서 발생할 수 있는 모든 문제들)

이번에 MCP 공부하다가 궁금해져서 찾아본 내용이나 이런 불편했던 부분의 해결책을 정리해보았다.

MCP 인증 방식과 사용 가능한 도구

MCP(OAuth 2.1) 인증에는 세 가지 역할이 있다:

1. MCP 서버 (Resource Server) — 도구를 제공하고, 토큰을 검증
2. Authorization Server (AS) — 토큰을 발급. MCP는 임의의 클라이언트가 접속하는 구조이므로 Dynamic Client Registration(RFC 7591) 지원이 권고됨
   • DCR을 지원하면 클라이언트가 /register에 요청을 보내 client_id/client_secret을 런타임에 자동 발급받을 수 있다.
3. Identity Provider (IdP) — 사용자가 누구인지 확인 (로그인 화면 제공). GitHub, Google 등

GitHub/Google은 3번(IdP)만 할 수 있고, 2번(AS) 역할은 할 수 없다. DCR을 지원하지 않고, 임의의 audience에 대한 토큰 발급도 안 되기 때문이다.

단, 현재 MCP 스펙에서 DCR은 MAY(선택)이고(MCP Authorization Spec), 실제 MCP 클라이언트(Claude Desktop, Cursor 등) 대부분은 DCR을 자동 수행하지 않는다. 토큰이나 API 키를 직접 입력하거나, client_id를 사전 설정하는 방식이다.

스펙을 완전히 준수하려면(DCR, RFC 9728 등) Auth0 같은 SaaS나 Keycloak 셀프호스트로 별도 AS를 운영해야 하지만, 소규모/개인 용도에서는 AS 래퍼를 통해 외부 IdP에 인증을 위임하는 것으로 충분하다.

• Cloudflare OAuthProvider - Cloudflare에서 작성한 MCP 서버 빌드 가이드 중
• mcp-auth-proxy - 여러 MCP 서버 앞에 놓는 프록시.

클라이언트별 권한 분리, 세밀한 스코프 관리, 토큰 수명 정책 등 엔터프라이즈 요구사항이 필요하다면 agentgateway 같은 게이트웨이를 사용할 수 있다.

MCP의 Tools가 많아질 떄의 대처법

배경: 컨텍스트가 많아지면 성능이 낮아진다는 건 이해하는데, 도구가 많아지는 건 어쩔 수 없는 것 아닌가? Skill을 재귀 형태로 관리하는 것처럼 이것도 여러 해결책이 있을 것 같아서 찾아보았다.

1. 목적별 MCP 서버 분리: 하나의 거대한 서버 대신 워크플로우 단위로 작은 서버를 나눈다. 가장 단순하고 널리 쓰이는 방법. 단, 활성화/비활성화는 사용자가 수동으로 해야 한다 (에이전트가 자율적으로 서버를 켜고 끄는 표준 인터페이스는 없음).
2. Tool-RAG: 도구 설명을 벡터 인덱스에 저장하고, 쿼리와 의미적으로 유사한 도구만 검색하여 컨텍스트에 주입. 실험에서 프롬프트 토큰 50%+ 감소, 도구 선택 정확도 3배 이상 향상이 보고됨. (Gan et al., "RAG-MCP", arXiv:2505.03275, 2025)
3. 코드 실행 기반 도구 호출: 도구 정의를 컨텍스트에 직접 넣는 대신, MCP 서버를 코드 API로 노출하고 에이전트가 코드를 작성해 호출. 필요한 도구만 import하고 중간 결과를 실행 환경에서 처리하므로 컨텍스트 소비를 크게 줄인다. Anthropic 엔지니어링 블로그에서 제안. (Anthropic - Code execution with MCP)