GPT Image 2.5 is live — OpenAI's newest image model, targeted edits that leave the rest of the frame alone
모든 가이드

· reAPI Team

MCP 도구 호출: API를 전환한 뒤 실패하는 이유

MCP 도구 호출을 검색, 모델 지원, 실행, 반환 결과의 각 단계에서 추적합니다. 재시도하거나 유료 작업을 제출하기 전에 API 마이그레이션 실패를 진단하세요.

MCP 도구 호출: API를 전환한 뒤 실패하는 이유

MCP 서버에는 연결됨이라고 표시됩니다. 그런데도 어시스턴트는 일반 텍스트로 답하거나, 결과를 보여 주지 않은 채 작업을 확인했다고 말합니다. 모델 API를 바꾼 뒤 이런 문제가 시작됐다면 프롬프트를 다시 수정하기 전에 새 연결을 통해 무엇이 전달됐는지 확인하세요.

연결된 도구 서버와 도구를 요청할 수 있는 모델은 애플리케이션의 서로 다른 구성 요소입니다. MCP는 도구 검색과 호출을 정의합니다. 그다음 호스트는 적절한 도구를 모델에 노출하고, 모델이 요청한 허용된 호출을 실행한 뒤 결과를 돌려줘야 합니다.[1][2] 첫 단계가 성공했다고 해서 마지막 단계까지 성공한 것은 아닙니다.

클라이언트가 받은 목록에서 도구 찾기

도구 하나부터 시작하세요. 영향을 받은 클라이언트가 실제로 받은 tools/list 결과를 읽고, 해당하는 경우 이어지는 페이지도 확인하세요. 이름, 설명, 입력 스키마를 보존하세요. 연결 표시만으로는 이 특정 도구가 검색됐는지 알 수 없습니다.

도구가 목록에 없다면 클라이언트를 실행하는 프로세스에서 선택한 서버, 지원되는 전송 방식, 인증을 확인하세요. 현재 MCP 사양에서는 제공된 권한 부여 정보에 따라 사용할 수 있는 도구가 달라질 수 있습니다.[1] 따라서 도구 하나가 보인다고 해서 같은 호출자가 해당 서버가 제공하는 모든 도구를 볼 수 있다는 뜻은 아닙니다.

reAPI 연결에서 문서화된 서버는 사용자 지정 Bearer 인증 헤더를 사용하는 원격 Streamable HTTP 방식입니다. 사용자 지정 헤더 없이 OAuth 로그인만 제공하는 클라이언트는 이 구성으로 연결할 수 없습니다.[3] 모델 지시를 반복해도 클라이언트에 없는 전송 방식이나 자격 증명 메커니즘을 제공할 수는 없습니다.

조사할 때 모델 제공업체 자격 증명과 도구 서버 자격 증명을 구분하세요. 둘은 서로 다른 연결에 속할 수 있습니다. 모델 API 키를 바꿔도 MCP 연결에서 누락된 자격 증명은 복구되지 않으며, MCP 자격 증명을 바꿔도 모델로 보내는 요청에 도구가 추가되지는 않습니다. 비밀 값 대신 안전한 구성 식별자를 기록하세요.

검색된 스키마와 모델이 실제로 보는 내용 비교하기

다음 가상의 읽기 전용 도구를 예로 들어 보겠습니다. ID로 기존 작업을 조회합니다. 이 조각은 검색 항목을 설명하기 위한 예시이며 완전한 프로토콜 응답도, 저희가 배포한 도구도 아닙니다.

{
  "name": "inspect_task_example",
  "description": "Look up the status of an existing task.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "task_id": { "type": "string" }
    },
    "required": ["task_id"]
  }
}

이제 모델로 보낸 직렬화 요청을 확인하세요. 모델용 도구 형식은 MCP의 inputSchema 형식과 다를 수 있지만 이름, 속성, 필수 필드의 의미는 변환 후에도 유지되어야 합니다. 호스트가 task_id 속성이나 필수 필드 목록 없이 도구 이름만 보낸다면 모델이 받은 계약은 달라진 것입니다.

