Reachy Mini에 MCP 도구 추가하기

Reachy Mini 검색 도구

Reachy Mini 원격 도구를 위한 공개 MCP 카나리(canary) 스페이스(Space)입니다.

도구를 추가하는 데는 단 하나의 명령만 필요합니다:

reachy-mini-conversation-app tool-spaces add pollen-robotics/reachy-mini-weather-tool

그 다음 평소처럼 앱을 시작하세요:

reachy-mini-conversation-app

이제 다음과 같이 물어보기만 하면 됩니다:

오늘 파리의 날씨는 어때?

아래에서는 도구(tool)란 무엇인지, 프로필(profile)이 로봇이 사용할 수 있는 것을 어떻게 제어하는지, 그리고 원격 경로(remote path)의 현재 한계는 무엇인지 살펴봅니다.

로봇과 대화할 때 여러분이 돌려받는 것은 단순히 음성만이 아닙니다. 그것은 대화에 반응하는 시스템입니다. 즉, 적용 가능한 경우 로봇이 움직이거나 비언어적으로 응답할 수 있습니다. 여기서 우리가 집중하고자 하는 부분은 이를 가능하게 하는 도구(tools)입니다. 도구란 모델이 대화 중에 수행할 수 있는 무언가입니다. 예를 들어 감정을 표현하거나, 머리를 움직이거나, 카메라를 통해 보는 것 등이 있습니다. 각 도구는 이름과 짧은 설명을 가지고 있습니다. 모델은 이를 읽고, 언제 도구가 유용할지 결정하며, 도구를 호출하고, 그 결과로 돌아온 값을 사용합니다.

현재 모든 도구는 로컬(local) 방식이며 앱 내부에 포함되어 있으며, 대부분 로봇의 신체와 관련된 것입니다:

도구	기능
move_head	머리 포즈(pose) 변경을 큐(queue)에 추가
dance / stop_dance	댄스 라이브러리에서 댄스를 재생하거나 중지
play_emotion / stop_emotion	녹화된 감정 클립을 재생하거나 중지
head_tracking	머리 추적(head-tracking) 오프셋 토글
camera	프레임을 캡처하고 분석
idle_do_nothing	유휴(idle) 차례에 명시적으로 아무것도 하지 않고 대기

코드 상의 도구는 **프로필(profile)**에서 활성화되기 전까지는 사용할 수 없습니다. 프로필은 여기서 중요한 두 개의 파일이 포함된 폴더입니다: instructions.txt (프롬프트 (prompt))와 tools.txt (활성화된 도구들 (tools)).

default 프로필은 전체 세트를 활성화합니다:

# profiles/default/tools.txt
dance
stop_dance
...

만약 이름이 tools.txt에 없다면, 모델은 해당 도구를 호출할 수 없습니다.

여러분만의 도구를 직접 작성할 수도 있습니다. 프로필(또는 external_tools/)에 Python 파일을 추가하고, 이름과 설명을 부여한 뒤, 그 이름을 tools.txt에 목록으로 작성하면 됩니다.

현재는 내장 도구 (built-in tools)와 사용자 정의 로컬 도구 (custom local tools)가 있으며, tools.txt가 어떤 도구를 활성화할지 결정합니다. 이는 로봇의 본체에 잘 작동하며 신뢰할 수 있는 코어 (core)를 작게 유지해 줍니다.

여기서 제약 사항은 모든 도구가 로컬 Python이어야 한다는 점입니다. move_head나 play_emotion 같은 경우에는 적절합니다. 이들은 하드웨어와 통신하며 앱에 속해야 하지만, 웹 검색, 날씨, 또는 조회 (lookups)와 같이 본체와는 아무런 관련이 없는 유용한 기능들이 많습니다. 이러한 기능들을 위해 모든 것을 로컬에 유지하는 것은 대부분 마찰 (friction)을 초래합니다.

원격 도구 (Remote tools)는 이미 가지고 있는 내장 도구 및 사용자 정의 로컬 도구와 함께 세 번째 종류를 추가하며, 자체적으로 게시, 공유 및 업데이트하기가 더 쉬운 기능들을 제공합니다:

external_tools/

이는 검색, 날씨, 조회와 같은 상태 비저장 (stateless) 기능에 적합합니다. 즉, 앱 자체를 건드리지 않고 반복적으로 개선하고 싶은 모든 것에 해당합니다. 또한 누구나 호환 가능한 Space를 게시할 수 있기 때문에, 도구를 공유하고 서로의 작업물을 기반으로 구축하기가 쉽습니다. 우리는 새로운 흐름을 테스트하기 위한 작은 테스트용 도구인 두 개의 카나리 도구 (canary tools)로 시작했습니다:

