---
title: "MCP로 AI 에이전트 연결하기"
description: "호스팅 또는 로컬 MCP 서버를 통해 AI 클라이언트를 Alpacon에 연결하세요. 인증 방식을 선택하고 클라이언트를 설정한 뒤 연결 상태를 확인합니다. 첫 작업을 실행하는 방법과 선택할 수 있는 설정의 위치, 인증 오류를 해결하는 방법까지 실제 예시와 함께 안내합니다."
---

> Full documentation index: https://docs.alpacax.com/llms.ko.txt

# MCP로 AI 에이전트 연결하기

<span id="mcp-시작하기" />

# 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](https://docs.astral.sh/uv/)**: 서버를 별도 설치 없이 실행할 수 있게 해주는 `uvx` 명령어를 제공합니다.

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

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

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

## 빠른 시작

### 설정 마법사 실행

```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`로 확인하세요.
  
  
    **Remote (호스팅)**

    **설정 → 커넥터 → 커스텀 커넥터 추가**에서 URL `https://mcp.alpacon.io/mcp`로 커스텀 커넥터를 추가하세요.

    로컬 서버만 지원하는 클라이언트라면 `claude_desktop_config.json`에 `mcp-remote` 브리지를 사용하세요.

    ```json
    {
      "mcpServers": {
        "alpacon": {
          "command": "npx",
          "args": ["-y", "mcp-remote", "https://mcp.alpacon.io/mcp"]
        }
      }
    }
    ```

    **Local**

    설정 파일을 엽니다.
    - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
    - Windows: `%APPDATA%\Claude\claude_desktop_config.json`

    ```json
    {
      "mcpServers": {
        "alpacon": {
          "command": "uvx",
          "args": ["alpacon-mcp"]
        }
      }
    }
    ```
  
  
    **Remote (호스팅)**

    `~/.cursor/mcp.json`을 만듭니다:

    ```json
    {
      "mcpServers": {
        "alpacon": {
          "url": "https://mcp.alpacon.io/mcp"
        }
      }
    }
    ```

    **Local**

    `~/.cursor/mcp.json`을 만듭니다:

    ```json
    {
      "mcpServers": {
        "alpacon": {
          "command": "uvx",
          "args": ["alpacon-mcp"]
        }
      }
    }
    ```
  
  
    **Remote (호스팅)**

    `.vscode/mcp.json`을 생성합니다.

    ```json
    {
      "servers": {
        "alpacon": {
          "type": "http",
          "url": "https://mcp.alpacon.io/mcp"
        }
      }
    }
    ```

    **Local**

    MCP 확장을 설치한 뒤 `.vscode/mcp.json`을 생성합니다.

    ```json
    {
      "servers": {
        "alpacon": {
          "command": "uvx",
          "args": ["alpacon-mcp"]
        }
      }
    }
    ```
  
  
    **Remote (호스팅)**

    원격(remote) 또는 streamable HTTP 서버를 지원하는 모든 MCP 클라이언트는 이 URL로 연결할 수 있습니다.

    ```
    https://mcp.alpacon.io/mcp
    ```

    **Local**

    stdio 전송 방식을 지원하는 MCP 클라이언트라면 다음 설정으로 서버를 직접 실행할 수 있습니다.

    ```json
    {
      "mcpServers": {
        "alpacon": {
          "command": "uvx",
          "args": ["alpacon-mcp"]
        }
      }
    }
    ```
  

## 첫 시도

<span id="토큰-설정" />
<span id="전송-방식" />
<span id="도구-묶음-선택" />

전송 방식, 토큰, 도구 묶음 옵션은 [MCP 설정 참조](/reference/mcp/configuration/)를 확인하세요.

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

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

에이전트가 할 수 있는 전체 작업은 카테고리별로 정리된 [도구](/reference/mcp/tools/)에서 확인할 수 있습니다.

Source: https://docs.alpacax.com/ko/integrate/mcp/