MCP 서버 요청 로그와 도구 호출 추적법
- JSON-RPC 요청 ID는 요청과 응답을 연결하고, trace ID는 여러 시스템의 작업 흐름을 연결합니다.
- stdio 서버는 stdout을 프로토콜 통신에 사용하므로 운영 로그는 stderr 등 별도 경로로 보냅니다.
- MCP Python SDK는 메시지 스팬을 생성하지만, 내보내기 설정이 없으면 관측 도구에서 확인할 수 없습니다.
MCP 서버에서 도구 호출이 실패하거나 느려졌다면 요청을 받은 시점부터 핸들러 실행, 외부 시스템 호출, 응답까지 이어서 살펴보세요. 요청 ID, MCP 메서드, 도구 이름, 처리 시간, 결과 상태를 기록하고, 여러 서비스에 걸친 작업에는 trace ID를 연결하면 원인을 좁히기 쉽습니다. 로그에는 토큰이나 개인정보를 그대로 남기지 말고, stdio 통신과 운영 로그의 출력 경로를 분리하세요.
로그와 트레이스의 차이
로그는 사건을 기록합니다
로그는 도구 실행 중 발생한 사건과 오류를 기록합니다. 도구 이름, 처리 결과, 오류 유형처럼 조사에 필요한 필드를 구조화해 남기면 실패를 찾기 쉽습니다. 입력값 전체를 기록하면 개인정보, 내부 문서 내용, 접근 토큰이 로그 저장소에 복제될 수 있으므로 필요한 요약만 남기는 편이 안전합니다.
트레이스는 처리 경로를 연결합니다
트레이스는 하나의 작업이 클라이언트, MCP 서버, 도구 핸들러, 외부 API를 거치는 흐름을 스팬으로 표현합니다. 스팬에는 작업 이름, 시작·종료 시각, 처리 결과 같은 정보를 담을 수 있어 어느 구간에서 지연이나 오류가 생겼는지 살펴보는 데 적합합니다.
JSON-RPC 요청 ID는 프로토콜 요청과 그 응답을 연결하는 식별자입니다. trace ID는 여러 시스템의 스팬을 같은 추적 흐름으로 묶습니다. 두 값을 같은 필드로 취급하지 말고, 각각 별도로 기록하세요. trace context 전파 방식과 자동 스팬 지원 여부는 사용 중인 SDK 및 버전에 따라 확인해야 합니다.
로그 위치와 기본 기록 항목
전송 방식에 맞춰 로그를 찾습니다
stdio에서는 클라이언트와 서버가 표준 입출력으로 통신합니다. stdout은 MCP 프로토콜 메시지용으로 두고, 디버그나 운영 로그는 stderr 또는 호스트가 제공하는 별도 로그 수집 경로로 보냅니다. stdout에 일반 문장을 출력하면 호스트가 이를 프로토콜 메시지로 해석해 통신을 방해할 수 있습니다.
Streamable HTTP 서버는 애플리케이션 로그와 함께 웹 서버, 프록시, 인증 계층의 로그를 확인할 수 있습니다. 다만 URL 쿼리나 헤더 전체를 기록하면 자격 증명이 노출될 수 있으므로 수집 필드를 점검하세요. 로그가 실제로 저장되는 위치는 호스트와 배포 환경의 설정에 따라 달라집니다.
필요한 필드만 정합니다
- 시각과 시간대, 환경, 서버 및 배포 버전
- MCP 메서드(예: tools/call), 도구 이름, JSON-RPC 요청 ID
- trace ID 또는 상관관계 ID, 처리 시간, 성공·실패 상태
- 오류 코드와 정제한 오류 요약, 외부 시스템 호출 여부
상관관계 ID는 여러 로그를 연결하기 위해 서비스가 정하는 값입니다. JSON-RPC 요청 ID와 별도로 보관하세요. 알림 메시지는 요청 ID가 없는 경우가 있으므로 요청과 같은 형태로 기록한다고 가정하지 마세요.
도구 호출을 추적하는 순서
1단계: 식별자와 호출 경계를 확인합니다
클라이언트 요청과 서버 로그에서 JSON-RPC 요청 ID를 확인하고, 지원되는 경우 trace context가 서버까지 전달되는지 살펴봅니다. 지원되지 않는 구간은 별도의 상관관계 ID로 이어 붙일 수 있습니다. 알림 메시지는 요청과 구분해 기록합니다.
2단계: 도구 실행의 시작과 끝을 기록합니다
핸들러 진입 시 도구 이름과 시작 시각을 기록하고, 종료 시 경과 시간과 성공 여부를 남깁니다. 오류가 발생하면 예외 유형과 정제된 요약을 기록하고, 모델이 받아야 할 도구 반환값과 운영자용 로그를 구분합니다. 원문 대신 입력 길이, 항목 수, 스키마 검증 결과처럼 민감도가 낮은 요약을 활용하세요.
3단계: 외부 호출을 별도 구간으로 나눕니다
도구가 데이터베이스나 외부 API를 호출하면 해당 작업의 시작·종료와 결과를 별도 스팬이나 로그 필드로 남깁니다. 연결 대기, 응답 대기, 재시도 횟수, 타임아웃 여부를 구분하면 지연이 발생한 구간을 찾기 쉽습니다.
4단계: 성공과 실패 호출을 확인합니다
개발 환경에서 성공 호출과 실패 호출을 각각 실행하고, 요청에서 서버 응답까지 식별자와 스팬이 이어지는지 확인하세요. trace ID가 중간에 끊기면 전파 설정과 SDK 버전을 살펴봅니다. 운영에서는 필요한 보존 기간과 수집 범위를 정하고, 오류와 지연 호출을 관측할 규칙을 구성하세요.
Python SDK에서 로그와 트레이스 보기
MCP Python SDK 로깅 문서는 도구 안에서 Python 표준 로깅을 사용할 수 있으며, 운영 로그는 도구 반환값에 포함되지 않는다고 설명합니다. stdio에서는 stdout이 프로토콜 통신 경로이므로 일반 로그를 stderr로 보내도록 구성하세요. 모델이 읽어야 하는 정보는 로그가 아니라 도구 반환값으로 제공해야 합니다.
MCP Python SDK OpenTelemetry 문서에 따르면 SDK는 수신 메시지마다 스팬을 생성하며, 도구 호출 스팬에는 MCP 메서드와 도구 이름 등의 속성이 포함됩니다. 하지만 OpenTelemetry API만 있고 SDK와 내보내기(exporter)가 설정되지 않은 환경에서는 스팬이 실제 관측 화면으로 전달되지 않을 수 있습니다. 데이터를 확인하려면 사용할 백엔드에 맞춰 OpenTelemetry SDK와 내보내기를 설정하세요. 클라이언트와 서버 양쪽에서 지원되는 SDK를 사용할 때 trace context 전파 동작도 확인할 수 있습니다.
2026-07-28 MCP 사양은 프로토콜 수준 로깅 기능을 지원 중단 대상으로 지정했습니다. 공식 발표는 해당 기능이 당장 제거되는 것은 아니며 최소 12개월 동안 유지된다고 안내합니다. 새 구현은 SDK와 협상된 프로토콜 버전을 확인하고, 서버 운영 관측에는 애플리케이션 로그와 OpenTelemetry를 사용하세요.
| 상황 | 먼저 볼 위치 | 확인할 단서 |
|---|---|---|
| stdio 호출 실패 | 호스트가 수집한 stderr 로그 | 도구 진입 여부, 예외, stdout 오염 |
| HTTP 호출 실패 | 서버·프록시·인증 계층 로그 | 응답 코드, 라우팅, 인증 거부 |
| 호출 지연 | 트레이스의 하위 스팬 | 핸들러, DB, 외부 API별 처리 시간 |
보안과 운영에서 놓치기 쉬운 점
민감한 원문 대신 필요한 정보만 남깁니다
도구 인자에는 개인정보, 내부 문서 내용, API 토큰이 포함될 수 있습니다. 입력 전체를 기본으로 로깅하지 말고 민감 필드 마스킹, 접근 권한, 보존 기간을 정하세요. 오류 분석에 원문이 꼭 필요한 경우에는 접근 범위와 보관 기간을 제한하고 접근 이력을 관리합니다.
실패와 정상 응답을 같은 기준으로 비교합니다
- 정상 호출에도 기본 식별 필드가 빠짐없이 기록되는지 확인합니다.
- 재시도는 원 요청 ID와 시도 번호를 구분해 기록합니다.
- 로그 레벨을 조정한 뒤에도 오류와 지연 호출을 찾을 수 있는지 점검합니다.
- 로그 저장소의 접근 권한과 보존·삭제 설정을 검토합니다.
기억할 기준: stdio 서버의 stdout은 프로토콜 메시지용입니다. 운영 로그는 stderr 등 별도 경로로 보내고, 민감한 입력과 인증 정보를 원문으로 기록하지 마세요.
자주 묻는 질문
Q. MCP 요청 로그는 도구 응답에 포함되나요?
일반적으로 서버 운영 로그와 도구 반환 결과는 별개입니다. 모델이 사용해야 하는 정보는 도구가 반환하도록 설계하고, 운영자 분석용 기록은 로그나 트레이스에 남기세요.
Q. stdio 서버에서 print()를 사용해도 되나요?
stdout이 MCP 메시지 채널이면 임의 출력을 피하고 로깅 라이브러리로 stderr나 별도 수집 경로에 기록하세요. 사용하는 SDK가 출력 스트림을 처리하는 방식도 해당 버전 문서에서 확인하세요.
Q. JSON-RPC 요청 ID만 있으면 전체 호출 추적이 충분한가요?
요청 ID는 프로토콜 메시지를 응답과 연결하는 데 유용하지만, 외부 API 호출과 재시도까지 이어지는 흐름을 표현하지는 않습니다. 지원되는 경우 trace ID를 함께 전달하고 하위 작업을 별도 스팬으로 기록하세요.
Q. 도구 입력값 전체를 로그에 저장해야 하나요?
대부분의 운영 분석에는 전체 원문이 필요하지 않습니다. 도구 이름, 처리 시간, 입력 검증 결과, 오류 종류처럼 목적에 필요한 요약을 기록하고 개인정보와 인증 정보는 마스킹하거나 제외하세요.