이 도구들은 전체 기능을 테스트하기에 충분합니다. Hub에서 설치하고, 원격 도구를 발견하며, 프로필별로 이를 활성화하고, 실시간 백엔드 (realtime backend)가 내장 도구와 정확히 동일하게 이를 호출하도록 합니다.

두 가지를 동시에 사용하려면, 동일한 프로필에 각 Space와 해당 도구 스택을 추가하십시오:

reachy-mini-conversation-app tool-spaces add pollen-robotics/reachy-mini-search-tool
reachy-mini-conversation-app tool-spaces add pollen-robotics/reachy-mini-weather-tool

이제 로봇은 동일한 대화 내에서 웹을 검색하고 날씨를 확인할 수 있으며, 이는 아래의 canary_web_search_weather 프로필이 수행하는 것과 정확히 일치합니다.

# 설치 + 활성 프로필에서 활성화
reachy-mini-conversation-app tool-spaces add <owner/space-name>
# 특정 프로필에서 활성화
...

add 명령은 Hub에서 Space를 검증하고, MCP 엔드포인트 (endpoint)를 조사하며, 도구를 발견하고, 기본적으로 활성 프로필의 tools.txt에 도구 ID를 추가합니다. REACHY_MINI_CUSTOM_PROFILE을 설정하지 않았다면 활성 프로필은 default입니다.

해당 단계를 건너뛰려면 --install-only를 사용하세요.

tools.txt는 문지기 역할을 합니다. 원격 도구 (remote tool)는 사용자가 원하는 내장 도구들과 함께 프로필의 tools.txt에 해당 ID가 나타나야만 활성화됩니다.

설치된 소스들은 다음 위치에 유지됩니다:

• 관리형 앱 모드 (managed app mode)의 경우: external_content/installed_tool_spaces.json
• 터미널 모드 (terminal mode)의 경우: installed_tool_spaces.json

설치된 각 Space는 슬러그 (slug)에서 파생된 로컬 별칭 (local alias)을 가지며, 이때 하이픈 (-), 점 (.), 슬래시 (/)는 언더스코어 (_)로 통합됩니다:

pollen-robotics/reachy-mini-search-tool → pollen_robotics_reachy_mini_search_tool

그 후 원격 도구들은 이중 언더스코어 (double underscore)를 사용하여 네임스페이스 (namespaced) 처리됩니다:

pollen_robotics_reachy_mini_search_tool__search_web
pollen_robotics_reachy_mini_weather_tool__get_day_brief

이를 통해 원격 도구의 이름이 내장 도구와 충돌하는 것을 방지하고, 동일한 프로필 내에서 여러 Space가 공존할 수 있도록 합니다.

구현 과정에서는 가능한 경우 중복되는 Space 이름 접두사를 제거하여, 장황한 원격 도구 이름을 더 깔끔한 로컬 ID로 변환합니다. 만약 접두사를 제거했을 때 동일한 Space 내의 두 도구 간에 충돌이 발생할 경우, 코드는 전체 네임스페이스가 적용된 이름을 기본값으로 사용합니다.

또한 레지스트리 (registry) 수준에서 중복 방지 검사가 수행됩니다: Tool.name 값은 병합된 전체 도구 세트 전체에서 고유해야 합니다. 만약 두 소스가 동일한 이름을 주장하면 앱은 즉시 오류를 발생시키며 중단됩니다 (fails fast).

이번 작업을 위해 우리는 전체 임바디드 (embodied) 도구 세트로부터 MCP 실험을 격리하기 위해 두 개의 집중적인 카나리 프로필 (canary profiles)을 생성했습니다.

첫 번째는 몇 가지 표현력 있는 도구들 (감정, 머리 움직임)을 유지하면서 그 위에 웹 검색을 추가한 것입니다:

# profiles/canary_web_search/tools.txt
play_emotion
stop_emotion
...

두 번째는 첫 번째와 동일하며, 검색과 함께 날씨 도구를 추가한 것입니다:

# profiles/canary_web_search_weather/tools.txt
play_emotion
stop_emotion
...

작은 물리적 도구 세트 덕분에 Reachy Mini는 웹에서 현재 질문에 대한 답을 찾는 동안에도 여전히 표현력 있게 반응할 수 있습니다.

