이 페이지는 Apigee 및 Apigee Hybrid에 적용됩니다.
Apigee Edge 문서 보기
이 페이지에서는 Apigee API 제품을 사용하여 MCP 도구에 대한 액세스를 제어하는 방법을 설명합니다. Apigee MCP 검색 프록시를 사용하든 자체 MCP 서버로 트래픽을 프록시하든 MCP 클라이언트를 인증하고, 도구별 할당량을 적용하고, API 제품 구성을 기반으로 도구 공개 상태를 필터링할 수 있습니다.
MCP 서버는 모든 도구 호출에 단일 엔드포인트 (예: /mcp)를 사용합니다. 작업이 URL 경로와 HTTP 메서드로 구분되는 REST API와 달리 MCP는 JSON-RPC 요청 본문에 작업을 삽입합니다. Apigee는 ParsePayload 정책을 사용하여 이러한 작업을 추출하므로 표준 API 관리 정책(인증, 할당량 적용, 도구 필터링)을 도구별로 적용할 수 있습니다.
개요
API 제품으로 MCP 도구 액세스를 관리하려면 다음 단계를 완료하세요.
- ParsePayload 정책을 추가하여 요청 본문에서 MCP 도구 이름을 추출합니다.
- MCP 도구 작업 및 도구별 할당량으로 API 제품을 구성합니다.
- 개발자 앱을 등록하여 클라이언트 사용자 인증 정보를 가져옵니다.
- API 제품에 대해 클라이언트 사용자 인증 정보를 확인하는 인증 정책 (API 키 또는 OAuth 2.0)을 추가합니다.
- 도구별 비율 제한을 적용하려면 할당량 정책을 추가하세요.
- 테스트 도구 필터링을 통해
tools/list응답이 API 제품 구성에 따라 필터링되는지 확인합니다.
ParsePayload 정책 추가
ParsePayload 정책은 JSON-RPC 요청 본문을 파싱하고 tools/call/get_weather 또는 tools/list과 같은 MCP 작업을 추출합니다. 추출된 작업은 정책 이름 (예: parsepayload.ParsePayload-MCP.operation)이 접두사로 붙은 흐름 변수에 저장되며, 다운스트림 정책은 이를 사용하여 인증 및 할당량 적용을 실행합니다.
다음 ParsePayload 정책을 MCP 프록시의 요청 PreFlow에 추가합니다.
<ParsePayload name="ParsePayload-MCP"> <DisplayName>Parse MCP Payload</DisplayName> <Source>request</Source> <PayloadType>JSON-RPC-2.0</PayloadType> <Protocol>MCP</Protocol> </ParsePayload>
각 항목의 의미는 다음과 같습니다.
<Source>: 파싱할 메시지입니다. 기본값은request입니다.<PayloadType>: 페이로드 형식입니다.JSON-RPC-2.0여야 합니다.<Protocol>: 파싱에 사용할 프로토콜입니다. MCP 서버의 경우MCP이어야 합니다.
실행 후 정책은 parsepayload.policyName.suffix 패턴에 따라 정책 인스턴스 이름이 접두사로 붙은 흐름 변수를 채웁니다.
ParsePayload-MCP라는 정책의 경우 다음 변수가 설정됩니다.
| 흐름 변수 | 설명 | 예시 값 |
|---|---|---|
parsepayload.ParsePayload-MCP.operation |
API 제품 일치 및 할당량 적용에 사용되는 파생 작업 이름입니다. | tools/call/get_weather |
parsepayload.ParsePayload-MCP.json-rpc.request.method |
요청의 JSON-RPC method 필드입니다. |
tools/call |
parsepayload.ParsePayload-MCP.json-rpc.request.id |
요청의 JSON-RPC id 필드입니다. |
1 |
parsepayload.ParsePayload-MCP.json-rpc.request.params.name |
요청의 params.name 필드입니다. |
get_weather |
MCP 도구 작업으로 API 제품 구성
API 제품은 클라이언트 애플리케이션이 액세스할 수 있는 MCP 도구와 각 도구의 할당량 한도를 정의합니다. API 제품 정의의 payloadOperationGroup 필드를 사용하여 MCP 도구 작업을 구성합니다.
payloadOperationGroup.operationConfigs의 각 항목은 다음을 지정합니다.
- MCP 도구를 제공하는 API 프록시 (
apiSource) - 하나 이상의 도구 작업 (예:
tools/call/get_stock_price,tools/list) - 해당 작업 집합의 할당량입니다(선택사항).
다음 API 호출을 사용하여 MCP 도구 작업이 포함된 API 제품을 만듭니다.
curl -X POST \ "https://apigee.googleapis.com/v1/organizations/ORG_NAME/apiproducts" \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json" \ -d '{ "name": "PRODUCT_NAME", "displayName": "PRODUCT_DISPLAY_NAME", "approvalType": "auto", "payloadOperationGroup": { "operationConfigs": [ { "apiSource": "MCP_PROXY_NAME", "operations": [ { "operation": "tools/call/get_stock_price" }, { "operation": "tools/call/get_company_news" } ], "quota": { "limit": "100", "interval": "1", "timeUnit": "minute" } }, { "apiSource": "MCP_PROXY_NAME", "operations": [ { "operation": "tools/list" } ], "quota": { "limit": "300", "interval": "1", "timeUnit": "minute" } } ] } }'
각 항목의 의미는 다음과 같습니다.
ORG_NAME은 Apigee 조직의 이름입니다.PRODUCT_NAME은 API 제품의 내부 이름입니다.PRODUCT_DISPLAY_NAME은 API 제품의 표시 이름입니다.MCP_PROXY_NAME은 트래픽을 MCP 서버로 라우팅하는 API 프록시의 이름입니다. Apigee MCP 탐색 프록시 또는 자체 MCP 서버가 백엔드인 프록시일 수 있습니다.
도구별 할당량 구성
개별 도구에 대해 서로 다른 할당량을 구성할 수 있습니다. 예를 들어 다음 구성은 get_stock_price를 분당 300회 호출로 제한하지만 get_company_news는 분당 3회 호출로 제한합니다.
{ "payloadOperationGroup": { "operationConfigs": [ { "apiSource": "MCP_PROXY_NAME", "operations": [ { "operation": "tools/call/get_stock_price" } ], "quota": { "limit": "300", "interval": "1", "timeUnit": "minute" } }, { "apiSource": "MCP_PROXY_NAME", "operations": [ { "operation": "tools/call/get_company_news" } ], "quota": { "limit": "3", "interval": "1", "timeUnit": "minute" } }, { "apiSource": "MCP_PROXY_NAME", "operations": [ { "operation": "tools/list" } ], "quota": { "limit": "300", "interval": "1", "timeUnit": "minute" } } ] } }
다양한 도구 하위 집합을 사용하여 여러 API 제품을 만들어 등급별 액세스를 제공할 수 있습니다.
예를 들어 Basic 제품에는 tools/call/get_stock_price만 포함될 수 있지만 Premium 제품에는 할당량이 더 높은 모든 사용 가능한 도구가 포함됩니다. 각 개발자 앱은 하나 이상의 API 제품과 연결되므로 서로 다른 클라이언트는 독립적인 비율 제한이 있는 서로 다른 도구 세트에 자동으로 액세스할 수 있습니다.
개발자 앱 등록
테스트용 API 키 또는 OAuth 사용자 인증 정보를 가져오려면 개발자를 등록하고 이전 단계에서 만든 API 제품과 연결된 개발자 앱을 만드세요.
- Apigee 조직에 앱 개발자를 등록합니다.
- 개발자 앱을 만들고 API 제품과 연결합니다.
- 앱 사용자 인증 정보에서 고객 키 (API 키)를 가져옵니다. 다음 인증 예에서 이 키를 사용합니다.
인증 정책 추가
ParsePayload 정책을 추가한 후 클라이언트가 요청된 MCP 도구를 사용할 수 있는지 확인하는 인증 정책을 추가합니다. Apigee는 추출된 작업을 클라이언트의 API 제품에 정의된 작업과 일치시킵니다.
요청된 도구가 클라이언트의 API 제품에 나열되지 않으면 Apigee에서 401 Unauthorized 오류를 반환합니다.
옵션 1: API 키 인증
VerifyAPIKey 정책을 사용하여 API 키를 통해 클라이언트를 인증합니다. ParsePayload 정책 뒤에 요청 PreFlow에 이 정책을 추가합니다.
<VerifyAPIKey name="VerifyAPIKey-1"> <DisplayName>Verify API Key</DisplayName> <APIKey ref="request.queryparam.apikey"/> </VerifyAPIKey>
클라이언트는 MCP 프록시를 호출할 때 API 키를 쿼리 매개변수로 전달합니다.
curl -X POST "https://RUNTIME_HOSTNAME/mcp?apikey=API_KEY" \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "method": "tools/call", "params": { "name": "get_stock_price", "arguments": { "ticker": "GOOGL" } }, "id": 1 }'
헤더에서 API 키를 읽도록 정책을 구성할 수도 있습니다.
<VerifyAPIKey name="VerifyAPIKey-1"> <DisplayName>Verify API Key</DisplayName> <APIKey ref="request.header.x-api-key"/> </VerifyAPIKey>
옵션 2: OAuth 2.0 인증
VerifyAccessToken 작업과 함께 OAuthV2 정책을 사용하여 OAuth 2.0 액세스 토큰을 사용하여 클라이언트를 인증합니다. ParsePayload 정책 다음에 요청 PreFlow에 이 정책을 추가합니다.
<OAuthV2 name="OAuthV2-VerifyAccessToken"> <DisplayName>Verify OAuth Access Token</DisplayName> <Operation>VerifyAccessToken</Operation> </OAuthV2>
클라이언트는 Authorization 헤더에 액세스 토큰을 전달합니다.
curl -X POST "https://RUNTIME_HOSTNAME/mcp" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer ACCESS_TOKEN" \ -d '{ "jsonrpc": "2.0", "method": "tools/call", "params": { "name": "get_stock_price", "arguments": { "ticker": "GOOGL" } }, "id": 1 }'
Apigee에서 OAuth 2.0을 구성하는 방법에 대한 자세한 내용은 OAuth2 시작하기를 참고하세요.
할당량 정책 추가
API 제품에 정의된 도구별 비율 제한을 적용하는 Quota 정책을 추가합니다.
이 정책은 UseQuotaConfigInAPIProduct를 사용하여 일치하는 API 제품 작업의 할당량 구성을 자동으로 적용합니다.
인증 정책 다음에 요청 PreFlow에 다음 할당량 정책을 추가합니다.
<Quota name="Quota-PerToolLimit"> <DisplayName>Per-Tool Quota</DisplayName> <UseQuotaConfigInAPIProduct stepName="AUTH_POLICY_STEP_NAME"/> <Distributed>true</Distributed> </Quota>
여기서 AUTH_POLICY_STEP_NAME은 인증 정책 XML 요소 (이 페이지의 예에서는 VerifyAPIKey-1 또는 OAuthV2-VerifyAccessToken)의 name 속성 값입니다. 이는 정책 <DisplayName>이 아닌 name 속성과 일치해야 합니다.
이 구성을 사용하면 각 도구 작업이 API 제품에 정의된 할당량에 따라 독립적으로 비율 제한됩니다. 예를 들어 tools/call/get_stock_price의 할당량이 분당 300개이고 tools/call/get_company_news의 할당량이 분당 3개인 경우 두 도구가 동일한 프록시를 통해 액세스되더라도 각 한도는 별도로 적용됩니다.
프록시 구성 완료
다음 예는 ParsePayload, API 키 인증, 도구별 할당량 적용이 있는 MCP 프록시의 전체 요청 PreFlow 구성을 보여줍니다.
<ProxyEndpoint name="default"> <PreFlow> <Request> <Step> <Name>ParsePayload-MCP</Name> </Step> <Step> <Name>VerifyAPIKey-1</Name> </Step> <Step> <Name>Quota-PerToolLimit</Name> </Step> </Request> </PreFlow> <HTTPProxyConnection> <BasePath>/mcp</BasePath> </HTTPProxyConnection> <RouteRule name="default"> <TargetEndpoint>default</TargetEndpoint> </RouteRule> </ProxyEndpoint>
도구 필터링
클라이언트가 API 키 또는 OAuth 인증을 사용하여 MCP 프록시를 통해 tools/list 요청을 보내면 Apigee는 클라이언트의 API 제품에 등록된 도구만 포함하도록 응답을 자동으로 필터링합니다.
예를 들어 클라이언트의 API 제품에 tools/call/get_stock_price 및 tools/call/get_company_news 작업이 포함된 경우 MCP 서버에서 추가 도구를 노출하더라도 MCP 서버의 tools/list 응답은 get_stock_price 및 get_company_news만 반환하도록 필터링됩니다.
이 필터링은 다음 구성이 적용된 경우 기본적으로 발생합니다. 전용 필터링 정책이 필요하지 않습니다.
- 요청 PreFlow에는 ParsePayload와 인증 정책(VerifyAPIKey 또는 OAuthV2)이 포함됩니다.
- API 제품에는
payloadOperationGroup에tools/list가 포함됩니다. - API 제품은 클라이언트가 액세스할 수 있는 도구 작업 (예:
tools/call/get_stock_price)을 지정합니다.
도구 필터링을 테스트하려면 클라이언트의 API 키를 사용하여 tools/list 요청을 전송하세요.
curl -X POST "https://RUNTIME_HOSTNAME/mcp?apikey=API_KEY" \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "method": "tools/list", "id": 1 }'
API 제품에 tools/call/get_stock_price 및 tools/call/get_company_news가 포함된 경우 MCP 서버에서 추가 도구를 노출하더라도 필터링된 응답은 다음과 비슷합니다.
{ "jsonrpc": "2.0", "result": { "tools": [ { "name": "get_stock_price", "description": "Get the current stock price for a given ticker symbol.", "inputSchema": { "type": "object", "properties": { "ticker": { "type": "string", "description": "Stock ticker symbol" } }, "required": ["ticker"] } }, { "name": "get_company_news", "description": "Get recent news articles for a company.", "inputSchema": { "type": "object", "properties": { "company": { "type": "string", "description": "Company name" } }, "required": ["company"] } } ] }, "id": 1 }
API 제품에 나열되지 않은 도구 (예: delete_account 또는 admin_reset)는 대답에서 자동으로 삭제됩니다.
다음 디버그 세션은 응답 흐름의 McpToolsFilterExecution 단계를 보여주며, mcp_flow_info.mcp.allowed.tools 속성에는 API 제품에서 허용하는 도구가 나열되어 있습니다.
도구별 로직에 조건부 흐름 사용
API 제품 할당량에서 제공하는 것 이상의 도구별 로직이 필요한 경우(예: 도구별 SpikeArrest 비율 적용, 다른 백엔드로 라우팅, 특정 도구에 대한 요청 변환 추가) 조건부 흐름을 사용합니다. 조건부 흐름은 parsepayload.policyName.operation 흐름 변수를 사용하여 추출된 MCP 작업과 일치시킵니다.
ParsePayload-MCP라는 ParsePayload 정책의 경우:
<Flows> <Flow name="ListTools"> <Condition>(parsepayload.ParsePayload-MCP.operation = "tools/list")</Condition> <Request/> </Flow> <Flow name="GetStockPrice"> <Condition>(parsepayload.ParsePayload-MCP.operation = "tools/call/get_stock_price")</Condition> <Request> <Step> <Name>SpikeArrest-StockPrice</Name> </Step> </Request> </Flow> <Flow name="GetCompanyNews"> <Condition>(parsepayload.ParsePayload-MCP.operation = "tools/call/get_company_news")</Condition> <Request> <Step> <Name>SpikeArrest-CompanyNews</Name> </Step> </Request> </Flow> </Flows>
프록시 구성 디버그
Apigee 디버그 도구를 사용하여 ParsePayload 정책이 MCP 작업을 올바르게 추출하고 인증 및 할당량 정책이 예상대로 작동하는지 확인합니다.
디버그 세션에서 ParsePayload 정책 단계 (여기서 ParsePayload-MCP은 정책 이름임) 후에 다음 흐름 변수를 확인합니다.
parsepayload.ParsePayload-MCP.operation: 전체 작업 이름 (예:tools/call/get_stock_price)을 포함해야 합니다.parsepayload.ParsePayload-MCP.json-rpc.request.method: JSON-RPC 메서드 (예:tools/call)를 포함해야 합니다.
제한사항
- ParsePayload 정책은 페이로드 유형으로
JSON-RPC-2.0만 지원합니다. - API 제품 도구 작업은
tools/call및tools/list메서드만 지원합니다.tools/list응답의 도구 필터링은 API 제품에 구성된tools/call작업에만 적용됩니다. - ParsePayload 정책은 전체 요청 본문을 파싱합니다. Apigee는 기본 요청 본문 크기 제한을 10MB로 적용하며,
request.payload.parse.limit속성을 사용하여 최대 30MB까지 구성할 수 있습니다. 자세한 내용은 엔드포인트 속성 참조를 확인하세요. - MCP 프로토콜이 적용된 ParsePayload 정책은 JSON-RPC 요청 페이로드(
method및params필드 포함)만 파싱합니다. MCP 응답 페이로드가 파싱되지 않습니다. tools/list응답의 도구 필터링에는 요청 PreFlow의 ParsePayload 및 인증 정책이 필요합니다.
다음 단계
- Apigee의 MCP에 대해 자세히 알아보려면 Apigee의 MCP 개요를 참고하세요.
- Apigee 및 MCP 시작하기에서 MCP 프록시를 시작하세요.
- API 제품 및 API 제품 관리에 대해 알아봅니다.
- Apigee의 비율 제한에 대해 알아봅니다.
- API 키 및 OAuth 2.0 인증에 대해 알아봅니다.