Apigee 및 MCP 시작하기

이 페이지는 Apigee에 적용되지만 Apigee Hybrid에는 적용되지 않습니다.

이 페이지에서는 Apigee 검색 프록시를 사용하여 에이전트 애플리케이션의 모델 컨텍스트 프로토콜(MCP) 클라이언트가 MCP 도구로 API를 사용할 수 있도록 하는 방법을 설명합니다.

시작하기 전에

시작하기 전에 다음 작업을 완료하세요.

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Apigee 조직이 프로비저닝되어 있는지 확인합니다. 자세한 내용은 프로비저닝 소개를 참고하세요.

필요한 역할

MCP 검색 프록시를 만들고 배포하는 데 필요한 권한을 얻으려면 Apigee 프록시 배포에 사용하는 서비스 계정에 대한 Apigee 관리자(roles/apigee.admin) IAM 역할을 부여해 달라고 관리자에게 요청하세요. 역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참고하세요.

커스텀 역할이나 다른 사전 정의된 역할을 통해 필요한 권한을 얻을 수도 있습니다.

API 사용 설정

Enable the Apigee, Model Armor APIs.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

환경 변수 설정하기

Apigee 인스턴스가 포함된 Google Cloud 프로젝트에서 다음 명령어를 사용하여 환경 변수를 설정합니다.

export PROJECT_ID=PROJECT_ID
export REGION=REGION
export RUNTIME_HOSTNAME=RUNTIME_HOSTNAME

각 항목의 의미는 다음과 같습니다.

PROJECT_ID: Apigee 인스턴스가 있는 프로젝트의 ID
REGION: Apigee 인스턴스의 Google Cloud 리전
RUNTIME_HOSTNAME: Apigee 런타임의 호스트 이름

환경 변수가 올바르게 설정되었는지 확인하려면 다음 명령어를 실행하고 출력을 검토합니다.

echo $PROJECT_ID $REGION $RUNTIME_HOSTNAME

프로젝트 설정

개발 환경에서 Google Cloud 프로젝트를 설정합니다.

    gcloud auth login
    gcloud config set project $PROJECT_ID

개요

Apigee를 사용하여 API를 MCP 도구로 노출하려면 MCP 검색 프록시 템플릿을 사용하여 새 Apigee 프록시를 만들고 배포합니다. 프록시가 배포된 후 프록시의 MCP API 작업을 API 제품으로 번들로 묶는 API 제품을 만들 수 있습니다. API 제품으로서 API 작업/도구는 API 허브에 통합되어 MCP 클라이언트가 검색할 수 있습니다.

다음 섹션에서는 MCP 검색 프록시를 만들고 배포하고, API 제품을 만들고, 사용 가능한 도구를 나열하는 단계를 설명합니다.

API 작업을 설명하는 OpenAPI 3.0.x 사양을 만듭니다.
MCP 디스커버리 프록시를 만듭니다.
(선택사항) MCP 검색 프록시에 Google 인증 정책을 추가합니다.
MCP 검색 프록시를 배포합니다.
(선택사항) API 제품을 만듭니다.
(선택사항) 개발자 및 앱을 만듭니다.
(선택사항) MCP 서버를 초기화합니다.
사용 가능한 도구를 나열합니다.

API 작업을 설명하는 OpenAPI 3.0.x 사양 만들기

MCP 검색 프록시를 만들고 배포하기 전에 MCP 도구로 노출할 API 작업을 설명하는 OpenAPI 3.0.x 사양을 만들어야 합니다. 이 빠른 시작에서는 세 가지 API 작업이 포함된 샘플 OpenAPI 3.0.x 사양을 사용합니다.

GET/artists: 아티스트 목록을 반환합니다.
POST/artists: 사용자가 새 아티스트를 게시할 수 있습니다.
GET /artists/{username}: 고유한 사용자 이름으로 아티스트에 관한 정보를 가져옵니다.

OpenAPI 3.0.x 사양을 만들려면 다음 단계를 따르세요.

API 프록시 번들의 oas 디렉터리에 새 mcp-quickstart-openapi.yaml 파일을 만듭니다.

파일에 다음 콘텐츠를 추가합니다.

