OpenAPI 파일을 AI에 연결하기

Apidog MCP Server는 Swagger 또는 OpenAPI Specification(OAS) 파일을 직접 읽을 수 있으므로, AI 어시스턴트가 Apidog 프로젝트나 온라인 문서와 독립적으로 API 사양을 활용할 수 있습니다.

사전 요구 사항

MCP 클라이언트를 구성하기 전에 다음 항목이 준비되어 있는지 확인하십시오.

Node.js(버전 18 이상, 최신 LTS 버전 권장)

MCP 호환 IDE:

Cursor

VS Code + Cline plugin

기타 MCP 지원 편집기

Swagger/OpenAPI 파일(URL 또는 로컬 경로)

OpenAPI 파일 준비하기

다음 중 하나가 준비되어 있는지 확인하십시오.

원격 URL: 공개적으로 접근 가능한 OpenAPI 파일(예: https://petstore.swagger.io/v2/swagger.json)

로컬 파일 경로: 사용자 머신의 OpenAPI 파일(예: ~/data/petstore/swagger.json)

지원 형식: JSON 또는 YAML

구성 개요

OpenAPI 파일을 위한 기본 MCP 구성은 다음과 같습니다.

macOS / Linux

Windows

{
  "mcpServers": {
    "API specification": {
      "command": "npx",
      "args": [
        "-y",
        "apidog-mcp-server@latest",
        "--oas=<oas-url-or-path>"
      ]
    }
  }
}

<oas-url-or-path>를 다음 중 하나로 대체하십시오.

원격 URL(예: https://petstore.swagger.io/v2/swagger.json)

로컬 파일 경로(예: ~/data/petstore/swagger.json)

Cursor에서 MCP 구성하기

MCP 설정 열기

Cursor 편집기를 여십시오.

설정 아이콘(오른쪽 상단)을 클릭하십시오.

왼쪽 메뉴에서 MCP를 선택하십시오.

+ Add new global MCP server를 클릭하십시오.

구성 추가하기

열린 mcp.json 파일에 다음 구성을 추가하십시오. https://petstore.swagger.io/v2/swagger.json을 실제 OpenAPI 파일 경로 또는 URL로 대체하십시오.

macOS / Linux

Windows

{
  "mcpServers": {
    "API specification": {
      "command": "npx",
      "args": [
        "-y",
        "apidog-mcp-server@latest",
        "--oas=https://petstore.swagger.io/v2/swagger.json"
      ]
    }
  }
}

구성 확인하기

AI에게 다음과 같이 요청하여 연결을 테스트하십시오(Agent 모드에서).

Please fetch API documentation via MCP and tell me how many endpoints exist in the project

AI가 OpenAPI 파일에서 올바른 API 정보를 반환하면 연결이 성공한 것입니다.

중요 참고 사항

여러 OpenAPI 파일 사용하기

여러 OpenAPI 사양 파일을 사용하려면 구성 파일에 여러 MCP Server를 추가하고, 각각 다른 --oas 매개변수를 지정하십시오.

예:

{
  "mcpServers": {
    "Petstore API": {
      "command": "npx",
      "args": [
        "-y",
        "apidog-mcp-server@latest",
        "--oas=https://petstore.swagger.io/v2/swagger.json"
      ]
    },
    "Local API": {
      "command": "npx",
      "args": [
        "-y",
        "apidog-mcp-server@latest",
        "--oas=~/data/my-api/openapi.yaml"
      ]
    }
  }
}

파일 경로 및 URL 요구 사항

로컬 파일 경로: 경로가 올바르고 파일이 존재하는지 확인하십시오.

URL: 공개적으로 접근 가능하며 유효한 OpenAPI 사양 파일을 반환하는지 확인하십시오.

성능 고려 사항

OpenAPI 파일이 크거나 복잡한 데이터 구조를 포함하는 경우, MCP 서버가 이를 처리하는 데 더 오래 걸릴 수 있습니다.

온프레미스 배포

온프레미스 배포의 경우 IDE MCP 구성에 서버의 API 주소를 포함하십시오.

{
  "mcpServers": {
    "API specification": {
      "command": "npx",
      "args": [
        "-y",
        "apidog-mcp-server@latest",
        "--oas=<oas-url-or-path>",
        "--apidog-api-base-url=<your-server-url>"
      ]
    }
  }
}

<your-server-url>을 온프레미스 서버의 API 주소(http:// 또는 https://로 시작)로 대체하십시오. www.npmjs.com에 대한 네트워크 접근이 가능한지 확인하십시오.

기타 데이터 소스

Apidog 프로젝트 내 API 사양을 AI에 연결하기

Apidog에서 게시한 온라인 API 문서를 AI에 연결하기

FAQ

Windows 구성 문제

Windows에서 표준 구성이 실패하는 경우 다음 대체 구성을 사용하십시오.

{
  "mcpServers": {
    "API specification": {
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "-y",
        "apidog-mcp-server@latest",
        "--oas=<oas-url-or-path>"
      ]
    }
  }
}

Node.js 버전 문제

OpenAPI 파일을 AI에 연결하기

사전 요구 사항#

OpenAPI 파일 준비하기#

구성 개요#

Cursor에서 MCP 구성하기#

중요 참고 사항#

여러 OpenAPI 파일 사용하기#

파일 경로 및 URL 요구 사항#

성능 고려 사항#

온프레미스 배포#

기타 데이터 소스#

FAQ#