원격 도구 배관 (remote-tool plumbing)은 도구들을 모델에 전달합니다. 프롬프트 (prompts)는 모델이 그 도구들을 어떻게 사용할지 결정합니다.

이러한 점은 '검색+날씨 (search-plus-weather)' 카나리 (canary) 모델에서 특히 두드러졌습니다. 다음과 같은 결합된 질문의 경우:

오늘 보르도에 재킷을 가져가야 할까요? 그리고 오늘 밤 시내에서 열리는 주요 행사가 있나요?

최소 세 가지 방식으로 처리될 수 있습니다: 날씨를 먼저 확인한 후 검색, 검색을 먼저 한 후 날씨 확인, 또는 동일한 턴 (turn)에서 둘 다 수행하는 방식입니다. 만약 프롬프트 (prompt)가 모호하면, 모델은 호출을 직렬화 (serialise)하여 불필요한 지연 시간 (latency)을 발생시킵니다. 따라서 카나리 프롬프트는 단순한 부수적 설정이 아니라 기능의 일부가 되었습니다.

[default_prompt]
## CANARY WEB SEARCH RULES
당신은 최신 웹 정보를 위한 하나의 원격 도구 (remote tool)를 가지고 있습니다.
...

[default_prompt]
## CANARY SEARCH AND WEATHER RULES
당신은 두 개의 원격 도구를 가지고 있습니다:
...

기능	지원 여부
공개된, MCP 호환 Gradio Spaces 설치 (표준 /gradio_api/mcp/ 엔드포인트)	✅
여러 Spaces를 동시에 설치	✅
tools.txt를 통한 프로필별 활성화	✅
네임스페이스가 지정된 원격 도구 ID (Namespaced remote tool IDs)	✅
백엔드에 구애받지 않는 등록 (OpenAI, Gemini, Hugging Face)	✅
로컬 앱으로 임의의 코드가 다운로드되지 않음	✅
...

두 가지 주목할 점이 있습니다. 첫째, Space는 실제로 MCP 서버처럼 동작해야 합니다. 도구 발견 (tool discovery)에 실패하면 설치도 실패합니다. 둘째, 프롬프트 지침은 병렬 호출 (parallel calls)을 권장할 수는 있지만, 이를 보장할 수는 없습니다. 만약 특정 유스케이스 (use case)에서 결정론적 오케스트레이션 (deterministic orchestration)이 중요하다면, 해당 로직은 프롬프트가 아닌 코드 내부로 옮겨야 합니다.

다른 사람들이 당신의 도구를 사용하게 하고 싶다면, 표준 MCP 엔드포인트를 노출하는 공개 Gradio Space로 게시하고, 네트워크 상에서 잘 작동하도록 도구를 상태가 없는 (stateless) 방식으로 유지하세요. Space의 설치 여부는 태그 (tags)가 아니라 이러한 런타임 동작 (runtime behavior)에 달려 있습니다.

설치를 위해 태그가 필수적인 것은 아니지만, 사람들이 호환 가능한 Space를 찾는 데 도움을 줍니다:

reachy-mini-tool

mcp

이제 앱은 하나의 레지스트리(registry)를 공유하는 세 가지 종류의 도구를 갖게 됩니다: 내장형(built-in), 로컬 커스텀(local custom), 그리고 원격 MCP 도구입니다. 프로필(profiles)은 여전히 특정 어시스턴트가 이 중 어떤 도구에 접근할 수 있는지를 결정합니다. 작고 신뢰할 수 있는 핵심(core)이 중심을 유지하는 동안, 그 주변의 선택적 기능들은 앱 자체를 건드리지 않고도 추가, 테스트 및 교체가 가능합니다.

우리가 지금 가장 궁금한 것은 사람들이 무엇을 만들어낼 것인가 하는 점입니다. 만약 도구 Space를 게시한다면, 다른 사람들이 찾을 수 있도록 reachy-mini-tool과 mcp 태그를 달아주세요.

Reachy Mini가 최종적으로 어떤 일을 할 수 있게 될지 정말 기대됩니다!

감사의 글: 이 포스트를 교정하고 워크플로(workflow) 테스트를 도와준 Fabien Danieau, 테스트를 도와준 Andres Marafioti, 그리고 원격 도구 워크플로를 형성하는 데 아이디어와 피드백을 준 Remi Fabre 및 Pollen Robotics 팀에게 깊은 감사를 드립니다.