# mcp-quickstart-openapi.yaml
---
openapi: 3.0.3
info:
  title: Cymbal Group Products API
  description: This is the official API for managing the artists for Cymbal Group Products.
  version: 1.0.0
servers:
  - url: https://cymbal.products.com/v1
    description: Cymbal Group Production Server
  - url: https://internal.products.com/v1
    description: Cymbal Group internal Server
paths:
  /artists:
    get:
      description: Returns a list of artists
      operationId: listArtists
      parameters:
        - name: limit
          in: query
          description: Limits the number of items on a page
          schema:
            type: integer
        - name: offset
          in: query
          description: Specifies the page number of the artists to be displayed
          schema:
            type: integer
      responses:
        "200":
          description: An array of artists
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Artist"
    post:
      summary: Create a new artist
      operationId: createArtist
      tags:
        - artists
      requestBody:
        description: The artist to create.
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Artist"
      responses:
        "201":
          description: The newly created artist profile
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Artist"
        "400":
          description: Invalid username supplied
  /artists/{username}:
    get:
      summary: Info for a specific artist
      operationId: showArtistByUsername
      tags:
        - artists
      parameters:
        - name: username
          in: path
          required: true
          description: The username of the artist to retrieve
          schema:
            type: string
      responses:
        "200":
          description: Expected response to a valid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Artist"
        "404":
          description: Artist not found
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: /oauth/authorize
          tokenUrl: /oauth/token
          scopes:
            artists.read: Grants read access
            artists.write: Grants write access
  schemas:
    Artist:
      type: object
      required:
        - id
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the artist

MCP 검색 프록시 만들기

이제 API 작업을 정의하는 OpenAPI 3.0.x 사양이 있으므로 MCP 검색 프록시 템플릿을 사용하여 새 API 프록시를 만들 수 있습니다.

MCP 검색 프록시를 만들려면 다음 단계를 따르세요.

Google Cloud 콘솔의 API 프록시 페이지로 이동합니다.
API 프록시로 이동
+ 만들기를 클릭하여 API 프록시 만들기 창을 엽니다.
프록시 템플릿 상자에서 MCP 검색 프록시를 선택합니다.
프록시 세부정보 섹션에서 다음 세부정보를 입력합니다.
- 프록시 이름: 프록시의 이름
- 설명(선택사항): 프록시에 대한 설명. 예를 들면 My first MCP Discovery Proxy입니다.
다음을 클릭합니다.
OpenAPI 사양 섹션에서 파일 브라우저를 사용하여 이전 단계에서 만든 OpenAPI 3.0.x 파일을 선택합니다.
다음을 클릭합니다.
배포(선택사항) 섹션에서 지금은 프록시 배포를 건너뛸 수 있습니다. 다음을 클릭합니다.
만들기를 클릭합니다.
참고: 프록시가 생성되는 데 최대 10분이 걸릴 수 있습니다. 작업이 완료되면 프록시 요약 세부정보 페이지로 이동하며, 여기에서 프록시 요약 세부정보 페이지에 MCP 검색 프록시가 표시됩니다.

수정사항 표의 엔드포인트 요약 열에서 보기를 클릭하여 프록시의 타겟 및 서버 엔드포인트를 확인할 수 있습니다. 선택한 프록시 버전의 버전 엔드포인트 요약에는 다음 정보가 표시됩니다.

프록시 엔드포인트: 이 예시에서는 기본 경로가 /mcp인 default 프록시 엔드포인트가 표시됩니다. 프록시에 추가 호스트 이름이나 환경 그룹이 추가되면 여기에도 표시됩니다.
대상 엔드포인트: 이 예시에서는 default 대상 연결이 mcp.apigee.internal/mcp로 설정됩니다.

(선택사항) MCP 검색 프록시에 정책 추가

이 단계에서는 MCP 검색 프록시에 Google 인증을 추가합니다. Google 인증 정책을 추가하면 MCP 검색 프록시에 대한 모든 요청이 인증되고 승인됩니다.

토큰 확인을 구성하려면 API 프록시 흐름의 시작 부분(ProxyEndpoint Preflow의 시작)에 VerifyAccessToken 작업이 포함된 OAuthV2 정책을 배치합니다. 여기에 배치하면 다른 토큰이 실행되기 전에 액세스 토큰이 확인됩니다. 토큰이 거부되면 Apigee가 처리를 중지하고 오류를 클라이언트에 반환합니다.

