기존 MCP 서버 노출 및 관리

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

이 문서에서는 API Management를 사용하여 API Management 외부에서 호스트되는 도구 서버인 기존 MCP(모델 컨텍스트 프로토콜) 서버를 노출하고 제어하는 방법을 보여 줍니다. MCP 클라이언트가 MCP 프로토콜을 사용하여 호출할 수 있도록 API Management를 통해 서버의 도구를 노출하고 관리합니다.

예제 시나리오에는 다음이 포함됩니다.

서버별 인증 및 속도 제한이 있는 API Management를 통한 프록시 LangChain 또는 LangServe 도구 서버
IP 필터링 및 OAuth를 사용하여 Azure Logic Apps 기반 도구를 부조종사에 안전하게 노출합니다.
Azure Functions 및 오픈 소스 런타임에서 Azure API Center로 MCP 서버 도구를 중앙 집중화합니다.
GitHub Copilot, Claude by Anthropic 또는 ChatGPT를 사용하여 기업 전체의 도구와 안전하게 상호 작용할 수 있습니다.

또한 API Management는 관리형 REST API에서 API Management에 기본적으로 노출되는 MCP 서버를 지원합니다. 자세한 내용은 REST API를 MCP 서버로 노출을 참조하세요.

자세히 알아보기:

제한점

외부 MCP 서버는 MCP 버전 2025-06-18 이상을 준수해야 합니다. 서버는 다음을 지원할 수 있습니다.
- 다음 표준을 준수하는 권한 부여 또는 권한 부여 프로토콜이 없습니다. https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization#standards-compliance
- 스트리밍 가능한 HTTP 또는 SSE 전송 형식입니다.
API Management는 현재 MCP 서버 도구를 지원하지만 MCP 리소스 또는 프롬프트는 지원하지 않습니다.
API Management는 현재 작업 영역에서 MCP 서버 기능을 지원하지 않습니다.

필수 조건

API Management 인스턴스가 아직 없는 경우 다음 빠른 시작을 완료합니다. Azure API Management 인스턴스를 만듭니다. 인스턴스는 MCP 서버를 지원하는 서비스 계층 중 하나에 있어야 합니다.
외부 MCP 호환 서버(예: Azure Logic Apps, Azure Functions, LangServe 또는 기타 플랫폼에서 호스트됨)에 대한 액세스
보안 액세스를 위해 MCP 서버에 대한 적절한 자격 증명(예: OAuth 2.0 클라이언트 자격 증명 또는 서버에 따라 API 키).
API Management 인스턴스에 대한 전역 범위(모든 API)에서 Application Insights 또는 Azure Monitor를 통해 진단 로깅을 사용하도록 설정한 경우, 프런트 엔드 응답에 대한 로그할 페이로드 바이트 수 설정을 0으로 설정합니다. 이 설정은 모든 API에서 의도하지 않은 응답 본문 로깅을 방지하고 MCP 서버의 적절한 작동을 보장하는 데 도움이 됩니다. 특정 API에 대해 페이로드를 선택적으로 기록하려면 API 범위에서 개별적으로 설정을 구성하여 응답 로깅에 대한 대상 제어를 허용합니다.
MCP 서버를 테스트하려면 GitHub Copilot 또는 MCP 검사기 같은 도구에 액세스할 수 있는 Visual Studio Code를 사용합니다.

기존 MCP 서버 노출

API Management에서 기존 MCP 서버를 노출하려면 다음 단계를 수행합니다.

Azure Portal에서 API Management 인스턴스로 이동합니다.
왼쪽 메뉴의 API에서 MCP 서버>+ MCP 서버 만들기를 선택합니다.
기존 MCP 서버 노출을 선택합니다.
백 엔드 MCP 서버에서:
1. 기존 MCP 서버 기본 URL을 입력합니다. 예를 들어 https://learn.microsoft.com/api/mcp Microsoft Learn MCP 서버의 경우입니다.
2. 전송 유형에서 스트리밍 가능한 HTTP는 기본적으로 선택됩니다.
새 MCP 서버에서:
1. API Management에서 MCP 서버의 이름을 입력합니다.
2. 기본 경로에서 도구에 대한 경로 접두사를 입력합니다. 예: mytools.
3. 필요에 따라 MCP 서버에 대한 설명을 입력합니다.
선택하고생성합니다.

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

MCP 서버가 만들어지고 원격 서버의 작업이 도구로 노출됩니다.
MCP 서버는 MCP 서버 창에 나열됩니다. 서버 URL 열에는 테스트 또는 클라이언트 애플리케이션 내에서 호출할 MCP 서버 URL이 표시됩니다.

중요합니다

현재 API Management는 기존 MCP 서버의 도구를 표시하지 않습니다. 기존 원격 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