이 지점은 어댑터를 수정할 수 있는 구체적인 위치입니다. 모델에게 “도구를 올바르게 사용하라”고 지시하는 긴 프롬프트를 써도 누락된 스키마가 복원되지는 않습니다. 지시를 더 추가하거나 제공업체를 다시 바꾸기 전에 두 객체를 비교하세요.

이 예시에서는 task_id가 세 곳에 있는지 비교하세요. 검색된 속성, 모델에 전달되는 속성, 호스트가 나중에 디스패치하는 인수입니다. 세 곳 모두 같은 필수 문자열 값을 가리켜야 합니다. 변환기가 한 곳에서는 id로 이름을 바꾸고 다른 곳에서는 task_id를 남겨 두면 불일치가 생긴 것입니다. 해당 필드의 이름, 유형, 필수 상태를 유지하면서 모델 API가 지원하는 정의 래퍼를 사용하세요.

오래된 정의도 확인하세요. 서버에서 도구 이름을 바꿔도 캐시된 클라이언트 목록에는 이전 이름이 남아 있을 수 있습니다. 모델이 실제로 받은 내용과 비교할 수 있도록 실패한 요청에 사용된 정의를 저장하세요. 별도의 문서 페이지에서 볼 수 있는 최신 스키마와 비교해서는 안 됩니다.

모델이 도구를 요청했나요, 아니면 사용하겠다고 말만 했나요?

모델 응답 구조를 살펴보세요. “작업을 확인하겠습니다”라는 일반 문장은 구조화된 도구 호출이 아닙니다. 거부, 일반 답변, 형식이 잘못된 호출, 유효한 호출은 모두 성공적인 HTTP 응답으로 도착했더라도 다음 조치가 서로 다릅니다.

요청에 올바른 스키마가 포함됐는데 호출이 반환되지 않았다면 모델 지원, 도구 선택 설정, 사용된 경로를 확인하세요. 자동 도구 선택은 일반 답변을 생성할 수 있고, 도구를 비활성화하는 설정은 선택을 막을 수 있습니다. 더 엄격한 도구 선택 값에 대한 지원 여부도 모델마다 다릅니다.[2] 호출이 없을 때마다 인수 형식 오류라고 판단하지 마세요.

중개자가 제공업체를 선택하는 경우 라우팅도 중요합니다. OpenRouter는 요청된 모든 매개변수를 지원하는 제공업체로 경로를 제한하는 require_parameters를 문서화합니다. 도구 관련 선호를 포함한 기본 매개변수 선호는 엄격한 필터링과 다릅니다.[4] 대체 모델과 요청을 처리한 경로를 확인하세요. 해당 제공업체 전용 옵션을 다른 API에 복사한 뒤 동등하게 작동한다고 가정하지 마세요.

구조화된 호출이 도착했다면 선택 문제 디버깅을 멈추고 그 호출을 따라가세요. 모델이 작업을 요청했지만 애플리케이션은 여전히 이를 실행해야 합니다. OpenRouter의 도구 호출 튜토리얼은 실행 책임이 모델이 아니라 호출자에게 있다고 명시합니다.[2]

실행과 반환 과정에서 같은 호출 ID 추적하기

다음은 가상의 예시에서 이어지는 부분으로, Chat Completions 메시지 형태를 사용합니다. ID와 결과는 만들어 낸 것입니다. 요청을 보내는 스크립트가 아니라 확인을 위한 메시지 조각입니다.

[
  {
    "role": "assistant",
    "content": null,
    "tool_calls": [
      {
        "id": "call_example_1",
        "type": "function",
        "function": {
          "name": "inspect_task_example",
          "arguments": "{\"task_id\":\"example_task_7\"}"
        }
      }
    ]
  },
  {
    "role": "tool",
    "tool_call_id": "call_example_1",
    "content": "{\"task_id\":\"example_task_7\",\"status\":\"processing\"}"
  }
]