VerifyAccessToken 정책을 추가하려면 다음 단계를 따르세요.

프록시 세부정보 페이지에서 개발 탭을 클릭합니다.
프록시 엔드포인트에서 기본값을 클릭한 다음 PreFlow를 클릭합니다.
프록시 흐름 편집기에서 정책 단계 추가를 클릭합니다.
정책 단계 추가 대화상자에서 새 정책 만들기를 선택합니다.
정책 목록의 보안에서 OAuth v2.0을 선택합니다.
선택적으로 정책 이름 및 표시 이름을 변경합니다. 예를 들어 가독성을 높이기 위해 표시 이름 및 이름을 모두 VerifyAccessToken으로 변경할 수 있습니다.
추가를 클릭합니다.

MCP 검색 프록시 배포

MCP 탐색 프록시를 배포하려면 다음 단계를 따르세요.

배포를 클릭하여 API 프록시 배포 창을 엽니다.
버전 필드가 1로 설정되어 있어야 합니다. 그렇지 않은 경우 1을 클릭하여 선택합니다.
환경 목록에서 프록시를 배포할 환경을 선택합니다. 환경은 종합 환경이어야 합니다.
이전 단계에서 만든 서비스 계정을 입력합니다.
배포를 클릭합니다.

API 프록시의 XML 구성이 개발 탭에 표시됩니다.

(선택사항) API 제품 만들기

이 단계에서는 개발자 또는 에이전트에게 노출할 프록시의 작업과 엔드포인트를 번들로 묶는 API 제품을 만듭니다. 이 단계는 선택사항입니다. MCP 엔드포인트에서 tools/list 메서드를 호출하는 데 인증이 필요하지 않은 경우 이 단계를 건너뛰고 MCP 서버 초기화로 이동하면 됩니다.

API 제품을 만들려면 다음 안내를 따르세요.

Google Cloud 콘솔에서 API 제품 페이지로 이동합니다.
API 제품으로 이동
add만들기를 클릭합니다. 제품 세부정보 페이지가 표시됩니다. 제품 세부정보 섹션에서 다음 세부정보를 입력합니다.
- 이름: API 제품의 이름. 예를 들면 MCP API product입니다.
- 표시 이름: API 제품의 표시 이름. 예를 들면 MCP product입니다.
- 설명: API 제품에 대한 설명. 예를 들면 API product for hostname cymbal.products.com입니다.
- 환경: MCP 검색 프록시를 배포한 환경. 예를 들면 default입니다.
- 액세스: 공개를 선택합니다.
- 할당량: 이 튜토리얼에서는 이 필드를 건너뛸 수 있습니다.
- 허용된 OAuth 범위: 작업을 쉼표로 구분된 목록으로 입력합니다. 이 튜토리얼에서는 artists.get, artists.post, artists.username.get을 입력합니다.
작업 섹션에서 + 작업 추가를 클릭하여 작업 창을 엽니다.
작업 창에서 다음을 수행합니다.
1. 프록시 목록에서 MCP 디스커버리 프록시를 찾아 선택합니다.
2. 작업 섹션에서 API 제품에 포함할 리소스 경로의 경로와 메서드를 입력합니다. 이 튜토리얼에서는:
  - 경로: /를 입력합니다.
  - 메서드: POST를 선택합니다.
3. 저장을 클릭합니다.

API 제품이 생성되면 제품 세부정보 페이지가 표시됩니다. 이제 API 제품을 개발자 포털에 게시하고 개발자와 에이전트가 사용할 수 있도록 할 수 있습니다.

(선택사항) 개발자 및 앱 만들기

이 단계에서는 Apigee 조직에서 개발자와 앱을 만들고 이러한 리소스를 사용하여 MCP 엔드포인트를 테스트합니다. 이 단계는 선택사항입니다. MCP 엔드포인트에서 tools/list 메서드를 호출하는 데 인증이 필요하지 않은 경우 이 단계를 건너뛰고 MCP 서버 초기화로 이동하면 됩니다.

테스트에 필요한 리소스를 설정하려면 다음 단계를 따르세요.

