Get Started
노드 사용법 익히기 - MCP 노드 (MCP Tool / MCP Client)
에이전트리아(Agentria)에서는 MCP 노드를 사용해 외부에서 만들어 둔 도구를 에이전트에 연결하고, 웹 검색·데이터 추출 같은 실제 작업을 워크플로 안에서 수행할 수 있습니다. 에이전트리아는 MCP 도구(MCP Tool) 노드와 MCP 클라이언트(MCP Client) 노드 두 가지를 제공합니다.
이 튜토리얼에서는 웹 검색 MCP 서버를 연결해, 사용자의 질문을 받은 에이전트가 스스로 검색 도구를 골라 호출하고 그 결과로 답변을 만드는 워크플로를 만듭니다. 마지막에는 같은 서버의 도구를 MCP 클라이언트 노드로 직접 호출하는 방법도 함께 살펴봅니다.
MCP란?
MCP(Model Context Protocol, 모델 컨텍스트 프로토콜)는 에이전트가 어떤 액션을 취하기 위한 약속입니다. 흔히 "AI를 위한 USB-C 단자"에 비유합니다. 기기마다 다른 충전기를 쓰는 대신 USB-C 하나로 모든 기기를 연결하듯, MCP는 하나의 표준 규격으로 다양한 도구를 에이전트에 연결합니다.
LLM은 글을 생성할 수는 있어도 웹 검색이나 파일 작성 같은 실제 액션은 직접 수행하지 못합니다. 그 액션은 대부분 API 호출로 이루어지기 때문입니다. MCP는 "어떤 도구를, 어떤 인자로 호출하면 되는지"를 에이전트가 읽을 수 있는 형태로 알려주는 인터페이스입니다.
MCP를 이해하려면 세 가지 개념을 알면 됩니다.
도구(Tool) : MCP 서버가 제공하는 하나의 기능입니다. 각 도구는 "무엇을 할 수 있는지" 설명하는 디스크립션(Description)과, "어떤 인자를 넘기면 되는지" 정의하는 입력 정보를 함께 가집니다. 예를 들어 검색 도구는
query(검색어)라는 인자를 받습니다.MCP 서버 : 여러 도구를 모아 제공하고, 에이전트의 요청을 받아 실제 액션을 수행한 뒤 결과를 돌려주는 서버입니다. 검색·파일 작성·코드 실행 등 서버마다 제공하는 도구가 다릅니다.
MCP 클라이언트 : MCP 서버에 연결해 도구를 호출하는 쪽입니다. 도구를 호출할 수 있는 시스템 + 어떤 도구를 호출할지 판단하는 LLM이 합쳐진 형태입니다. Claude 데스크탑 앱이 대표적인 MCP 클라이언트이며, 에이전트리아의 MCP 노드도 같은 역할을 합니다.
전체 동작은 다음 순서로 이루어집니다.
여기서 중요한 것은 어떤 도구를 호출할지 결정하는 주체가 LLM이라는 점입니다. 호출 순서를 미리 정해두는 것이 아니라, 에이전트가 도구의 디스크립션을 읽고 지금 필요한 도구를 스스로 고릅니다. 그래서 도구를 여러 개 연결해 두면 작업 내용에 따라 적절한 도구가 자동으로 선택됩니다.
MCP는 "설명서"가 아니라 "실행 경로"입니다. 어떤 일을 어떻게 처리할지 적어둔 명세 문서는 LLM에게 판단 기준을 알려줄 뿐 실제 동작을 만들지 못합니다. MCP는 디스크립션에 더해 호출할 인자 형식과 연결할 서버까지 함께 규정하므로, 에이전트가 그 규격대로 요청을 보내면 실제로 검색이 실행되고 결과가 돌아옵니다.
MCP 서버는 내 컴퓨터에서 직접 실행하는 방식(로컬)과, 인터넷 주소로 접속하는 방식(원격, 호스티드)이 있습니다. 에이전트리아는 MCP 서버 URL을 입력해 원격 MCP 서버에 연결합니다. 따라서 접속할 URL과, 서버가 요구하는 인증값(API 키 등)만 준비하면 됩니다.
사전 준비
시작하려면 에이전트리아에서 프로젝트를 생성한 뒤 에이전트 캔버스(Canvas)에 진입합니다.
캔버스 진입 방법은 🔗3단계 핵심 가이드의 1단계(프로젝트 생성 및 컴포저 선택)를 참고하시기 바랍니다.
이 튜토리얼을 완료하면 다음 작업을 수행할 수 있습니다.
MCP Parameters크리덴셜에 MCP 서버 정보를 등록합니다.MCP 도구 노드를 추가하고 서버가 제공하는 도구 목록을 불러옵니다.MCP 도구 노드를 에이전트 노드에 도구로 연결해 에이전트가 도구를 자동으로 호출하게 합니다.MCP 클라이언트 노드로 특정 도구를 직접 호출합니다.
연결할 MCP 서버 준비하기
MCP 노드를 사용하려면 연결할 MCP 서버가 필요합니다. 이 튜토리얼에서는 가입과 키 발급이 간단한 Tavily 웹 검색 MCP 서버를 사용합니다.
https://app.tavily.com 에 접속해 무료 계정을 생성합니다. 신용카드 등록 없이 월 1,000 크레딧을 사용할 수 있습니다.
로그인하면 대시보드에 API 키가 표시됩니다. (
tvly-로 시작하는 문자열)아래 형식의 자리에 발급받은 키를 넣어 서버 URL을 완성합니다. Tavily는 키를 URL 뒤에 쿼리 파라미터로 붙이는 방식을 지원하므로, 이 URL 하나로 인증까지 끝납니다.
Tavily MCP 서버는 아래 도구를 제공합니다.
도구 이름 | 설명 | 주요 인자 |
|---|---|---|
| 실시간 웹 검색 |
|
| 웹 페이지에서 데이터 추출 |
|
다른 MCP 서버를 쓰고 싶다면 MCP 서버를 모아둔 곳에서 원하는 기능의 서버를 찾아 서버 URL과 인증 방식을 확인하면 됩니다. MCP 공식 레지스트리에서 검증된 서버를 먼저 찾아보고, 원하는 서버가 없다면 Smithery에서 호스팅된 원격 서버의 접속 URL을 바로 확인할 수 있습니다. 서버가 바뀌어도 에이전트리아에서 연결하는 방법은 동일합니다.
MCP Parameters 크리덴셜 만들기
![이미지]
두 MCP 노드 모두 MCP Parameters 크리덴셜(Credential)에 MCP 서버 정보를 등록해 사용합니다. 크리덴셜은 한 번 만들어 두면 여러 노드에서 재사용할 수 있습니다.
MCP Parameters 크레덴셜 추가 모달은 다음 항목으로 구성됩니다.
항목 | 필수 여부 | 설명 |
|---|---|---|
| 필수 | 크리덴셜을 구분할 이름 (예: |
| 선택 | 이 크리덴셜에 대한 메모 |
| 선택 | 켜면 MCP 노드를 추가할 때 이 크리덴셜이 기본으로 선택됩니다 |
| 필수 | 연결할 MCP 서버의 주소 |
| 선택 | 서버가 별도 키 인증을 요구할 때 입력 |
| 선택 | 서버가 헤더 인증을 요구할 때 JSON 형식으로 입력 (예: |
| 선택 | 서버가 쿼리 파라미터를 요구할 때 JSON 형식으로 입력 |
Headers와 Query Parameters는 {} 가 기본값인 JSON 입력란입니다. 필요 없으면 {} 상태 그대로 둡니다.
Tavily는 API 키를 URL 뒤에 붙이는 방식을 지원하므로, MCP SERVER URL 항목에 앞에서 완성한 전체 URL을 그대로 입력하고 API-KEY·Headers·Query Parameters는 비워 둡니다.
입력이 끝나면 저장 버튼을 클릭합니다.
키를 URL에 붙이지 않고
Query Parameters에{"tavilyApiKey": ""}로 분리해 입력해도 결과는 같습니다. 어느 쪽이든 서버에는 동일한 요청이 전달되므로, URL 하나로 끝나는 앞의 방식이 더 간단합니다.
서버마다 인증 방식이 다릅니다. 헤더 인증을 쓰는 서버라면
MCP SERVER URL에는 기본 주소만 입력하고Headers에{"x-api-key": ""}형식으로 입력합니다. 인증값이 없거나 잘못되면 도구 목록을 불러오는 단계에서 호출이 실패하므로 서버 문서에서 요구하는 방식대로 정확히 입력합니다.
모달 하단의
+ 세트 추가버튼은 키 로테이션(Key Rotation) 을 위한 기능입니다. 세트를 여러 개 등록해 두면 사용 중인 키가 레이트 리밋(Rate Limit)에 걸리거나 토큰을 모두 소진했을 때 다음 세트의 키로 이어서 호출을 시도합니다. 무료 플랜처럼 호출 한도가 빠듯한 서버를 쓸 때 유용합니다. 이 튜토리얼에서는세트 1만 사용합니다.
워크플로 개요
![이미지]
전체 워크플로는 Agent Input → 에이전트 루프(Agent Loop) 노드 → Agent Output 순서로 실행되며, MCP 도구 노드가 에이전트 루프 노드에 도구로 연결됩니다.
이 튜토리얼의 핵심은 MCP 노드입니다.
MCP 도구 노드는 MCP 서버가 제공하는 도구 목록을 불러와 에이전트에게 넘겨주는 역할을 합니다. 에이전트는 그 목록에서 지금 필요한 도구를 골라, 필요한 인자를 스스로 채워 호출합니다. 검색 결과가 돌아오면 그 내용을 근거로 최종 답변을 생성합니다.
에이전트리아의 두 MCP 노드는 다음과 같이 나뉩니다.
노드 | 위치 | 사용 방식 | 언제 사용하나요 |
|---|---|---|---|
| AI Agent 섹션 | 에이전트 노드에 도구로 연결 | 에이전트가 작업에 맞는 도구를 자동으로 선택·호출하게 하고 싶을 때 |
| 유틸리티 / 생산성 섹션 | 단독으로 직접 호출 | 호출할 도구와 인자를 직접 지정해 특정 작업만 실행하고 싶을 때 |
대부분의 경우 MCP 도구 노드를 에이전트에 연결하는 방식이 편리합니다. 도구 호출에 필요한 인자를 에이전트가 알아서 채워 주기 때문입니다.
함께 등장하는 에이전트 루프 노드의 자세한 사용법은 🔗에이전트 가이드를 참고하시기 바랍니다.
1단계: 시작 노드(Agent Input) 확인
![이미지]
에이전트 워크플로의 시작 노드는 Agent Input입니다. Agent Input 노드를 더블클릭해 노드 편집기를 엽니다.
Agent Input의 입력 변수는 아래 네 가지로 고정되어 있어 직접 추가하거나 수정할 수 없습니다.
입력 변수 | 설명 |
|---|---|
| 사용자가 입력한 메시지 |
| 사용자가 업로드한 파일 |
| JSON 오브젝트 형태로 전달되는 커스텀 메타데이터 |
| 현재 대화의 세션 식별자. 채팅방 ID로 자동 설정됩니다 |
사용자가 채팅으로 보낸 질문은 input_message에 담겨 그대로 에이전트에게 전달됩니다. 따라서 이 튜토리얼에서는 별도로 선언할 변수가 없습니다.
인풋 변수를 직접 선언해 워크플로를 구성하려면 어빌리티를 사용합니다. 에이전트 워크플로의 입력은
Agent Input의 고정 변수로 정해져 있습니다.
확인이 끝나면 캔버스로 돌아옵니다.
2단계: 에이전트 루프 노드 추가
![이미지]
캔버스 하단의 +노드 추가(Add Node) 버튼을 클릭하고, AI Agent 섹션에서 에이전트 루프(Agent Loop) 노드를 드래그 앤 드롭으로 캔버스에 배치합니다.
MCP 도구 노드는 단독으로 실행되지 않고 에이전트 노드에 도구로 연결해 사용하므로, 도구를 붙일 에이전트 노드를 먼저 배치합니다.
3단계: MCP 도구 노드 추가
![이미지]
같은 AI Agent 섹션에서 MCP 도구(MCP Tool) 노드를 드래그 앤 드롭으로 캔버스에 배치합니다.
에이전트 루프 노드 아래쪽에 배치하면 이후 도구 연결이 수월합니다.
4단계: MCP 도구 노드 설정 (크리덴셜 연결 & 도구 로드)
![이미지]
MCP 도구 노드를 더블클릭해 노드 편집기를 엽니다.
MCP Parameters항목에서 사전 준비 단계에서 만든 크리덴셜을 선택합니다.도구 연결 & 로드버튼을 클릭합니다. 해당 MCP 서버에 접속해 서버가 제공하는 도구 목록을 불러옵니다.작업(도구)목록에 불러온 도구(tavily-search,tavily-extract)가 표시됩니다. 에이전트에게 사용하게 할 도구를 선택합니다.모두 선택을 체크하면 불러온 도구를 전부 사용할 수 있습니다.
이 단계에서 불러오는 것은 도구 이름뿐 아니라 각 도구의 디스크립션과 인자 정보입니다. 에이전트는 이 정보를 읽고 어떤 도구를 언제 호출할지 판단합니다. 따라서 여러 도구를 선택해 두면 에이전트가 작업 내용에 따라 그중 적절한 도구를 자동으로 골라 호출합니다.
도구 목록이 비어 있거나 불러오기에 실패하면 크리덴셜의 서버 URL과 인증값을 다시 확인합니다. 인증값이 잘못되면 서버가 도구 목록 요청을 거부합니다.
설정이 완료되면 캔버스로 돌아옵니다.
5단계: 에이전트 루프 노드에 도구로 연결
![이미지]
에이전트 루프 노드 하단의 Tools 핀과 MCP 도구 노드의 인핀(In-Pin)을 엣지(Edge)로 연결합니다.
도구로 연결하면 도구 호출에 필요한 인자(검색어, 결과 개수 등)를 에이전트가 자동으로 채워 주기 때문에 따로 값을 입력할 필요가 없습니다. 예를 들어 에이전트에게 "MCP가 무엇인지 검색해줘"라고 요청하면, 에이전트가 tavily-search 도구를 골라 query에 검색어를 채워 호출하고, 돌아온 검색 결과로 답변을 생성합니다.
MCP 도구 노드는 여러 개를 붙일 수 있습니다. 검색·파일 작성·일정 조회처럼 서로 다른 MCP 서버의 도구를 함께 연결해 두면, 에이전트 노드 하나로 여러 종류의 작업을 처리할 수 있습니다.
6단계: 엣지로 노드 연결
![이미지]
나머지 노드를 엣지로 연결합니다.
Agent Input의 아웃핀(Out-Pin) →에이전트 루프 노드의 인핀(In-Pin)에이전트 루프 노드의 아웃핀(Out-Pin) →Agent Output의 인핀(In-Pin)
연결이 완료되면 사용자가 채팅으로 입력한 메시지가 input_message를 통해 에이전트 루프 노드로 전달되고, 에이전트가 생성한 답변이 Agent Output으로 넘어갑니다.
이것으로 '웹 검색 에이전트' 워크플로가 완성되었습니다.
7단계: 채팅 테스트로 워크플로 전체 실행
![이미지]
CHAT TEST 버튼을 클릭하고, 채팅 입력창에 아래 메시지를 입력해 실행합니다.
검색 내용을 근거로 작성된 답변이 돌아오면 워크플로가 정상적으로 동작하는 것입니다. 실행 로그에서 에이전트가 tavily-search 도구를 호출한 기록과 서버가 돌려준 검색 결과도 함께 확인할 수 있습니다.
MCP 클라이언트 노드로 도구 직접 호출하기
에이전트에게 도구 선택을 맡기지 않고, 호출할 도구와 인자를 직접 지정하고 싶을 때는 MCP 클라이언트(MCP Client) 노드를 사용합니다. 이 노드는 에이전트 없이 단독으로 MCP 서버의 도구를 호출합니다.
MCP 클라이언트 노드 추가 및 설정
![이미지]
+노드 추가 패널의 유틸리티 / 생산성 섹션에서 MCP 클라이언트(MCP Client) 노드를 드래그 앤 드롭으로 캔버스에 배치한 뒤, 더블클릭해 노드 편집기를 엽니다.
MCP 클라이언트 노드는 아래 옵션을 제공합니다.
옵션 | 필수 여부 | 설명 |
|---|---|---|
| 필수 | 연결할 MCP 서버 크리덴셜 ( |
| 선택 |
|
| 필수 | 호출할 도구의 이름 |
| 필수 | 호출할 도구에 전달할 인자 (JSON 형식) |
크리덴셜 선택
MCP Parameters의 Select Credential에서 사전 준비 단계에서 만든 크리덴셜을 선택합니다. MCP 도구 노드와 동일한 크리덴셜을 그대로 재사용할 수 있습니다.
호출할 도구 지정
MCP 도구 노드와 달리 값을 채워 줄 에이전트가 없으므로, 호출할 도구와 인자를 직접 입력합니다. Tavily에서 웹 검색을 실행하는 경우 아래와 같이 설정합니다.
항목 | 값 |
|---|---|
|
|
|
|
tool_arguments의 query는 검색어, max_results는 가져올 결과 개수입니다. 도구 이름과 인자 형식은 에이전트리아가 아니라 사용하는 MCP 서버 쪽에서 정의하므로, 해당 서버의 문서에서 확인해 입력합니다.
상세 결과 플래그
상세 결과 플래그를 켜면(True) 기본 결과에 더해 메타 정보 등 추가 데이터가 함께 반환됩니다. 검색 결과 본문만 필요하면 끈 상태(Off)로 둡니다.
tool_name과tool_arguments는 인풋 영역(Input Section)에서 입력 변수에 연결해 사용할 수도 있습니다. 이전 노드에서 만든 값을 전달하려면, 왼쪽 인풋 영역에서 연결할 타입을 선택한 뒤 변수를 드래그 앤 드롭으로 각 필드에 배치합니다.
노드 테스트로 실행 확인
![이미지]
노드 편집기 상단의 테스트(TEST) 버튼을 클릭해 도구가 정상적으로 호출되는지 확인합니다.
호출이 성공하면 아웃풋 영역(Output Section)의 result에 도구 실행 결과가 반환됩니다.
다음 단계
🎉 축하합니다! 에이전트리아를 사용해 '웹 검색 에이전트' 워크플로를 완성했습니다.
MCP 도구 노드에 여러 MCP 서버의 도구를 함께 연결해 에이전트가 검색·추출·일정 관리 등 다양한 작업을 처리하도록 확장하거나, MCP 클라이언트 노드로 특정 도구를 정해진 인자로 호출하는 워크플로를 만들어 보시기 바랍니다.
에이전트리아는 아이디어를 현실로 바꾸는 가능성의 공간입니다.
당신의 상상력으로 워크플로는 무한히 확장될 수 있습니다.
자주 묻는 질문
MCP 노드란 무엇인가요?
MCP 노드는 에이전트리아에서 MCP(Model Context Protocol) 서버에 연결해 외부 도구를 사용하는 노드입니다. MCP는 에이전트가 검색·파일 작성 같은 실제 액션을 취하기 위한 약속으로, 어떤 도구를 어떤 인자로 호출하면 되는지를 에이전트가 읽을 수 있는 형태로 규정합니다. 에이전트리아는 에이전트에 도구로 연결하는 MCP 도구(MCP Tool) 노드와 단독으로 도구를 호출하는 MCP 클라이언트(MCP Client) 노드를 제공합니다.
MCP 도구 노드와 MCP 클라이언트 노드는 각각 언제 사용하나요?
에이전트가 상황에 맞는 도구를 스스로 골라 호출하게 하려면 MCP 도구 노드를 에이전트 루프(Agent Loop) 노드 같은 에이전트 노드에 도구로 연결합니다. 이 경우 검색어나 결과 개수 같은 인자를 에이전트가 자동으로 채워 줍니다. 반대로 호출할 도구와 인자가 이미 정해져 있어 매번 같은 작업만 실행하면 될 때는 MCP 클라이언트 노드에 tool_name과 tool_arguments를 직접 입력해 사용합니다.
MCP는 스킬이나 명세 문서와 어떻게 다른가요?
어떤 일을 어떻게 처리할지 적어 둔 명세 문서는 LLM에게 판단 기준을 제공할 뿐, 그 자체로는 아무 동작도 실행하지 못합니다. MCP는 도구의 디스크립션에 더해 넘겨야 할 인자 형식과 요청을 받을 MCP 서버까지 함께 규정하므로, 에이전트가 그 규격대로 호출하면 서버가 실제로 액션을 수행하고 결과를 돌려줍니다. 즉 명세 문서가 "무엇을 해야 하는지"라면, MCP는 "실제로 실행되는 경로"입니다.
MCP 도구 노드는 웹 요청 노드와 어떻게 다른가요?
웹 요청(Web Request) 노드는 URL·메서드·파라미터를 직접 지정해 API를 호출하는 노드로, 호출 대상과 값이 워크플로에 고정되어 있습니다. MCP 도구 노드는 MCP 서버에서 도구 목록과 각 도구의 디스크립션을 먼저 불러온 뒤 이를 에이전트에게 넘기고, 어떤 도구를 어떤 인자로 호출할지는 에이전트가 판단합니다. 호출할 API가 정해져 있으면 웹 요청 노드가, 에이전트가 상황에 따라 도구를 골라야 하면 MCP 도구 노드가 적합합니다.
MCP 도구 노드는 에이전트 루프 노드와 어떻게 함께 동작하나요?
MCP 도구 노드는 단독으로 실행되지 않고, 에이전트 루프 노드 하단의 Tools 핀에 엣지로 연결해 사용합니다. 연결하면 MCP 도구 노드가 불러온 도구 목록이 에이전트에게 전달되고, 에이전트는 사용자 요청을 처리하는 과정에서 필요한 도구를 선택해 인자를 채워 호출한 뒤 그 결과로 답변을 생성합니다. MCP 도구 노드를 여러 개 연결하면 에이전트 노드 하나로 여러 MCP 서버의 도구를 함께 사용할 수 있습니다.