Unla MCP — 사용 사례, 설치 & 라이브 데모

왜 쓰나요

핵심 기능

YAML을 통한 REST → MCP 변환, 래퍼 코드 불필요
기존 MCP 서비스를 단일 게이트웨이를 통해 프록시
핫 리로드 설정용 웹 UI
OAuth 사전 인증을 지원하는 멀티테넌트
SSE + Streamable HTTP 전송; 멀티 레플리카 지원

라이브 데모

실제 사용 모습

unla.replay ▶ 준비됨

0/0

설치

클라이언트 선택

~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "unla": {
      "command": "npx",
      "args": [
        "-y",
        "Unla"
      ],
      "_inferred": true
    }
  }
}

Claude Desktop → Settings → Developer → Edit Config 열기. 저장 후 앱 재시작.

~/.cursor/mcp.json · .cursor/mcp.json

{
  "mcpServers": {
    "unla": {
      "command": "npx",
      "args": [
        "-y",
        "Unla"
      ],
      "_inferred": true
    }
  }
}

Cursor는 Claude Desktop과 동일한 mcpServers 스키마 사용. 프로젝트 설정이 전역보다 우선.

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "unla": {
      "command": "npx",
      "args": [
        "-y",
        "Unla"
      ],
      "_inferred": true
    }
  }
}

Cline 사이드바의 MCP Servers 아이콘 클릭 후 "Edit Configuration" 선택.

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "unla": {
      "command": "npx",
      "args": [
        "-y",
        "Unla"
      ],
      "_inferred": true
    }
  }
}

Claude Desktop과 같은 형식. Windsurf 재시작 후 적용.

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "unla",
      "command": "npx",
      "args": [
        "-y",
        "Unla"
      ]
    }
  ]
}

Continue는 맵이 아닌 서버 오브젝트 배열 사용.

~/.config/zed/settings.json

{
  "context_servers": {
    "unla": {
      "command": {
        "path": "npx",
        "args": [
          "-y",
          "Unla"
        ]
      }
    }
  }
}

context_servers에 추가. 저장 시 Zed가 핫 리로드.

claude mcp add unla -- npx -y Unla

한 줄 명령. claude mcp list로 확인, claude mcp remove로 제거.

사용 사례

실전 활용법: Unla

서버를 작성하지 않고 내부 REST API를 MCP로 노출하는 방법

👤 플랫폼 엔지니어, 내부 도구 팀 ⏱ ~30 min intermediate

언제 쓸까: 회사 REST API가 있고 맞춤형 MCP를 구축하지 않고 Claude/Cursor가 사용하도록 하고 싶을 때

사전 조건

Docker — docker.com/get-started
API용 OpenAPI/Swagger 사양(선택 사항이지만 도움이 됨) — 대부분의 내부 API는 이미 이 사양을 가지고 있습니다

흐름

Unla 배포

docker run -d --name unla -p 8080:80 -p 5234:5234 -p 5235:5235 ghcr.io/amoylab/unla/allinone:latest✓ 복사됨

→ :8080의 웹 UI
YAML 서버 정의 추가

UI에서 'internal-api' 서버를 만들고 엔드포인트 /users(GET), /orders(GET, POST)를 https://api.internal/v1에 매핑합니다.✓ 복사됨

→ 도구 표시: get_users, get_orders, create_order
클라이언트가 이를 가리키도록 설정

Claude Desktop에 https://gateway.internal/mcp/internal-api를 추가합니다.✓ 복사됨

→ 클라이언트에 새 도구가 나타남

결과: 1시간 이내에 모든 MCP 클라이언트에서 내부 API를 사용할 수 있습니다.

함정

제한 없이 민감한 헤더를 매핑하면 인증이 누출됨 — Unla의 OAuth 사전 인증을 사용하여 사용자별로 제어하세요. YAML에 관리자 토큰을 하드코딩하면 안 됩니다
쓰기 엔드포인트가 파괴적인 호출을 노출함 — POST/DELETE 엔드포인트를 'confirm'으로 표시하여 명시적 사용자 승인을 요청하세요

함께 쓰기: mcphub

각 고객에게 자신의 MCP 네임스페이스를 제공하는 방법

👤 고객에게 MCP 액세스를 제공하는 SaaS 팀 ⏱ ~45 min advanced

언제 쓸까: 플랫폼을 운영하고 테넌트별 도구 격리를 원할 때

흐름

Unla에서 테넌트 생성

관리자에서 'acme'와 'globex' 테넌트를 만들고 각각 자신의 API 키 매핑을 설정합니다.✓ 복사됨

