MCP 서버가 주는 세 가지

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

세 가지

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

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

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

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

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

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

이름도 중요합니다

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

2. 리소스 — 읽을 자료

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

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

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

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

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

사람이 목록에서 골라 쓰는 형태입니다. 좋은 지시의 네 요소를 매번 다시 쓰지 않게 해주는 장치로 보면 됩니다.

세 가지가 함께 쓰이는 모습

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

Connect 에서는

HyperTeams Connect에서 MCP 서버를 붙이면, 그 서버의 도구들이 에이전트 목록에 APP 으로 올라옵니다. 워크스페이스별로 어떤 도구를 켤지 정할 수 있습니다.

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

자주 하는 오해

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

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

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

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

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

확인

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

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

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

파트가 끝났습니다. 이제 이 모든 것을 매일 일하는 방식으로 만드는 방법론입니다 → 애자일이 풀었던 문제와 남은 병목