MCP 문서 관리

메뉴

홈
문서 목록
관리자 로그인

문서 정보

최종 수정일:
2025-05-13 10:54
태그:
#MCP #써드파티 #API #문서화 #개발

OpenAPI

OpenAPI

OpenAPI MCP 서버는 OpenAPI 명세를 MCP 리소스 및 도구로 변환하여 AI 에이전트가 복잡한 API 문서를 쉽게 탐색하고 이해할 수 있게 도와주는 서비스입니다. 이 서버는 대규모 언어 모델(LLM)이 자연어를 통해 REST API와 상호작용할 수 있게 하여 API 개발 및 사용 경험을 크게 향상시킵니다.

특징

  • OpenAPI 명세 변환: OpenAPI(예전의 Swagger) 명세를 MCP 리소스로 변환하여 AI 에이전트가 접근 가능하게 함
  • 시맨틱 검색: 자연어 쿼리를 사용하여 관련 API 엔드포인트를 쉽게 발견할 수 있는 기능
  • 단순 언어 요약: 복잡한 API 구조를 단순화된 언어로 요약하여 이해 용이성 향상
  • API 문맥 제공: API의 기능, 매개변수, 응답 형식에 대한 상세한 문맥 정보 제공
  • 코드 생성 지원: API 상호작용을 위한 코드 생성 용이
  • 유연한 구성: 환경 변수를 통한 다양한 API 연결 및 인증 옵션 지원

API

리소스

  • API 명세: OpenAPI 명세에서 추출한 API 정보를 구조화된 형태로 제공
  • 엔드포인트 정보: 각 API 엔드포인트의 세부 정보(경로, 메소드, 매개변수, 응답 등)

도구

API 탐색 도구

  • discover_api: OpenAPI 명세를 검색하고 이해하는 데 사용됩니다.
  • 입력:
    • spec_url (문자열, 선택적): OpenAPI 명세 URL 또는 파일 경로
    • api_name (문자열, 선택적): 검색할 API 이름

  • 출력:

    • API 개요, 사용 가능한 엔드포인트 목록 등 일반적인 API 정보

  • summarize_api: API의 간략한 요약을 생성합니다.

  • 입력:
    • spec_url (문자열): OpenAPI 명세 URL 또는 파일 경로
  • 출력:
    • API의 주요 기능, 리소스, 작업 등에 대한 단순화된 요약

엔드포인트 분석 도구

  • analyze_endpoint: 특정 API 엔드포인트를 자세히 분석합니다.
  • 입력:
    • path (문자열): 엔드포인트 경로(예: '/users/{id}')
    • method (문자열): HTTP 메소드(예: 'GET', 'POST')
    • spec_url (문자열, 선택적): OpenAPI 명세 URL 또는 파일 경로

  • 출력:

    • 엔드포인트 설명, 매개변수 세부 정보, 응답 형식, 예시 등

  • translate_complex_api: 복잡한 API 구조를 단순한 언어로 변환합니다.

  • 입력:
    • endpoint_path (문자열): 분석할 엔드포인트 경로
    • spec_url (문자열, 선택적): OpenAPI 명세 URL 또는 파일 경로
  • 출력:
    • 단순화된 API 설명 및 사용 방법

지원되는 기능

OpenAPI MCP 서버는 현재 다음과 같은 기능을 지원합니다:

  1. API 탐색 및 이해: OpenAPI 명세의 본적을 파악하고 전체 API 구조를 이해할 수 있습니다.

  2. 엔드포인트 세부 정보: 특정 엔드포인트에 대한 상세 정보(파라미터, 응답 형식, 인증 요구 사항 등)를 제공합니다.

  3. 단순 언어 요약(SLOP): 복잡한 API 구조를 간결하고 이해하기 쉬운 언어로 요약합니다.

  4. 코드 생성 지원: API 호출을 위한 코드 예제 생성을 지원합니다.

참고: OpenAPI MCP 서버 v2는 현재 API 탐색 및 문맥 제공에 중점을 두고 있으며, 인증 문제로 인해 엔드포인트를 직접 실행하는 기능은 제공하지 않습니다.

사용 방법

OpenAPI MCP 서버를 사용하려면:

  1. MCP 서버 설치: 

    # NPX를 통한 직접 실행
npx @ivotoby/openapi-mcp-server

