5단계로 만드는 다중 사용자용 원격 MCP 서버

책 『5단계로 만드는 다중 사용자용 원격 MCP 서버 - OAuth로 Claude와 연동하기』의 예제 코드입니다.

할 일 관리 서버 하나를 다섯 번 고쳐 갑니다. 내 PC에서만 도는 stdio 서버로 시작해서, 고객이 claude.ai에서 로그인해 쓰는 원격 MCP 서버까지 갑니다. 단계마다 서버 파일이 하나씩 들어 있습니다. 4·5단계 서버는 공통 파일 issue_token.py 를 같은 폴더에 두어야 돕니다.

• 책: 판매 링크 준비 중

• 정오표: ERRATA.md

책 본문은 여기 없습니다. 이 저장소가 담는 것은 예제 코드뿐입니다.

요구 사항

파이썬 3.10 이상이면 됩니다. 라이브러리는 FastMCP 하나이고, 점검 스크립트와 최종 장 코드가 httpx를 함께 씁니다.

Related MCP server: MCP OAuth Server

설치

python -m venv .venv
source .venv/bin/activate        # 윈도우 PowerShell 은 .\.venv\Scripts\Activate.ps1
pip install -r requirements.txt

파일

실행

아래는 파일별 실행 예입니다. 위에서 아래로 다 치는 순서가 아닙니다. 실습할 단계의 서버 하나를 골라 띄우고, 최종 장은 service_api.py 와 todo_adapter.py 를 각각 다른 터미널에서 띄웁니다.

(.venv) $ python todo_v1.py                # stdio. Claude Desktop 이 실행합니다
(.venv) $ python todo_v3.py                # http://127.0.0.1:8000/mcp
(.venv) $ python check_v3.py <토큰>        # 3단계 점검. MCP_URL 로 배포 주소를 줄 수 있습니다
(.venv) $ python issue_token.py kim        # 토큰 발급
(.venv) $ python todo_v4.py                # 0.0.0.0:8000
(.venv) $ python todo_v5.py                # OAuth
(.venv) $ python service_api.py            # 최종 장. 예제 서비스 API :8001 (먼저 띄웁니다)
(.venv) $ python todo_adapter.py           # 최종 장. 몸통 교체판 :8000

(.venv) $ 는 가상환경이 켜진 터미널이라는 표시입니다. 입력하지 않습니다.

todo_v5.py 는 띄우기 전에 BASE_URL 을 실제 접속 주소로 맞춰 주세요. 로그인 화면 주소가 이 값에서 나옵니다.

(.venv) $ BASE_URL=https://내주소 python todo_v5.py
# 윈도우 PowerShell: $env:BASE_URL="https://내주소"; python todo_v5.py

점검

(.venv) $ python test_smoke.py

다섯 단계를 순서대로 돌립니다. 5단계는 등록·인가·로그인·코드 교환·도구 호출까지 전 과정을 왕복합니다. 마지막에는 두 계정이 서로의 데이터를 못 본다는 것까지 확인합니다. 53개 항목입니다.

실습 계정 (5단계)

코드에 적혀 있는 실습용 계정입니다. 실전에서는 이 자리에 여러분의 회원 데이터베이스가 섭니다.

코드에서 눈여겨볼 세 곳

읽다 보면 군더더기처럼 보이는데, 빼면 서버가 안 도는 자리들입니다.

get_http_headers(include={"authorization"}) - 3·4단계입니다. 인자 없이 부르면 FastMCP가 authorization 헤더를 지웁니다. 토큰이 늘 빈 문자열이 되어 도구 실행이 모두 실패하는데, 증상은 "토큰이 잘못됐다"로 보입니다.

ClientRegistrationOptions(enabled=True) - 5단계입니다. 클라이언트 등록은 기본이 꺼져 있어서, 안 켜면 /register 가 404입니다. 자기 정보 문서(CIMD)가 없는 클라이언트는 등록할 길이 사라집니다. 이 서버는 두 방식을 다 받습니다.

claims={"sub": user} - 5단계입니다. 인가 코드는 subject 에, 접근 토큰은 claims 에 사용자를 싣습니다. 도구에서는 claims["sub"] 로 꺼냅니다. sub 는 JWT 표준에서 "누구"를 담는 이름을 빌려 온 것이고, 이 예제 안의 약속입니다.

데이터 파일 경로도 하나 덧붙입니다. 1~3단계는 todos.json 의 경로를 스크립트 기준(Path(__file__).parent)으로 잡았습니다. stdio 서버의 작업 폴더는 클라이언트가 정하기 때문에, 상대 경로로 쓰면 엉뚱한 곳에 파일이 생기거나 권한 오류가 납니다. 4·5단계는 DATA_DIR 환경변수로 저장 폴더를 정하고, 없으면 실행한 작업 폴더를 씁니다.

버전

requirements.txt 는 fastmcp==4.0.3 과, 그 아래에서 도는 기반 SDK mcp==2.1.1 을 함께 고정합니다. fastmcp 만 고정하면 딸려 오는 mcp 판이 설치 시점에 따라 달라지기 때문입니다. 책이 이 판을 기준으로 삼은 이유는 2026년 7월 28일 MCP 개정에 대응하는 세대이기 때문입니다. 그 이전 세대(3.4.x)에서도 이 코드는 돕니다. 다만 규격이 개정 이전이라, 책의 설명과 어긋나는 곳이 생깁니다.

파이썬은 3.10과 3.13에서 확인했고 3.10 이상이면 됩니다.

라이선스

MIT입니다. 쓰시고 고치시고 여러분 서비스에 넣으셔도 됩니다. 코드를 복사해 배포하실 때는 저작권 표시와 허가문을 함께 남겨 주세요. LICENSE 파일을 같이 두시면 됩니다.