이 두 메시지 사이에서 호스트는 허용된 호출을 도구에 디스패치하고 결과를 받아야 합니다. 모델 응답에 call_example_1이 포함됐다고 해서 디스패치가 이루어진 것은 아닙니다. 해당 실행 기록과 서버 결과를 확인하세요.

실행이 승인을 기다리고 있다면 그 상태를 유지하세요. 사용자가 거부했다면 거부된 작업이 결과입니다. 다른 도구를 사용하거나 재시도한다고 해서 그 결정을 우회할 권한이 생기는 것은 아닙니다. 승인이 났는데도 디스패치가 이루어지지 않았다면 호스트의 실행 로직을 조사하세요.

디스패치된 도구 이름과 인수도 요청된 호출과 대조하세요. 이 예시에서 조회에는 example_task_7이 전달되어야 합니다. 호스트가 실수로 이전 작업 ID를 재사용하면 서버가 유효한 결과를 반환하더라도 다른 조회를 실행한 것입니다. 모델 호출 ID와 도구 실행, 반환된 콘텐츠의 대응 관계를 저장하세요. 그러면 모델이 결과를 확신에 찬 답변에 반영하기 전에 잘못된 작업의 결과를 확인할 수 있습니다. 원본 도구의 스키마를 바꾸거나 접근 권한을 넓히지 말고 이 로컬 대응 관계를 수정하세요.

스트리밍 호출의 경우 인수가 완성될 때까지 기다리세요. OpenRouter는 호출 인덱스별로 델타를 모으고 인수 문자열이 완성된 뒤 파싱하는 방법을 설명합니다.[2] task_id 중간에서 끝나는 초기 조각은 아직 유효한 JSON이 아닙니다. 이를 완성된 상태에서도 유효하지 않은 인수 문자열과 구분하세요.

위의 두 번째 메시지는 첫 번째와 같은 호출 ID를 포함합니다. 문서화된 Chat Completions 루프에서는 어시스턴트의 도구 호출 턴 뒤에 요청된 각 호출의 결과 메시지가 이어집니다.[2] 여러 호출이 반환됐다면 각각의 식별 정보와 결과를 보존하세요. 모든 ID에 하나의 결과를 보내면 대화가 완료된 것처럼 보이면서 요청된 작업에 잘못된 데이터가 연결될 수 있습니다.

도구가 실제로 processing을 반환했지만 다음 모델 요청에서 도구 메시지가 빠졌다고 가정해 보세요. 실행은 성공했지만 모델은 결과를 받지 못했습니다. 또는 호스트가 변환 과정에서 결과를 빈 문자열로 바꿨다고 해 보세요. 모델을 바꿔도 대화에 같은 정보가 누락된 상태로 남습니다.

실제 서버 결과와 다음으로 전송되는 요청을 비교하세요. 클라이언트 로그의 성공 표시만이 아니라 관련 콘텐츠와 오류도 보존하세요. 모델의 최종 표현은 모델이 받은 결과를 기준으로 평가해야 합니다. 작업을 확인했다는 주장은 그 기록을 대신할 수 없습니다.

도구 오류를 그대로 드러내기

MCP는 프로토콜 문제와 도구 실행 실패를 구분합니다. 알 수 없는 도구나 잘못된 프로토콜 요청은 JSON-RPC 오류를 일으킬 수 있습니다. 도구 실행 실패는 대신 isError: true로 반환될 수 있습니다.[1] 모델에 결과를 변환할 때 이 구분과 관련 메시지를 보존하세요.

