MCP 시작하기

Alpacon MCP 서버는 두 가지 방식으로 연결할 수 있습니다: 설치가 필요 없는 호스팅 서버, 또는 직접 실행하는 로컬 서버입니다. 이 가이드는 두 방식을 모두 다루고, 이어서 로컬 서버 설치, API 토큰 설정, AI 클라이언트 연결 과정을 안내합니다.

호스팅 vs 로컬

Alpacon은 https://mcp.alpacon.io/mcp에서 관리형 MCP 서버를 제공합니다(streamable HTTP 전송 방식 사용). AI 클라이언트를 이 URL로 연결하고 브라우저로 로그인하기만 하면 됩니다. 설치도 API 토큰도 필요 없습니다.

Alpacon 웹 콘솔의 “Connect your AI agent” 대화상자에서는 Cursor와 VS Code에 대한 원클릭 설치 버튼도 제공합니다.

호스팅 서버를 사용하는 이유:

  • 설치 불필요: uvx, Python, 로컬 프로세스 실행이 모두 필요 없습니다
  • API 토큰 불필요: 토큰을 설정 파일에 붙여넣는 대신 브라우저(OAuth)로 인증합니다
  • 리전·워크스페이스 설정 불필요: 접근 가능한 워크스페이스는 로그인 계정에서 결정되므로, 사용할 워크스페이스는 프롬프트에서 지정하면 됩니다(예: “production 워크스페이스에서 서버 목록을 보여줘”)
  • 항상 최신 상태: 별도 업그레이드 없이 최신 도구를 사용합니다

인증 동작 방식

클라이언트가 처음 연결하면 브라우저 창이 열려 Alpacon 로그인을 진행합니다. 로그인하면 클라이언트는 단기 토큰을 발급받아 모든 요청에 사용하며, Alpacon 웹 콘솔과 동일한 계정 권한(RBAC)과 감사 기록이 적용됩니다. 세션에 MFA 재인증이 필요한 경우(예: MFA 타임아웃) 클라이언트가 자동으로 브라우저를 다시 열어 인증을 완료합니다.

접근 권한이 로그인 계정에서 결정되므로 클라이언트 설정에 리전, 워크스페이스, API 토큰을 지정하지 않습니다. 대신 프롬프트에서 워크스페이스 이름을 지정하면(예: “production 워크스페이스에서”) 리전은 인증된 워크스페이스 정보를 바탕으로 자동으로 결정됩니다.

각 클라이언트별 정확한 설정은 아래 클라이언트 연결에서 확인하세요.

사전 준비

아래 사전 준비 사항과 단계는 로컬 서버를 직접 실행할 때 필요합니다. 설치 없이 연결하려면 위의 호스팅 서버 섹션을 참고하세요.

  • Python 3.12 이상

  • uv: 서버를 별도 설치 없이 실행할 수 있게 해주는 uvx 명령어를 제공합니다.

    curl -LsSf https://astral.sh/uv/install.sh | sh

  • Alpacon 워크스페이스와 API 토큰. 워크스페이스에 로그인해 사이드바의 API Token 메뉴에서 토큰을 생성하세요. 명령 실행과 파일 전송 도구를 쓰려면 해당 토큰에 ACL 권한도 설정해야 합니다.

빠른 시작

설정 마법사 실행

uvx alpacon-mcp

토큰이 아직 설정되어 있지 않으면 바로 대화형 설정 마법사로 진입합니다. 마법사는 다음을 순서대로 묻습니다.

  1. 리전 (기본값: ap1)
  2. 워크스페이스 이름
  3. API 토큰 (입력 시 화면에 표시되지 않음)

입력이 끝나면 설정을 저장하고 연결을 테스트한 뒤, 그대로 복사해 쓸 수 있는 MCP 클라이언트 설정을 출력합니다. 토큰이 이미 설정되어 있다면 같은 명령이 마법사 대신 서버를 바로 시작합니다.

마법사는 언제든 명시적으로 다시 실행할 수 있습니다.

uvx alpacon-mcp setup

클라이언트에 설정 추가

출력된 설정을 아래 클라이언트 연결을 참고해 MCP 클라이언트에 붙여넣은 뒤, 클라이언트를 재시작하거나 다시 연결하세요.

연결 확인

