AI 에이전트가 사용자의 MCP 서버에서 실제로 하는 일

MCP 서버는 모든 로그에서 정상적으로 보일 수 있지만, 에이전트에게는 여전히 사용하기 어려울 수 있습니다. 요청이 들어오고 응답이 나가며, 아무것도 충돌하지 않습니다. 여러분이 보지 못하는 것은 에이전트가 어떻게 그곳에 도달했는지입니다. 즉, 어떤 것을 요청했는데 여러분이 가지고 있지 않은 것인지, 올바르게 하기 전에 무엇을 잘못했는지, 그리고 어디서 막혔는지를 말합니다.

이것들은 제가 측정했을 때만 나타난 다섯 가지 사항들입니다. 스크린샷은 시뮬레이션 트래픽을 사용한 데모 항공편 예약 서버에서 가져온 것이므로 수치는 예시이며, 패턴이 에이전트가 생성하는 것입니다.

1. 에이전트는 여러분이 가지고 있지 않은 도구를 호출합니다

에이전트는 도구 이름을 추측합니다. 일부 추측은 근접 실패입니다: 도구가 search_flights일 때 searchFlights, 또는 seat_map 대신 seatMap과 같습니다. 다른 것들은 에이전트가 존재한다고 가정하는 도구, 예를 들어 get_flight_price와 같습니다.

이 목록을 단순히 오류 횟수로 세는 것보다 유용하게 만드는 세 가지 요소가 있습니다:

• 가장 가까운 기존 이름. searchFlights는 누락된 기능이 아니라, 클라이언트 중 한 곳이 선호하는 명명 규칙입니다. 이는 새로운 코드가 아닌 설명 수정 문제입니다.
• 에이전트가 다음에 한 일. get_flight_price 이후 대부분의 에이전트는 search_flights로 넘어갔으므로, 그들은 방법을 알아냈습니다. export_itinerary 이후 모든 세션은 중단되었습니다. 사용자가 무엇을 원했든 간에, 그것을 얻지 못했습니다.
• 어떤 클라이언트가 요청했는지. export_itinerary는 오직 Cursor에서만 발생했습니다. 한 클라이언트가 기대하는 도구는 모든 클라이언트가 기대하는 것과는 다른 신호입니다.

2. 잘못된 인수는 가장 흔한 실패 원인이며, 숨겨져 있습니다

에이전트가 입력 스키마와 일치하지 않는 인수를 전송할 때, MCP SDK는 핸들러가 실행되기 전에 이를 거부하고 검증 오류를 일반 결과로 모델에 다시 보냅니다. 따라서 여러분의 핸들러는 절대 실행되지 않았고, 여러분의 코드는 실패를 본 적이 없으며, 여러분의 오류율은 에이전트가 경험한 것보다 더 좋아 보입니다.

이 서버에서 book_flight의 실패는 충돌(crash)보다는 인수가 거부된 경우(refused arguments)가 대부분이었습니다. 이는 다음 요점으로 이어집니다.

3. 도구 설명(tool description)이 코드입니다

book_flight은

5. 응답 크기는 지연 시간 차트에서 보이지 않습니다

평소에 6 kB로 답변하는 도구와 가끔 650 kB로 답변하는 도구가 아무리 빨라도 모든 지연 시간(latency) 차트에서는 괜찮아 보입니다. 하지만 그 답변은 에이전트의 컨텍스트 창(context window)에 들어가 다른 모든 것을 밀어내고, 이후 매 턴마다 토큰 비용을 발생시킵니다.

여기서 중앙값(median)과 95번째 백분위수(95th percentile)는 괜찮습니다. 하지만 가장 큰 답변은 100배나 더 큽니다. 일반적인 원인은 필터가 없는 쿼리(query)를 사용하여 모든 것을 반환하는 경우입니다. 기본 제한(default limit)을 설정하거나, 더 많은 정보를 요청할 수 있는 요약본(summary)을 제공하면 이 문제가 해결됩니다.

측정 방법

이를 위해 저는 mcpspan을 만들었습니다: MCP 서버를 위한 자체 호스팅 분석 도구이며, MIT 라이선스를 따릅니다. Docker로 실행하고 서버에 한 줄만 추가하면 됩니다:

git clone https://github.com/mcpspan/mcpspan.git
cd mcpspan
docker compose up -d

import { instrument } from 'mcpspan';

instrument(server, {
...

import os

import mcpspan
...

TypeScript, Python, Go, C#, Java, Rust, Ruby, PHP용 SDK가 있으며, 각 언어마다 동일한 기능을 제공합니다. 매개변수 값은 절대 서버 프로세스를 벗어나지 않으며, 사용자가 직접 설정하지 않은 곳으로는 아무것도 전송되지 않습니다.

초기 버전이므로, 에이전트가 귀하의 서버를 어떻게 사용하는지에 대해 보고 싶은 부분이 있다면 알려주시면 좋겠습니다.