예시 조회에서 작업에 접근할 수 없다는 오류를 빈 성공 상태로 바꾸면 안 됩니다. 모델이 빈 문자열만 받으면 실패를 설명하거나 적절한 다음 조치를 선택하는 데 필요한 정보를 잃습니다. 최종 답변을 탓하기 전에 변환 과정을 살펴보세요.

유용한 로컬 점검 방법은 저장했거나 합성한 메시지를 어댑터에 전달하는 것입니다. 일반 결과 하나, 실행 오류 하나, 서로 다른 ID를 가진 호출 두 개를 사용하세요. 콘텐츠, 오류 의미, 식별 정보가 유지되는지 확인하세요. 이는 어댑터가 해당 테스트 데이터를 처리하는 방식을 검증할 뿐 원격 모델이 도구를 올바르게 선택한다는 것을 입증하지는 않습니다. 읽기 전용 도구를 선택하더라도 실제 모델 평가에는 추론 요금이 발생할 수 있습니다.

두 합성 결과를 서로 확연히 다르게 만든 뒤 요청과 반대 순서로 반환하세요. 호스트는 도착 순서가 아니라 호출 ID로 결과를 연결해야 합니다. 테스트 결과가 같으면 서로 바꿔도 다음 모델 입력에 차이가 없어 이 오류를 감출 수 있습니다.

생성 작업을 제출하기 전에 연결 점검 마치기

reAPI에서는 문제와 관련된 비제출 도구부터 사용하세요. MCP 참고 문서에 따르면 모델 검색, 스키마 조회, 견적, 작업 상태, 잔액 작업은 크레딧을 청구하지 않습니다. submit_task는 별도입니다. 작업을 생성하는 호출은 해당 작업에 대해 요금이 부과됩니다.[3]

문서화된 서버는 상태를 저장하지 않으며 HTTP 요청 하나당 JSON-RPC 메시지 하나를 받습니다. 배치 배열은 받지 않습니다. 미디어 입력은 base64나 data URI가 아니라 공개 HTTP 또는 HTTPS URL이어야 합니다.[3] 실행 단계에서 실패하면 실제 인터페이스 요구 사항을 확인하세요. 연결 테스트로 생성 작업을 반복 제출하지 마세요.

반환된 작업 ID를 보존하고 그 기존 작업을 조회하세요. reAPI 문서에 따르면 작업 제출은 멱등적이지 않습니다. 생성 요청을 반복하면 요금이 청구되는 작업이 하나 더 생길 수 있습니다.[3] 제출 응답을 잃어버렸다면 아무 일도 없었다고 가정하지 말고 접수 여부를 확인하세요.

가상의 조회에서는 메시지가 처음 달라지는 지점을 보여 줄 수 있을 때 마이그레이션 비교가 완료됩니다. 검색, 모델에 전달된 정의, 구조화된 호출, 실행, 반환 결과 중 어디인지 확인하세요. 그 구체적인 차이를 고친 뒤 같은 무해한 점검을 반복하세요. 서버, 모델, 클라이언트 버전, 기록된 호출을 함께 보관하면 다음 담당자가 연결됨 표시만 믿지 않고 무엇을 확인했는지 알 수 있습니다.

참고 자료

  1. Model Context Protocol, Tools specification, revision 2026-07-28. 열람일: 2026년 11월 16일. 프로토콜 버전과 서버 구현은 다를 수 있습니다.
  2. OpenRouter, “Tool Calling Across Any Model: Write the Loop Once, Swap the Model String,” 공식 튜토리얼, 2026년 9월 24일 업데이트. 열람일: 2026년 11월 16일.
  3. reAPI, MCP Server documentation. 검토일: 2026년 11월 16일. 이 가이드를 위해 실시간 생성 또는 클라이언트 호환성 테스트를 수행하지 않았습니다.
  4. OpenRouter, “Provider Routing,” 공식 문서의 “Requiring Providers to Support All Parameters” 및 “Default parameter preferences.” 열람일: 2026년 11월 16일.
모든 가이드