---
type: how-to
title: MCP 서버 쓰기
summary: MCP 서버를 통해 AI 에이전트를 Caputchin에 연결하고, 액세스 토큰으로 그것을 인증하고, 자연어로 관리 API를 몰아가세요, 동작하는 예제와 함께.
---

Caputchin MCP 서버는 AI 에이전트(Claude, Cursor, 또는 어떤 [Model Context Protocol](https://modelcontextprotocol.io) 클라이언트든)가 대시보드가 쓰는 같은 [관리 API](/docs/automation/management-api)를 호출해 당신의 계정을 관리하게 합니다. 서버는 얇은 전송·인증 셸입니다: 관리 작업마다 MCP 도구 하나를 노출하고 각 호출을 API로 프록시합니다. 그래서 에이전트는 결제만 빼고 당신이 할 수 있는 무엇이든, 자연어로 할 수 있습니다.

## 액세스 토큰 발급하기 [#mint-an-access-token]

서버는 `CAPUTCHIN_TOKEN` 환경 변수의 액세스 토큰으로 인증합니다. 어느 종류든 동작합니다([API 인증](/docs/automation/management-api#mint-an-access-token)을 보세요):

- 전체 계정 제어를 위한 [Personal Access Token](/docs/account-management/personal-access-token), 또는
- 에이전트를 최소 권한으로 특정 팀에 범위 지정하는 [Troop Access Token](/docs/troops/tokens), 자율 에이전트에 접근 권한을 넘길 때 더 안전한 기본값입니다.

생성 시 토큰을 복사하세요; 한 번 표시됩니다.

## 연결하는 두 방법

두 전송이 있고, 그것들은 같은 관리 API로 뒷받침되는 **같은 도구**를 노출합니다. 당신의 클라이언트가 어떻게 연결하는지로 고르세요:

| | 로컬 (stdio) | 호스팅 (HTTP) |
|---|---|---|
| 무엇인가 | 당신 머신에서 돌리는 `@caputchin/mcp` 패키지 | `api.caputchin.com/mcp`의 원격 엔드포인트 |
| 클라이언트에 필요한 것 | 로컬 프로세스 띄우기(stdio) | 원격 MCP 서버에 연결(HTTP) |
| 인증 | 프로세스 환경의 `CAPUTCHIN_TOKEN` | 연결의 `Authorization: Bearer` 헤더 |
| 가장 알맞을 때 | 로컬 개발, 데스크톱 클라이언트, 인바운드 네트워크 없음 | 호스팅된 에이전트, 띄울 로컬 프로세스 없음 |

### 로컬: npx 서버 (stdio)

서버는 npm에 `@caputchin/mcp`로 공개됩니다. 보통 그것을 손으로 돌리지 않습니다; 당신의 MCP 클라이언트 설정에 그것을 배선하면 토큰을 환경에 둔 채 stdio로 띄워집니다:

```json
{
  "mcpServers": {
    "caputchin": {
      "command": "npx",
      "args": ["-y", "@caputchin/mcp"],
      "env": { "CAPUTCHIN_TOKEN": "cpt_pat_..." }
    }
  }
}
```

그것이 도는지 확인하려면, 직접 띄우세요; 그것은 stdio로 MCP를 말하고 토큰이 없으면 오류로 종료합니다:

```bash
CAPUTCHIN_TOKEN=cpt_pat_... npx -y @caputchin/mcp
```

### 호스팅: HTTP 엔드포인트

로컬을 띄우는 대신 원격 MCP 서버에 연결하는 클라이언트를 위해, Caputchin은 같은 서버를 여기 호스팅합니다:

```
https://api.caputchin.com/mcp
```

그것은 연결의 `Bearer` 헤더로 당신의 토큰을 인증합니다(같은 자격 증명을, 그저 환경이 아니라 HTTP로 넘긴 것):

```json
{
  "mcpServers": {
    "caputchin": {
      "url": "https://api.caputchin.com/mcp",
      "headers": { "Authorization": "Bearer cpt_pat_..." }
    }
  }
}
```

정확한 설정 모양은 당신의 MCP 클라이언트에 달렸습니다; 중요한 것은 URL과 `Authorization: Bearer` 헤더입니다. 설치할 것도, 로컬 프로세스도 없습니다; 절충은 토큰이 로컬 프로세스 환경에 머무는 대신 요청마다 호스팅 엔드포인트로 이동한다는 점입니다.

## 도구들

모든 도구는 `caputchin_<verb>_<noun>`으로 이름 지어지고 하나의 관리 작업에 대응합니다, 예를 들어 `caputchin_list_troops`, `caputchin_create_site`, `caputchin_rotate_site_secret`, `caputchin_add_troop_member`, `caputchin_site_stats`. 에이전트는 전체 묶음과 각 도구의 파라미터를 MCP로 자동 발견하니, 당신은 목표를 묘사하고 에이전트가 도구를 고릅니다.

## 동작하는 예제

서버를 당신의 클라이언트에 배선한 채, 에이전트에게 평이한 말로 요청할 수 있습니다:

> "내 shop-team 팀에 shop-frontend라는 사이트 키를 만들고, 그것에 게임 게이트를 켜 줘."

에이전트는 그것을 일련의 도구 호출로 해소합니다: 팀 id를 찾는 `caputchin_list_troops`, 그 `troop_id`를 둔 `caputchin_create_site`, 그다음 게임을 요구하는 `caputchin_update_site_security`. 각 호출은 당신의 토큰으로 관리 API에 닿고, Apex에서는 각각이 토큰에 귀속되어 당신의 [감사 로그](/docs/audit-logs/overview)에 떨어지니, 에이전트의 행동은 사람의 것만큼 추적 가능합니다.

에이전트는 당신 토큰의 전체 도달 범위로 행동하므로, 가능하면 범위 지정된 팀 토큰을 선호하고, 작업이 끝나는 순간 그것을 취소하세요.

## 전체 레퍼런스

각각 한 줄 설명과 그 토큰이 지녀야 하는 권한을 둔 도구의 완전한 목록은, [MCP 도구 레퍼런스](/docs/automation/mcp-tools)를 보세요. 도구는 관리 API를 일대일로 비추니, [대화형 API 레퍼런스](/docs/api-reference)가 모든 작업의 파라미터와 응답에 대한 권위 있는 설명입니다: 에이전트를 향한 요약은 도구의 MCP 설명을, 정확한 스키마는 API 레퍼런스를 읽으세요.

## 함께 보기

- [MCP 도구 레퍼런스](/docs/automation/mcp-tools): 모든 도구, 그 설명, 그리고 그것이 필요로 하는 권한.
- [API에서 Caputchin 관리하기](/docs/automation/management-api): 모든 도구가 호출하는 HTTP API.
- [Terraform 또는 OpenTofu 쓰기](/docs/automation/terraform): 코드형 인프라 표면.
- [Personal Access Token](/docs/account-management/personal-access-token)과 [팀 토큰](/docs/troops/tokens): 서버가 쓰는 자격 증명.