ByteChef Embedded Part 6: MCP Chat

요약: Part Three에서는 사용자의 라우트가 ByteChef로부터 사용자 도구를 가져와 AI SDK에 맞게 각 도구를 조정했습니다. MCP Chat은 표준이 이 작업을 수행할 수 있게 합니다: 백엔드 라우트(/api/chat-mcp)가 스트리밍 가능한 HTTP를 통해 ByteChef의 임베디드 MCP 서버로 MCP 클라이언트를 열고, mcpClient.tools()를 호출하여 연결된 사용자의 도구를 발견한 다음, 이를 모델에 직접 전달합니다. 이는 Claude와 Cursor가 사용하는 것과 동일한 Model Context Protocol이며, 사용자 자신의 채팅 내부에서 소비됩니다. 이것은 시리즈의 Part Six입니다.

ComponentKit Chat은 비서에게 실제 도구를 제공했지만, 사용자의 라우트는 ByteChef의 도구 API를 알아야 했습니다: 목록을 가져오고, 각 스키마를 구문 분석하고, tool()로 래핑한 다음, 모든 호출을 실행을 위해 POST해야 했습니다. MCP Chat은 대신 프로토콜을 통해 동일한 종류의 도구 상자를 얻으므로, 발견과 실행이 앱별로 수동으로 작성되는 것이 아니라 표준화됩니다.

ByteChef에 MCP 서버 설정하기

채팅이 무언가를 발견하려면, ByteChef는 어떤 도구를 노출할지 알려주는 MCP 서버가 필요합니다. 이 서버는 공급자로서 한 번 구축하며, 연결된 모든 사용자는 그 자체의 범위가 지정된 뷰를 얻게 됩니다.

1. 통합(Integration) 먼저 게시하기

임베디드 MCP 서버는 귀하의 게시된 통합 중 하나가 사용하는 컴포넌트만 제공합니다. Part One을 따랐다면 이미 하나를 가지고 있을 것입니다. 여기서는 Gmail 통합이며, 이것이 아래 단계에서 Gmail이 표시되는 이유입니다.

2. 서버 생성하기

Embedded → MCP Servers로 이동하여 New MCP Server를 클릭합니다. 요청하는 것은 이름뿐입니다. 여러 개의 서버를 서로 다른 도구 상자와 함께 실행할 수 있으므로, 비서가 무엇을 위한 것인지 설명하는 이름을 선택하세요.

3. 컴포넌트 추가 및 도구 선택하기

새 서버를 확장하고, 컴포넌트 도구(Component Tools) 탭에서 **컴포넌트 추가(Add Component)**를 클릭합니다. 피커에는 게시된 통합 뒤에 있는 컴포넌트들이 나열되며, 각 컴포넌트가 제공하는 도구의 개수가 표시됩니다.

하나를 선택하면 해당 컴포넌트의 전체 동작 목록을 얻게 됩니다. 모델이 사용하기를 원하는 것만 체크하세요. Gmail은 **이메일 삭제(Delete Email)**를 포함하여 11개의 기능을 가지고 있으므로, 이 단계에서 비서가 이메일을 검색하고 읽을 수는 있지만 삭제할 수는 없도록 결정합니다.

저장하면 해당 컴포넌트가 선택한 도구들과 함께 서버에 나타납니다. 각 도구 옆의 톱니바퀴 아이콘(구성(Configure))을 사용하면 이름을 변경하고, 모델이 읽는 설명을 다시 작성하며, 특정 입력을 고정된 값으로 지정할 수 있습니다. 그대로 두는 입력은 모델에 의해 자동 정의됩니다. 예를 들어, 검색 이메일(Search Email)의 최대 결과(Max Results)를 고정하면 모델이 한 번의 호출로 전체 사서함을 가져가는 것을 방지합니다.

4. 워크플로우를 도구로 추가하기 (선택 사항)

4. 워크플로우를 도구로 추가하기 (선택 사항)

단일 액션만으로는 충분하지 않을 때가 있습니다. Workflow Tools 탭에서 Add Workflows 기능을 사용하면 전체 통합 워크플로우를 하나의 도구로 노출할 수 있습니다. 원하는 통합 인스턴스 구성을 선택하고 해당 워크플로우에 체크 표시를 하세요. 모델이 채우는 입력 스키마를 정의하는 트리거가 있는 Workflow › New Workflow Call을 시작하는 워크플로우만 자격이 됩니다.

여기서 Gmail 통합의 Send Email 워크플로우가 원본 Gmail 액션 옆에 도구로 나타납니다. 워크플로우 도구는 단순한 액션으로는 강제할 수 없는 규칙(고정된 발신자, 템플릿, 로깅 단계 등)을 적용할 수 있습니다.

5. 활성화 및 서버 URL 복사하기

서버의 토글을 켜고 Connect 탭을 여세요. Server URL은 https://<your-bytechef>/api/embedded/{secretKey}/mcp 형태입니다. 경로에 있는 secret key가 서버를 식별하므로 **민감(Sensitive)**으로 표시됩니다. 복사 아이콘을 누르면 URL이 복사되고, 새로고침 아이콘을 누르면 혹시 유출될 경우 secret 키가 변경됩니다.

