API Management에서 REST API를 MCP 서버로 노출

적용 대상: 개발자 | 기본 | 기본 v2 | 표준 | 표준 v2 | 프리미엄 | 프리미엄 v2

API Management에서는 기본 제공 AI 게이트웨이를 사용하여 API Management에서 관리되는 REST API를 MCP(원격 모델 컨텍스트 프로토콜) 서버로 노출할 수 있습니다. MCP 클라이언트가 MCP 프로토콜을 사용하여 호출할 수 있는 도구로 하나 이상의 API 작업을 노출합니다.

Azure API Management는 API Management 외부에서 호스트되는 도구 서버인 기존 MCP 호환 서버와의 보안 통합도 지원합니다. 자세한 내용은 기존 MCP 서버 노출을 참조하세요.

자세히 알아보기:

제한점

API Management는 현재 MCP 서버 도구를 지원하지만 MCP 리소스 또는 프롬프트는 지원하지 않습니다.
API Management는 현재 작업 영역에서 MCP 서버 기능을 지원하지 않습니다.

필수 조건

API Management 인스턴스가 아직 없는 경우 다음 빠른 시작을 완료합니다. Azure API Management 인스턴스를 만듭니다. 인스턴스는 MCP 서버를 지원하는 서비스 계층 중 하나에 있어야 합니다.
인스턴스가 MCP 서버로 노출하려는 HTTP 호환 API(Azure 리소스에서 가져온 API를 포함하여 REST API로 가져온 모든 API)를 관리해야 합니다. 샘플 API를 가져오려면 첫 번째 API 가져오기 및 게시를 참조하세요.

비고

HTTP 호환되지 않는 API Management의 다른 API 형식은 MCP 서버로 노출될 수 없습니다.
API Management 서비스 인스턴스에 대한 전역 범위(모든 API)에서 Application Insights 또는 Azure Monitor를 통해 진단 로깅을 사용하도록 설정하는 경우 프런트엔드 응답의 로그할 페이로드 바이트 수 설정을 0으로 설정합니다. 이 설정은 모든 API에서 의도하지 않은 응답 본문 로깅을 방지하고 MCP 서버의 적절한 작동을 보장하는 데 도움이 됩니다. 특정 API에 대해 페이로드를 선택적으로 기록하려면 API 범위에서 개별적으로 설정을 구성하여 응답 로깅에 대한 대상 제어를 허용합니다.
MCP 서버를 테스트하려면 GitHub Copilot 또는 MCP Inspector와 같은 도구에 액세스할 수 있는 Visual Studio Code를 사용할 수 있습니다.

API를 MCP 서버로 노출

다음 단계에 따라 API Management에서 관리되는 REST API를 MCP 서버로 노출합니다.

Azure Portal에서 API Management 인스턴스로 이동합니다.
왼쪽 메뉴의 API에서 MCP 서버>+ MCP 서버 만들기를 선택합니다.
MCP 서버로 API 노출을 선택합니다.
백 엔드 MCP 서버에서:
1. MCP 서버로 노출할 관리되는 API 를 선택합니다.
2. 도구로 노출할 하나 이상의 API 작업을 선택합니다. 모든 작업 또는 특정 작업만 선택할 수 있습니다.
  
  비고
  
  나중에 MCP 서버의 도구 블레이드에서 도구로 노출된 작업을 업데이트할 수 있습니다.
새 MCP 서버에서:
1. API Management에서 MCP 서버의 이름을 입력합니다.
2. 필요에 따라 MCP 서버에 대한 설명을 입력합니다.
선택하고생성합니다.

포털에서 MCP 서버를 만드는 스크린샷

MCP 서버가 만들어지고 API 작업이 도구로 노출됩니다.
MCP 서버는 MCP 서버 블레이드에 나열됩니다. 서버 URL 열에는 테스트를 호출하거나 클라이언트 애플리케이션 내에서 호출할 MCP 서버의 엔드포인트가 표시됩니다.

MCP 서버에 대한 정책 구성

MCP 서버를 관리하는 데 도움이 되도록 하나 이상의 API Management 정책을 구성합니다. 정책은 MCP 서버에서 도구로 노출되는 모든 API 작업에 적용됩니다. 이러한 정책을 사용하여 도구의 액세스, 인증 및 기타 측면을 제어합니다.

정책 구성에 대해 자세히 알아보세요.

주의

MCP 서버 정책 내에서 context.Response.Body 변수를 사용하여 응답 본문에 액세스하지 마세요. 이렇게 하면 응답 버퍼링이 트리거되어 MCP 서버에 필요한 스트리밍 동작을 방해하고 오작동을 일으킬 수 있습니다.

MCP 서버에 대한 정책을 구성하려면 다음 단계를 수행합니다.

Azure Portal에서 API Management 인스턴스로 이동합니다.
왼쪽 메뉴의 API에서 MCP 서버를 선택합니다.
목록에서 MCP 서버를 선택합니다.
왼쪽 메뉴의 MCP에서 정책을 선택합니다.

정책 편집기에서 MCP 서버의 도구에 적용할 정책을 추가하거나 편집합니다. XML 형식으로 정책을 정의합니다.