→ 두 개의 격리된 네임스페이스
테넌트별 라우팅

Acme 사용자는 /mcp/acme를 호출하고, globex는 /mcp/globex를 호출합니다.✓ 복사됨

→ 도구에 테넌트 범위의 데이터 표시

결과: 여러 게이트웨이를 실행하지 않고도 멀티테넌트 MCP를 구현합니다.

함정

공유 YAML 템플릿을 통한 테넌트 간 유출 — 테넌트 범위의 변수를 사용하고, 테넌트 간에 해결되는 $ENV 참조를 사용하면 안 됩니다

기존 MCP를 단일 인증 URL 뒤에 배치하는 방법

👤 분산된 MCP 배포를 가진 팀 ⏱ ~20 min intermediate

언제 쓸까: 다양한 장소에 여러 stdio MCP가 있고 OAuth가 있는 공개 URL 하나를 원할 때

흐름

각 다운스트림 MCP 등록

Unla에서 github-mcp(stdio)와 postgres-mcp(HTTP)를 프록시 서버로 추가합니다.✓ 복사됨

→ 둘 다 정상으로 표시
OAuth 활성화

게이트웨이에 대해 GitHub OAuth를 활성화합니다.✓ 복사됨

→ 로그인 흐름이 종단 간 작동

결과: 하나의 엔드포인트, 하나의 로그인, 모든 MCP.

조합

다른 MCP와 조합해 10배 효율

unla + mcphub

Unla을 REST-to-MCP 변환용으로, MCPHub를 라우팅/그룹화용으로 사용

Unla에서 노출된 도구를 MCPHub에 'internal' 그룹 아래에 등록합니다.✓ 복사됨

unla + proxy

mcp-proxy를 마지막 마일 stdio 브리지로, Unla을 공개 게이트웨이로 사용

mcp-proxy로 로컬 stdio MCP를 HTTP로 브리징한 다음 Unla에 등록합니다.✓ 복사됨

도구

이 MCP가 노출하는 것

도구	입력	언제 호출	비용
(gateway) yaml-defined REST tools	YAML에 선언된 대로	노출된 REST 엔드포인트가 수행하는 모든 작업	업스트림 API에 대한 1개의 요청
(gateway) proxied MCP tools	통과	다운스트림과 동일	다운스트림 MCP와 동일

비용 및 제한

운영 비용

API 쿼터: 게이트웨이 계층에서 제한 없음; 업스트림 API 할당량은 여전히 적용됨
호출당 토큰: 최소한의 게이트웨이 오버헤드
금액: 무료(Apache 2.0)
팁: 중복 업스트림 청구를 피하려면 게이트웨이에서 GET 엔드포인트를 캐시하세요.

보안

권한, 시크릿, 파급범위

최소 스코프: OAuth 발급자 설정 + 테넌트 범위의 API 키

자격 증명 저장: 디스크의 게이트웨이 설정(보안 관리자를 통해 암호화); DB를 통한 테넌트 토큰

데이터 외부 송신: 게이트웨이는 사용자가 설정한 모든 업스트림 URL로 전달합니다

절대 부여 금지: 인증 없이 관리자 UI를 공개하지 마세요 git에 프로덕션 토큰을 YAML로 인코딩하지 마세요

YAML 포함은 환경 변수를 해결할 수 있습니다 — 컨테이너에서 환경 변수가 어디에서 오는지 주의하세요.

문제 해결

자주 발생하는 오류와 해결

모든 호출에서 업스트림 401 오류

게이트웨이가 인증 헤더를 전달하지 않습니다. YAML에 Authorization 매핑 규칙을 추가하세요.

확인: curl gateway with -v; check upstream headers

핫 리로드가 YAML 변경 사항을 반영하지 않음

먼저 UI의 Lint 탭에서 YAML을 확인하세요. 핫 리로드는 잘못된 설정을 자동으로 거부합니다.

OAuth redirect_uri 불일치

OAuth 공급자에 정확한 게이트웨이 URL을 등록하세요.

SSE가 60초 후 연결 해제

로드 밸런서 유휴 시간 제한. 3600초로 올리거나 Streamable HTTP를 사용하세요.

대안

Unla 다른 것과 비교

대안	언제 쓰나	단점/장점
MCPHub	TypeScript 허브와 스마트 벡터 라우팅을 원할 때	REST-to-MCP 변환에 덜 초점을 맞춤
ToolHive	컨테이너화된 MCP별 격리를 원할 때	REST-to-MCP 변환기가 아님

Unla