# 또는 Smithery를 통한 설치
npx -y @smithery/cli install @ivotoby/openapi-mcp-server --client claude

  2. Claude Desktop 구성: 

    {
  "mcpServers": {
    "openapi": {
      "command": "npx",
      "args": ["-y", "@ivotoby/openapi-mcp-server"],
      "env": {
        "API_BASE_URL": "https://api.example.com",
        "OPENAPI_SPEC_PATH": "https://api.example.com/openapi.json",
        "API_HEADERS": "Authorization:Bearer token123,X-API-Key:your-api-key"
      }
    }
  }
}

  3. 환경 변수 설명:

  4. API_BASE_URL: API의 기본 URL
  5. OPENAPI_SPEC_PATH: OpenAPI 명세의 URL 또는 파일 경로

  6. API_HEADERS: API 호출에 사용할 헤더(쉼표로 구분된 키:값 쌍)

  7. 검사 모드 실행(디버깅용): 

    npm run inspect -- \
  --api-base-url https://api.example.com \
  --openapi-spec https://api.example.com/openapi.json \
  --headers "Authorization:Bearer token123,X-API-Key:your-api-key" \
  --name "my-mcp-server" \
  --version "1.0.0"

자동 생성된 MCP 서버

여러 도구들이 OpenAPI 명세에서 MCP 서버를 자동으로 생성하는 기능을 제공합니다:

  1. Stainless: OpenAPI 명세에서 MCP 서버를 자동으로 생성하고 npm 패키지로 게시합니다. Stainless 프로젝트 대시보드에서 "Add SDKs" > "MCP Server"를 선택하여 설정할 수 있습니다.

  2. Mintlify: 문서에서 직접 MCP 서버를 생성하여 AI 애플리케이션이 API 문서와 상호작용할 수 있게 합니다. 간단한 CLI 설치를 통해 설정 가능합니다.

  3. Speakeasy: OpenAPI/Swagger 명세에서 MCP 서버를 생성하는 기능을 제공합니다.

MCP-to-OpenAPI 프록시

Open WebUI에서 제공하는 MCP-to-OpenAPI 프록시 서버(mcpo)를 통해 MCP 도구 서버를 표준 REST/OpenAPI API로 노출할 수 있습니다:

  1. 프록시 서버 실행: 

    uvx mcpo --port 8000 -- uvx mcp-server-time --local-timezone=America/New_York

  2. 특징:

  3. MCP 도구를 동적으로 발견하고 REST 엔드포인트 생성
  4. 인터랙티브 OpenAPI 문서 생성(http://localhost:8000/docs에서 접근 가능)
  5. HTTP 클라이언트, AI 에이전트 또는 다른 OpenAPI 도구를 통해 자동 생성된 API 엔드포인트에 직접 호출 가능

사용 사례

OpenAPI MCP 서버는 다음과 같은 시나리오에서 특히 유용합니다:

  1. 실시간 API 가이드: 사용자가 AI에게 특정 작업을 수행하는 방법을 물으면 AI는 정확한 API 참조를 문서에서 가져올 수 있습니다.

  2. AI 지원 API 호출: 단순히 엔드포인트를 보여주는 대신 AI 애플리케이션이 바로 사용할 수 있는 API 요청을 생성할 수 있습니다.

  3. 워크플로우에 API 실행 통합: 적절한 인증을 통해 AI 애플리케이션이 실제로 작업을 실행할 수 있습니다(예: Stripe 환불 시작 또는 실시간 데이터 검색).

  4. 복잡한 API 간소화: 개발자나 일반 사용자가 복잡한 API 구조를 이해하고 활용하는 데 도움을 줍니다.

  5. 코드 생성: 특정 API 호출을 위한 코드 템플릿을 자동으로 생성하여 개발 속도를 높입니다.

보안 고려사항

OpenAPI MCP 서버를 사용할 때 다음과 같은 보안 고려사항에 주의해야 합니다:

  1. 도구 설명 검증: OpenAPI 명세에서 MCP로 변환하는 과정에서 도구 설명이나 파라미터 설명이 악의적인 지시로 오염될 수 있으므로 API 거버넌스 워크플로우 중에 검토 및 검사가 필요합니다.

  2. 인증 관리: API 키나 토큰과 같은 인증 정보는 안전하게 관리하고, 필요한 경우에만 제한된 권한으로 제공해야 합니다.

  3. API 접근 제한: 필요한 엔드포인트만 노출하여 불필요한 보안 위험을 줄이세요. Stainless와 같은 도구에서는 enable_all_resources: false를 설정하고 특정 리소스나 엔드포인트만 mcp: true로 지정할 수 있습니다.

연결된 구성 요소

  • GitHub - API 문서와 함께 사용하여 개발 워크플로우 향상
  • Pandoc - API 문서를 다양한 형식으로 변환하는 데 활용 가능