Google Cloud 콘솔에서 Apigee API 관리 페이지로 이동합니다.
Apigee API 관리
Kubernetes용 Apigee Operator를 설치한 Apigee 조직을 선택합니다.
개발자를 만듭니다.
1. 배포 > 개발자를 선택합니다.
2. 개발자 페이지에서 + 만들기를 클릭합니다.
3. 개발자 추가 페이지에서 원하는 값을 사용하여 필수 필드를 작성합니다.
4. 추가를 클릭합니다.
앱을 만듭니다.
1. 배포> 앱을 선택합니다.
2. 앱 페이지에서 + 만들기를 클릭합니다.
3. 앱 만들기 페이지의 앱 세부정보 섹션에서 다음 값을 사용하여 필수 필드를 작성합니다.
  - 앱 이름: mcp-test-app
  - 개발자: 이전 단계에서 만든 개발자 또는 목록에 있는 다른 개발자를 선택합니다.
4. 앱 사용자 인증 정보 섹션에서 + 사용자 인증 정보 추가를 클릭합니다.
5. 인증 정보 섹션에서 인증 정보 세부정보 섹션에 다음 값을 입력하여 필수 필드를 완료합니다.
  - 사용자 인증 정보 이름: demo-credential
  - 사용자 인증 정보 유형: API 키 선택
6. 만들기를 클릭합니다.
7. 제품 섹션에서 + 제품 추가를 클릭합니다.
8. 이전 단계에서 만든 api-product-1을 선택합니다.
9. 추가를 클릭합니다.
10. 만들기를 클릭합니다.
앱 세부정보 페이지의 사용자 인증 정보 섹션에서 를 클릭하여 키 값을 표시합니다.
Key 값을 복사합니다. 이 키는 이후 단계에서 서비스에 API를 호출하는 데 사용됩니다.
앱 세부정보 페이지의 사용자 인증 정보 섹션에서 를 클릭하여 앱 보안 비밀 값을 표시합니다.
앱 보안 비밀 값을 복사합니다. 이 값은 이후 단계에서 액세스 토큰을 생성하는 데 사용됩니다.

MCP 서버 초기화

이 단계에서는 MCP 엔드포인트에 요청을 보내 MCP 서버를 초기화하고 예상대로 작동하는지 확인합니다.

MCP 서버를 초기화하고 테스트하려면 MCP 엔드포인트에 다음 요청을 전송하세요.

curl -X POST "https://MCP_ENDPOINT_URL/mcp" \
  -H "Content-Type: application/json" \
  -d '{
        "jsonrpc": "2.0",
        "id": 1,
        "method": "initialize",
        "params": {}
      }' \
  -H "Authorization: Bearer TOKEN"

다음을 바꿉니다.

MCP_ENDPOINT_URL: MCP 엔드포인트 기본 URI. 예를 들면 cymbal.products.com입니다.
(선택사항) TOKEN: OAuth 2.0 액세스 토큰

성공적인 응답은 다음과 유사하게 표시됩니다.

{
"id":1,
"jsonrpc":"2.0",
"result":
  {
    "capabilities":
    {
      "tools":
      {
        "listChanged":false
      }
    },
    "protocolVersion":"2025-03-26",
    "serverInfo":
      {
        "name":"cymbal.products.com",
        "version":"1.0.0"
      }
    }
  }

API 제품에서 사용할 수 있는 MCP 도구 나열

이 단계에서는 tools/list 메서드에 요청을 전송하여 MCP 엔드포인트에서 사용할 수 있는 도구 목록을 확인합니다.

참고: API 제품 수준에서 tools/list 메서드의 인증을 제어할 수 있습니다. MCP 엔드포인트에 액세스하는 데 인증이 필요하지 않은 경우 MCP 검색 프록시가 API 제품에 포함되지 않아도 됩니다. 하지만 인증되지 않은 액세스를 메서드에 허용하면 조직에 보안 위험이 발생할 수 있습니다.

Apigee 프록시의 tools/list 메서드에 요청을 전송합니다.

curl -X POST "https://MCP_ENDPOINT_URL/mcp" \
  -H "Content-Type: application/json" \
  -d '{
        "jsonrpc": "2.0",
        "id": 1,
        "method": "tools/list",
        "params": {}
      }' \
  -H "Authorization: Bearer TOKEN"