이 URL은 샘플 앱에 필요한 유일한 서버 측 설정입니다. front-end/.env.local 파일에 다음 내용을 넣어주세요:

NEXT_PUBLIC_BYTECHEF_MCP_SERVER_URL=https://your-bytechef/api/embedded/{secretKey}/mcp

이 URL은 서버를 지정하고, 라우트가 보내는 connected-user JWT는 어떤 사용자의 도구와 연결을 사용할지 지정합니다. 모든 사용자가 하나의 URL을 공유하면서도 각자만의 도구 상자를 갖게 됩니다.

6. 사용자별 제어

연결된 사용자가 컴포넌트가 서버에 있는 통합(integration)을 연결하면, 해당 서버가 그들의 기록에 표시됩니다. Embedded → Connected Users를 열고 사용자를 클릭한 다음, MCP Servers 탭으로 전환합니다. 각 서버는 해당 사용자의 도구들을 자신이 속한 통합 아래에서 Component Tools와 Workflow Tools라는 두 그룹으로 나열하며, 여기에는 연결 상태와 버전이 포함됩니다. Send Email과 같은 워크플로우 도구(workflow tools)는 Search Email과 같은 단순 액션 옆에 위치합니다. 이 서버 전체를 해당 사용자에게서 끌 수도 있고, 개별 도구를 비활성화할 수도 있습니다.

사용자들도 동일한 제어를 할 수 있습니다. 연결된 통합에 대해 ConnectDialog를 열 때, 해당 Tools 탭에는 각 도구별 토글과 함께 통합의 도구들이 나열됩니다. Send Email과 같은 워크플로우 도구는 필요한 모든 입력을 포함하여 단순 액션 옆에 위치합니다.

기본 설정을 참고하세요: 사용자가 통합을 연결하거나(또는 다시 연결) 할 때, 해당 도구들은 비활성화된 상태로 시작합니다. 사용자가 직접 켜지 않는 한, 어시스턴트는 이를 사용할 수 없습니다. 이는 누군가의 메일함에서 작동하는 모든 것에 대해 합리적인 옵트인(opt-in) 방식이지만, 사용자 인터페이스(UI)는 사용자들이 이 탭으로 이동하도록 안내해야 함을 의미합니다.

Discovery를 통한 도구 관리 (Tools by Discovery)

채팅 페이지는 파트 3의 어시스턴트 UI 스레드와 동일합니다. 차이점은 전적으로 백엔드 라우트에 있습니다:

import { createMCPClient } from '@ai-sdk/mcp';
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';

...

직접 액션을 열거하고 래핑하는 대신, ByteChef의 임베디드 MCP 서버에 MCP 연결을 열고 이 연결된 사용자에게 사용 가능한 도구를 요청합니다. part one에서 사용한 동일한 JWT가 Authorization 헤더에 실려 가기 때문에, 사용자의 통합 기능(즉, _당신_이 판매자로서 위해 구성한 것들)은 이미 연결 범위로 한정된, 바로 호출 가능한 도구로 도착합니다. 작성할 execute 함수는 없습니다. 모델이 도구를 호출하면 MCP 클라이언트가 해당 호출을 서버로 전송해 주기 때문입니다.

라우트에서 주목할 몇 가지 세부 사항:

• stopWhen: stepCountIs(8): 에이전트 루프가 도구 호출 후에도 계속되도록 하여, 모델이 한 단계 후에 멈추는 대신 도구의 결과를 읽고 다시 행동하거나 (또는 답변) 할 수 있게 합니다.
• frontendTools(...): 어시스턴트 UI 페이지가 클라이언트에서 등록하는 모든 도구를 병합하여, MCP의 서버 도구와 브라우저 측 도구가 하나의 툴박스에 존재하게 합니다.
• mcpClient.close(): onFinish에서 실행되므로, 각 요청마다 자체적인 MCP 세션을 열고 닫습니다.

ByteChef 측 MCP 서버에 도구를 추가하면 다음 요청의 채팅창에 나타납니다. 클라이언트 변경은 필요 없습니다.

샘플 앱의 한 턴을 살펴보겠습니다. 모델은 발견된 도구들 중에서 GOOGLEMAIL_SEARCH_EMAIL을 찾고, subject 필드를 채운 후 결과로부터 답변합니다:

도구 이름은 COMPONENT_ACTION 패턴을 따르므로, Gmail Search Email 액션은 GOOGLEMAIL_SEARCH_EMAIL이 됩니다. 워크플로우 도구는 해당 워크플로우의 이름을 따르므로, 4단계의 Send Email 워크플로우는 Send_Email로 도착합니다.

온디맨드 권한 부여 (Authorization on Demand)

사용자는 모든 앱을 미리 연결할 필요가 없습니다. 만약 모델이 아직 통합되지 않은 도구(tool)를 호출하면, 임베디드 MCP 서버는 호출에 실패하지 않습니다. 대신 모델에게 무엇을 해야 하는지 알려주는 결과를 반환합니다: