Speakeasy OpenAPI Generator 오픈소스화: API 하나로 SDK·CLI·MCP 서버 만들기

2026년 09월 20일

dorian

OpenAPI 문서에서 SDK, CLI, MCP 서버를 생성하는 Speakeasy 도구

Google과 Speakeasy가 2026년 9월 17일 OpenAPI 코드 생성 도구를 공개했습니다. 공개된 openapi-generation 저장소는 OpenAPI 문서에서 여러 언어의 SDK, CLI 애플리케이션, MCP 서버, Postman 컬렉션, Terraform provider를 만드는 Go 기반 generator입니다.

API를 운영하면서 Python과 TypeScript SDK를 따로 관리하거나, 코딩 에이전트가 쓸 CLI와 MCP 서버까지 직접 만들고 있다면 살펴볼 만합니다. 하나의 OpenAPI 문서를 여러 개발자 인터페이스로 바꾸는 과정이 공개 저장소와 재현 가능한 생성 단계 안으로 들어왔기 때문입니다.

무엇이 공개됐나

Google 발표에 따르면 SDK generator는 Python, TypeScript, Go, Java, C#, PHP, Ruby 등 7개 언어를 지원합니다. 생성한 라이브러리에는 static typing, Server-Sent Events(SSE) streaming, retry, pagination 처리가 포함됩니다.

저장소가 지원하는 primary target은 모두 12개입니다. C#, Go, Java, MCP TypeScript, PHP, Python, Ruby, TypeScript, Unity SDK와 CLI, Postman collection, Terraform provider가 여기에 들어갑니다. OpenAPI 3.0과 3.1을 지원하고 OpenAPI 3.2는 일부 construct만 처리하므로, 3.2 문서 전체를 바로 넣는 용도로는 아직 적합하지 않습니다.

생성 과정은 결정적입니다. OpenAPI 문서를 parse하고 validate한 뒤 SDK용 AST를 만들고 target별 template와 TypeScript helper를 불러와 결과물을 render·format·compile합니다. 모델이 매번 다른 코드를 작성하도록 맡기는 방식과 달리, 같은 specification과 설정으로 검토 가능한 결과를 반복 생성하려는 구조입니다.

개발자에게 필요한 변화

가장 실용적인 부분은 API 표면을 한 번 정의한 뒤 배포 채널을 늘릴 수 있다는 점입니다. 사용자에게는 언어별 SDK를 제공하고 운영자에게는 CLI를 주며 코딩 에이전트에는 문서 MCP 서버를 연결할 수 있습니다. Google은 이 도구로 Interactions, Agents, Webhooks API용 새 Google GenAI SDK를 만들었다고 밝혔습니다.

문서 MCP server generator는 OpenAPI specification과 Markdown 문서를 MCP server로 바꿉니다. 에이전트가 오래된 method 이름을 추측하는 대신 현재 schema와 문서를 조회하도록 만드는 용도입니다. CLI generator도 같은 API를 terminal에서 실행할 수 있는 독립 binary로 컴파일합니다.

빠르게 시작하는 방법

일반 사용자는 generator 저장소를 직접 build하기보다 Speakeasy CLI를 쓰는 편이 낫습니다. 저장소도 end-user SDK generation에는 CLI 사용을 안내합니다.

macOS에서는 Homebrew로 설치할 수 있습니다.

brew install speakeasy-api/tap/speakeasy

Linux와 macOS용 설치 script도 있지만 바로 pipe해서 실행하기 전에 내려받은 내용을 검토하는 편이 안전합니다. Windows에서는 winget install speakeasy 또는 choco install speakeasy를 사용할 수 있습니다.

설치한 뒤 interactive mode를 시작합니다.

speakeasy

인증이 필요하면 다음 명령을 사용합니다. browser에서 Speakeasy Platform workspace를 선택하거나 만들면 API key가 생성됩니다.

speakeasy auth login

CI/CD에서는 Speakeasy Platform에서 만든 API key를 SPEAKEASY_API_KEY 환경 변수로 전달합니다.

저장소 자체를 수정하거나 template 개발에 참여하려면 Go 1.26.2, Node.js와 npm, Docker, target별 toolchain이 필요합니다. 공식 저장소의 direct generation 예시는 다음 형태입니다.

go run ./cmd/generate/main.go \
  -s ./tests/specs/basic-http.yaml \
  -o /tmp/generated-sdk \
  -l go \
  --license agpl-3.0-only \
  --skip-compile

이 명령은 OpenAPI 문서를 읽어 Go SDK를 생성하되 compile은 건너뜁니다. 첫 실행은 output directory에 .speakeasy/gen.yaml을 만듭니다.

라이선스와 비용에서 확인할 부분

Generator 저장소는 AGPL-3.0입니다. Open Source 경로를 선택하면 생성 결과에도 AGPL-3.0-only가 적용되고 commercial license token을 쓰면 생성한 SDK를 별도 조건으로 사용·수정·배포할 수 있습니다. 따라서 회사 제품에 넣을 SDK를 만들 때는 generator의 공개 여부만 보고 판단하지 말고 생성 artifact에 적용할 license를 먼저 정해야 합니다.

Google 발표는 generator를 개발 또는 CI pipeline에서 실행하면서 생성 코드의 license를 선택할 수 있다고 설명합니다. 저장소의 현재 안내는 AGPL election과 commercial token을 명시적으로 구분합니다. 두 문서를 함께 읽고 조직의 배포 방식에 맞는 조건을 확인하는 편이 안전합니다.

Telemetry도 확인해야 합니다. Generator는 실행 환경에 따라 target, template, 성공 여부, OS와 architecture, version, configuration 및 feature flag를 기록할 수 있습니다. 문서 또는 configuration에서 파생한 server URL, contact, title, OpenAPI version, validation warning과 error가 포함될 수도 있습니다. 필요하면 실행 전에 다음 환경 변수로 끌 수 있습니다.

export SPEAKEASY_DISABLE_TELEMETRY=true

장점과 한계

장점은 SDK와 agent용 interface를 같은 OpenAPI 원본에서 만들고 generator와 template 구현을 직접 검토할 수 있다는 점입니다. 수정 사항을 CI에서 다시 생성하고 diff로 검토하기도 쉽습니다. 특히 여러 언어 SDK를 동시에 관리하거나 MCP server를 API 문서와 함께 갱신해야 하는 팀에 맞습니다.

대신 toolchain이 가볍지는 않습니다. 저장소 개발에는 Go, Node.js, Docker와 target별 runtime이 필요하고 OpenAPI 3.2 전체 문서는 아직 지원하지 않습니다. AGPL과 commercial license의 경계도 배포 전에 검토해야 합니다. Telemetry 기본 동작 역시 민감한 specification을 다루는 환경에서는 별도 확인이 필요합니다.

이 글의 실행 예시는 공식 문서와 저장소를 기준으로 정리했습니다. 이번 작성 과정에서는 전체 SDK 생성과 compile을 직접 실행하지 않았습니다.

어떤 개발자에게 맞나

여러 언어의 client SDK를 같은 API specification에서 관리하거나, CLI와 MCP server까지 함께 배포하려는 팀에 적합합니다. Generator template을 직접 고쳐 사내 규칙을 반영하려는 platform engineer에게도 선택지가 생겼습니다.

SDK 하나만 수작업으로 관리하고 배포 license 검토가 부담스럽다면 도입 비용이 더 클 수 있습니다. OpenAPI 문서의 품질이 낮은 프로젝트도 먼저 specification을 정리해야 합니다. 이 도구의 효율은 입력 문서가 얼마나 정확한지에 크게 좌우됩니다.

출처

확인일: 2026-09-20

태그: AI Coding · MCP · Web API