예를 들어 MCP 서버의 도구에 대한 호출을 제한하는 정책을 추가할 수 있습니다(이 예제에서는 MCP 세션당 60초당 한 번의 호출).

<!-- Rate limit tool calls by Mcp-Session-Id header -->
<set-variable name="body" value="@(context.Request.Body.As<string>(preserveContent: true))" />
<choose>
    <when condition="@(
        Newtonsoft.Json.Linq.JObject.Parse((string)context.Variables["body"])["method"] != null 
        && Newtonsoft.Json.Linq.JObject.Parse((string)context.Variables["body"])["method"].ToString() == "tools/call"
    )">
    <rate-limit-by-key 
        calls="1" 
        renewal-period="60" 
        counter-key="@(
            context.Request.Headers.GetValueOrDefault("Mcp-Session-Id", "unknown")
        )" />
    </when>
</choose>

비고

API Management는 MCP 서버 범위에서 정책을 평가하기 전에 전역(모든 API) 범위에서 구성된 정책을 평가합니다.

MCP 서버 유효성 검사 및 사용

규격 LLM 에이전트(예: GitHub Copilot, 의미 체계 커널 또는 Copilot Studio) 또는 테스트 클라이언트(예: curl)를 사용하여 API Management 호스팅 MCP 엔드포인트를 호출합니다. 요청에 적절한 헤더 또는 토큰이 포함되어 있는지 확인하고 MCP 서버에서 성공적인 라우팅 및 응답을 확인합니다.

팁 (조언)

MCP 검사기를 사용하여 API Management에서 관리하는 MCP 서버를 테스트하는 경우 버전 0.9.0을 사용합니다.

Visual Studio Code에서 MCP 서버 추가

Visual Studio Code에서 에이전트 모드에서 GitHub Copilot 채팅을 사용하여 MCP 서버를 추가하고 도구를 사용합니다. Visual Studio Code의 MCP 서버에 대한 배경 정보는 VS Code에서 MCP 서버 사용을 참조하세요.

Visual Studio Code에서 MCP 서버를 추가하려면 다음을 수행합니다.

명령 팔레트에서 MCP: 서버 추가 명령을 사용합니다.
메시지가 표시되면 서버 유형 HTTP(HTTP 또는 서버 전송 이벤트)를 선택합니다.
API Management에서 MCP 서버의 서버 URL 을 입력합니다. 예를 들어 https://<apim-service-name>.azure-api.net/<api-name>-mcp/mcp MCP 엔드포인트의 경우입니다.
원하는 서버 ID 를 입력합니다.
구성을 작업 영역 설정 또는 사용자 설정에 저장할지 여부를 선택합니다.
- 작업 영역 설정 - 서버 구성은 현재 작업 영역에서만 사용할 수 있는 파일에 저장 .vscode/mcp.json 됩니다.
- 사용자 설정 - 서버 구성이 전역 settings.json 파일에 추가되고 모든 작업 영역에서 사용할 수 있습니다. 구성은 다음과 유사합니다.

인증 헤더와 같은 설정에 대한 필드를 JSON 구성에 추가합니다. 다음 예제에서는 입력 값에서와 같이 헤더에 전달된 API Management 구독 키에 대한 구성을 보여줍니다. 구성 형식에 대해 자세히 알아보기

MCP 서버에 대한 인증 헤더 구성의 스크린샷

에이전트 모드에서 도구 사용

Visual Studio Code에서 MCP 서버를 추가한 후 에이전트 모드에서 도구를 사용할 수 있습니다.

GitHub Copilot 채팅에서 에이전트 모드를 선택하고 도구 단추를 선택하여 사용 가능한 도구를 확인합니다.
채팅에서 사용할 수 있도록 MCP 서버에서 하나 이상의 도구를 선택합니다.
채팅에 프롬프트를 입력하여 도구를 호출합니다. 예를 들어 주문에 대한 정보를 가져오는 도구를 선택한 경우 에이전트에게 주문에 대해 요청할 수 있습니다.
```
Get information for order 2
```
결과를 보려면 [계속]을 선택합니다. 에이전트는 이 도구를 사용하여 MCP 서버를 호출하고 채팅의 결과를 반환합니다.

문제 해결 및 알려진 문제

문제	원인	해결책
`401 Unauthorized` 백 엔드의 오류	인증 헤더가 전달되지 않음	필요한 경우 정책을 사용하여 `set-header` 토큰을 수동으로 연결합니다.
API 호출은 API Management에서 작동하지만 에이전트에서 실패합니다.	잘못된 기본 URL 또는 누락된 토큰	보안 정책 및 엔드포인트 다시 확인
진단 로그를 사용하도록 설정하면 MCP 서버 스트리밍이 실패합니다.	정책을 통해 응답 본문 또는 응답 본문에 액세스하는 로깅은 MCP 전송을 방해합니다.	모든 API 범위에서 응답 본문 로깅 사용 안 함 - 필수 구성 요소 참조

피드백

이 페이지가 도움이 되었나요?

Last updated on 2025-11-19