MCP로 AI 에이전트 연결하기

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 재인증이 필요한 경우(예: 추가 인증 유지 시간) 클라이언트가 자동으로 브라우저를 다시 열어 인증을 완료합니다.

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

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

사전 준비

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

  • Python 3.12 이상

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

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

  • Alpacon 워크스페이스와 토큰. 개인 API 토큰을 만들려면 왼쪽 사이드바 맨 아래의 계정 카드를 클릭하고 내 API 토큰을 선택하세요. 명령어 실행과 파일 전송에 필요한 권한은 서비스 토큰을 참고하세요.

새 개인 API 토큰에는 명령어 실행이나 파일 전송 범위를 부여할 수 없습니다. 해당 범위를 이미 가진 토큰은 작업 세션 없이 계속 사용할 수 있습니다. 자동화와 CI에는 서비스 토큰을 쓰세요.

빠른 시작

설정 마법사 실행

bash
uvx alpacon-mcp

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

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

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

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

bash
uvx alpacon-mcp setup

클라이언트에 설정 추가

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

연결 확인

bash
uvx alpacon-mcp test

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

그 외 설정 명령어

bash
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>를 붙여 해당 실행에서만 사용할 토큰 파일을 지정할 수도 있습니다.

클라이언트 연결

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

Remote (호스팅)

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

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

Local

CLI로 서버를 추가합니다.

bash
claude mcp add alpacon -- uvx alpacon-mcp

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

첫 시도

전송 방식, 토큰, 도구 묶음 옵션은 MCP 설정 참조를 확인하세요.

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

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

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

최종 수정: