# MCP 서버가 제공하는 것

> **이 장에서 배우는 것**
> MCP 서버가 내놓는 세 종류와 각각의 쓰임. 그리고 왜 도구 설명을 잘 쓰는 것이
> 생각보다 중요한지.

## 세 가지

| 종류 | 무엇인가 | 성격 |
|---|---|---|
| **도구(Tools)** | 에이전트가 **부르는** 동작 | 능동 |
| **리소스(Resources)** | 에이전트가 **읽는** 자료 | 수동 |
| **프롬프트(Prompts)** | 미리 준비된 **지시 템플릿** | 사람이 고름 |

실무에서 대부분은 **도구**입니다. 나머지 둘은 있으면 편한 정도입니다.

## 1. 도구 — 가장 많이 쓰는 것

에이전트가 호출할 수 있는 동작입니다. 각 도구는 이렇게 생겼습니다.

```
이름:   재고조회
설명:   제품 코드로 현재 창고 재고 수량을 조회합니다.
        여러 창고에 있으면 창고별로 나눠서 반환합니다.
인자:   제품코드 (문자열, 필수)
        창고코드 (문자열, 선택 — 없으면 전체)
반환:   창고별 수량 목록
```

### 설명이 생각보다 중요합니다

**모델은 이 설명을 읽고 언제 쓸지 판단합니다.** 설명이 부실하면 안 써야 할 때
쓰거나, 써야 할 때 안 씁니다.

```
✗ 설명: "재고 조회"
   → 어떤 재고인지, 언제 쓰는지 모름

✓ 설명: "제품 코드로 현재 창고 재고 수량을 조회합니다.
         판매 가능 수량이 아니라 물리적 재고입니다.
         예약분을 빼려면 예약조회를 함께 쓰세요."
   → 언제 쓰고 무엇을 주의할지가 들어 있음
```

**도구 설명은 사람이 아니라 모델에게 쓰는 문서입니다.** 그런데 잘 쓰는 요령은
사람에게 쓸 때와 같습니다 — 무엇을 하는지, 언제 쓰는지, 무엇을 주의할지.

### 이름도 중요합니다

비슷한 이름이 여럿이면 모델이 헷갈립니다.

```
✗ 조회1 / 조회2 / 데이터가져오기
✓ 재고조회 / 주문조회 / 고객조회
```

## 2. 리소스 — 읽을 자료

도구가 "무언가를 한다"면 리소스는 **"여기 자료가 있다"**입니다.

```
리소스 예:
  회사 규정집 (문서)
  제품 카탈로그 (문서)
  현재 프로젝트 파일 목록
```

도구와의 차이는 **부르는 주체**입니다.

| | 도구 | 리소스 |
|---|---|---|
| 누가 시작 | 모델이 판단해서 호출 | 사람이 골라서 넣거나, 모델이 읽음 |
| 성격 | 동작 | 자료 |
| 예 | "재고를 조회하라" | "여기 규정집이 있다" |

실무에서는 **자주 참조하는 문서**를 리소스로 두면 편합니다. 매번 붙여넣지 않아도
됩니다.

## 3. 프롬프트 — 준비된 지시 템플릿

자주 쓰는 지시를 서버가 미리 만들어 제공하는 것입니다.

```
프롬프트: "PR 리뷰"
내용:     아래 변경사항을 리뷰해주세요.
          - 보안 문제가 있는지
          - 테스트가 빠진 곳이 있는지
          - 우리 코드 규칙(첨부)에 맞는지
```

사람이 목록에서 골라 쓰는 형태입니다. **[좋은 지시의 네 요소](/guide/ai-intent-context)를
매번 다시 쓰지 않게 해주는 장치**로 보면 됩니다.

## 세 가지가 함께 쓰이는 모습

```mermaid
graph TD
  P["프롬프트: 'PR 리뷰'<br/>사람이 선택"] --> M["모델"]
  R["리소스: 코드 규칙 문서<br/>참조 자료로 제공"] --> M
  M -->|"필요할 때 호출"| T1["도구: 변경사항 조회"]
  M -->|"필요할 때 호출"| T2["도구: 테스트 실행"]
  T1 --> M
  T2 --> M
  M --> O["리뷰 결과"]
```

## Connect 에서는

[HyperTeams Connect](/guide/cn-agents-intro)에서 MCP 서버를 붙이면, 그 서버의
도구들이 **에이전트 목록에 `APP` 으로 올라옵니다.** 워크스페이스별로 어떤 도구를
켤지 정할 수 있습니다.

반대 방향도 됩니다 — Connect 자체가 MCP 서버가 되어 외부 클라이언트(Claude Code
등)가 이 워크스페이스를 도구로 쓸 수 있습니다.

## 자주 하는 오해

### "리소스와 도구 중 뭘 써야 하나?"

**동작이면 도구, 자료면 리소스**입니다. 헷갈리면 이렇게 물어보세요 — "이게
무언가를 바꾸거나 실행하는가?" 그렇다면 도구입니다.

실무에서는 대부분 도구로 만듭니다. 자료도 "문서조회(문서명)" 같은 도구로 만들면
모델이 필요할 때 스스로 가져갑니다.

### "도구 설명은 대충 써도 알아서 하지 않나?"

가장 자주 하는 실수입니다. **모델이 도구를 잘못 고르는 원인의 대부분이 설명
부실**입니다. 도구를 만드는 시간의 상당 부분을 설명 쓰는 데 써야 합니다.

---

## 확인

**1. 도구 설명이 왜 중요합니까?**

<details>
<summary>답</summary>

**모델이 그 설명을 읽고 언제 쓸지 판단하기 때문**입니다. 설명이 부실하면 안 써야
할 때 쓰거나 써야 할 때 안 씁니다. 모델이 도구를 잘못 고르는 원인의 대부분이
설명 부실입니다.
</details>

**2. 도구와 리소스를 어떻게 구분합니까?**

<details>
<summary>답</summary>

**동작이면 도구, 자료면 리소스**입니다. "무언가를 바꾸거나 실행하는가"로 물어보면
됩니다. 실무에서는 자료도 조회 도구로 만드는 경우가 많습니다.
</details>

**3. 프롬프트(템플릿)는 무엇을 덜어줍니까?**

<details>
<summary>답</summary>

**매번 지시를 다시 쓰는 수고**입니다. 자주 쓰는 지시를 미리 만들어두고 사람이
목록에서 골라 씁니다.
</details>

---

도구가 많아지면 새로운 문제가 생깁니다 →
[도구가 많아질 때](/guide/mcp-too-many-tools)