uvx alpacon-mcp test

리전과 워크스페이스를 입력받아 해당 토큰을 조회하고, API에 정상적으로 연결되는지 확인합니다.

그 외 설정 명령어

uvx alpacon-mcp                                # 서버 시작 (토큰이 없으면 설정 마법사 실행)
uvx alpacon-mcp setup                          # 대화형 설정 마법사 실행
uvx alpacon-mcp setup --local                  # 전역 위치 대신 ./config/token.json에 저장
uvx alpacon-mcp setup --token-file ~/my.json   # 사용자 지정 경로에 저장
uvx alpacon-mcp test                           # 특정 리전·워크스페이스의 연결 테스트
uvx alpacon-mcp list                           # 설정된 워크스페이스 전체 조회
uvx alpacon-mcp add                            # 기존 설정에 워크스페이스 추가

setup, test, list, add는 최상위 명령에 --config-file <path>를 붙여 해당 실행에서만 사용할 토큰 파일을 지정할 수도 있습니다.

토큰 설정

토큰은 리전, 워크스페이스 순으로 중첩된 JSON으로 저장됩니다.

{
  "ap1": {
    "production": "alpat-xxxxxxxxxxxxxxxxxx",
    "staging": "alpat-xxxxxxxxxxxxxxxxxx"
  }
}

기본 위치: ~/.alpacon-mcp/token.json (전역 파일이 없으면 ./config/token.json으로 대체).

서버가 토큰을 찾는 탐색 순서는 다음과 같습니다.

  1. ALPACON_MCP_CONFIG_FILE 환경 변수가 설정되어 있으면 해당 파일
  2. 전역 설정 파일 (존재하는 경우)
  3. 로컬 설정 파일 (./config/token.json)

ALPACON_MCP_<REGION>_<WORKSPACE>_TOKEN 형태의 환경 변수(예: ALPACON_MCP_AP1_PRODUCTION_TOKEN)로 리전·워크스페이스별 토큰을 개별 지정할 수도 있습니다. 환경 변수가 토큰 파일보다 우선합니다.

클라이언트 연결

각 클라이언트는 호스팅 서버(remote)에 연결하거나 로컬 uvx alpacon-mcp 프로세스에 연결할 수 있습니다. 클라이언트를 선택하세요.

Remote (호스팅)

claude mcp add --transport http alpacon https://mcp.alpacon.io/mcp

처음 사용할 때 Claude Code가 브라우저를 열어 로그인을 진행합니다. claude mcp list로 연결을 확인하세요.

Local

CLI로 서버를 추가합니다.

claude mcp add alpacon -- uvx alpacon-mcp

또는 Claude Desktop과 같은 JSON을 프로젝트의 .mcp.json에 추가해도 됩니다. claude mcp list로 확인하세요.

전송 방식

uvx alpacon-mcp는 위 클라이언트들이 기본으로 사용하는 stdio 전송 방식으로 동작합니다. 배포 형태가 다르면 다음 두 전송 방식도 선택할 수 있습니다.

  • SSE (alpacon-mcp-sse 콘솔 스크립트): HTTP 기반 Server-Sent Events 방식으로, 프로세스를 직접 실행하는 대신 HTTP 엔드포인트가 필요한 로컬 네트워크 연동에 적합합니다.
  • Streamable HTTP (alpacon-mcp-http 콘솔 스크립트): 위에서 설명한 호스팅 서버가 사용하는 전송 방식입니다. 정적 토큰 파일 대신 Auth0(OAuth)로 호출자를 인증하므로, 클라이언트는 API 토큰을 로컬에 저장하는 대신 브라우저로 로그인합니다.

대부분의 개인 사용자는 위의 기본 stdio 설정만으로 충분하며, 나머지 전송 방식은 조직이 공유 MCP 엔드포인트를 직접 운영할 때 주로 필요합니다.

첫 시도

클라이언트 연결이 끝났다면 다음과 같이 물어보세요.

  • “내 서버 목록을 보여줘”
  • “web-01의 최근 24시간 CPU 사용량을 보여줘”
  • “지금 나는 어떤 계정으로 로그인되어 있어?”

에이전트가 할 수 있는 전체 작업은 카테고리별로 정리된 도구에서 확인할 수 있습니다.

최종 수정: