OpenAPI MCP 서버

“OpenAPI” MCP 서버는 무엇을 하나요?

OpenAPI MCP 서버는 AI 어시스턴트(예: Claude, Cursor)가 oapis.org를 통해 OpenAPI 명세를 검색·탐색할 수 있도록 설계된 Model Context Protocol(MCP) 서버입니다. 이 서버는 브릿지 역할을 하며 AI 모델이 복잡한 API를 쉬운 언어로 포괄적으로 이해할 수 있게 지원합니다. 서버는 3단계 절차를 따릅니다: 필요한 OpenAPI 명세를 확인하고, 쉽게 이해할 수 있도록 요약하며, 엔드포인트와 그 활용법을 상세히 제공합니다. (인증 제한으로 인해) 직접 엔드포인트를 실행하지는 않지만, API 개요 제공, 코드 생성 지원, API 구조의 이해와 문서화가 필수적인 개발 워크플로우를 효과적으로 지원합니다.

프롬프트 목록

• 개요 프롬프트: OpenAPI 명세에 대한 요약과 이해를 요청합니다.
• 작업 상세 프롬프트: 특정 API 작업에 대한 상세 설명을 가져옵니다.
• 엔드포인트 식별 프롬프트: 쿼리를 바탕으로 관련 엔드포인트를 판별합니다.

리소스 목록

• OpenAPI 명세 개요: 전체 API 명세에 대한 요약을 제공합니다.
• API 작업 상세: 특정 엔드포인트와 그 파라미터에 대한 컨텍스트 정보를 제공합니다.
• 포맷 유연성: JSON과 YAML 형식의 API 명세를 모두 지원합니다.
• 호환성 리소스: Claude Desktop 및 Cursor와 테스트되어 원활한 컨텍스트 전달을 보장합니다.

도구 목록

• v2에서는 실행 가능한 도구가 노출되지 않습니다. 서버는 API에 대한 탐색 및 컨텍스트 제공에 집중하며, 엔드포인트를 도구로 직접 실행하지 않습니다.

MCP 서버 활용 사례

• API 문서 자동 생성: 복잡한 OpenAPI 명세로부터 사람이 읽을 수 있는 문서를 자동으로 생성하여 개발자가 API를 쉽게 이해할 수 있도록 지원합니다.
• API 코드 생성 지원: 엔드포인트 설명 및 사용법을 명확하게 제공하여 개발자의 클라이언트 코드 생성에 도움을 줍니다.
• API 탐색 및 발견: 사용 가능한 엔드포인트를 신속하게 파악 및 요약하여 팀 또는 AI 모델이 API의 기능을 쉽게 발견할 수 있게 합니다.
• AI 에이전트에 컨텍스트 제공: LLM이나 에이전트에 관련 API 컨텍스트를 제공하여 외부 API를 활용한 질문 응답이나 코드 작성 능력을 향상시킵니다.
• 온보딩 및 교육: 새로운 팀원 또는 AI 에이전트가 익숙하지 않은 API를 쉽게 학습할 수 있도록 간단한 요약과 작업별 안내를 제공합니다.

설치 방법

Windsurf

1. 시스템에 Node.js가 설치되어 있는지 확인하세요.
2. Windsurf 설정 파일을 엽니다.
3. 제공된 JSON 스니펫을 이용해 mcpServers 섹션에 OpenAPI MCP 서버를 추가하세요.
4. 설정을 저장하고 Windsurf를 재시작하세요.
5. MCP 서버 연결을 확인하세요.

설정 예시:

{
  "mcpServers": {
    "openapi-mcp": {
      "command": "npx",
      "args": ["@janwilmake/openapi-mcp-server@latest"],
      "env": {
        "OAS_API_KEY": "${OAS_API_KEY}"
      }
    }
  }
}

참고: 위와 같이 환경 변수를 사용해 API 키를 안전하게 관리하세요.

Claude

1. Node.js를 설치하세요.
2. Claude의 MCP 통합 설정에 접속하세요.
3. 아래와 같이 OpenAPI MCP 서버를 추가하세요.
4. 설정을 저장하고 Claude를 재시작하세요.
5. 서버가 MCP 리소스로 사용 가능한지 확인하세요.

설정 예시:

{
  "mcpServers": {
    "openapi-mcp": {
      "command": "npx",
      "args": ["@janwilmake/openapi-mcp-server@latest"],
      "env": {
        "OAS_API_KEY": "${OAS_API_KEY}"
      }
    }
  }
}

Cursor

1. Node.js가 설치되어 있는지 확인하세요.
2. Cursor의 설정 파일을 찾으세요.
3. mcpServers 아래 OpenAPI MCP 서버를 삽입하세요.
4. 저장 후 Cursor를 재시작하세요.
5. 샘플 OpenAPI 쿼리로 테스트하세요.

설정 예시:

{
  "mcpServers": {
    "openapi-mcp": {
      "command": "npx",
      "args": ["@janwilmake/openapi-mcp-server@latest"],
      "env": {
        "OAS_API_KEY": "${OAS_API_KEY}"
      }
    }
  }
}

Cline

1. Node.js가 설치되어 있지 않다면 설치하세요.
2. Cline 설정 파일을 수정하여 OpenAPI MCP를 추가하세요.
3. 아래 JSON 블록을 추가하세요.
4. 저장 후 Cline을 재시작하세요.
5. MCP 서버가 활성화되었는지 확인하세요.

설정 예시:

{
  "mcpServers": {
    "openapi-mcp": {
      "command": "npx",
      "args": ["@janwilmake/openapi-mcp-server@latest"],
      "env": {
        "OAS_API_KEY": "${OAS_API_KEY}"
      }
    }
  }
}

API 키 보안:
민감한 키는 환경 변수에 저장하고, 설정에서 env 속성을 통해 참조하세요.

플로우 내에서 MCP 사용 방법

FlowHunt에서 MCP 사용하기

FlowHunt 워크플로우에 MCP 서버를 통합하려면, 플로우에 MCP 컴포넌트를 추가하고 AI 에이전트에 연결하세요:

MCP 컴포넌트를 클릭해 설정 패널을 엽니다. 시스템 MCP 설정 섹션에서 아래 JSON 형식으로 MCP 서버 정보를 입력하세요:

{
  "openapi-mcp": {
    "transport": "streamable_http",
    "url": "https://yourmcpserver.example/pathtothemcp/url"
  }
}

설정이 완료되면, AI 에이전트는 MCP의 모든 기능과 역량을 도구로 사용할 수 있습니다. “openapi-mcp” 이름과 URL을 실제 MCP 서버 명과 주소로 교체하는 것을 잊지 마세요.

개요

의견

OpenAPI MCP 서버는 OpenAPI 명세에 대한 컨텍스트 및 탐색 도구 제공에 특화된 유용한 MCP입니다. 엔드포인트 실행이 불가한 점은 일부 고급 사용처에서는 한계일 수 있고, 샘플링/roots 지원은 문서화되어 있지 않습니다. 그러나 명확한 설치 안내, 견고한 코드베이스, 커뮤니티 내 활발한 사용 사례 덕분에 API 컨텍스트 및 코드 생성 지원이 필요한 개발자에게 강력한 솔루션입니다.

MCP 점수