Adding MCP Tools to Reachy Mini

🖼️ 인포그래픽

Adding MCP Tools to Reachy Mini 내용을 설명하는 본문 이미지

🖼️ 4컷 인포그래픽

💡 한 줄 요약

리치 미니 대화 앱은 공개 허깅페이스 스페이스의 MCP 도구를 프로필별로 연결해, 로컬 코드를 수정하거나 내려받지 않고도 날씨 조회와 웹 검색 같은 기능을 추가할 수 있게 됐다.

📌 핵심 요약

리치 미니는 기존의 내장 로봇 도구와 사용자 정의 로컬 도구에 더해, 공개 허깅페이스 스페이스에서 실행되는 원격 MCP 도구를 지원한다.
도구 설치 명령은 스페이스 검증, MCP 엔드포인트 확인, 도구 탐색을 수행하며, 기본적으로 발견한 도구 식별자를 활성 프로필의 tools.txt에 추가한다.
프로필의 tools.txt는 내장·로컬·원격 도구 모두에 대한 최종 활성화 관문이며, 목록에 없는 도구는 모델이 호출할 수 없다.
원격 도구에는 스페이스별 네임스페이스가 적용되고 전체 레지스트리에서 이름 중복을 검사해, 여러 스페이스와 내장 도구가 함께 사용될 때의 충돌을 방지한다.
현재 공개 MCP 호환 Gradio 스페이스만 설치할 수 있으며, 비공개 스페이스·비 Gradio 스페이스·임의 MCP URL은 지원하지 않고 프롬프트만으로 병렬 호출을 보장할 수도 없다.

🧩 주요 포인트

리치 미니는 기존의 내장 로봇 도구와 사용자 정의 로컬 도구에 더해, 공개 허깅페이스 스페이스에서 실행되는 원격 MCP 도구를 지원한다.
도구 설치 명령은 스페이스 검증, MCP 엔드포인트 확인, 도구 탐색을 수행하며, 기본적으로 발견한 도구 식별자를 활성 프로필의 tools.txt에 추가한다.
프로필의 tools.txt는 내장·로컬·원격 도구 모두에 대한 최종 활성화 관문이며, 목록에 없는 도구는 모델이 호출할 수 없다.
원격 도구에는 스페이스별 네임스페이스가 적용되고 전체 레지스트리에서 이름 중복을 검사해, 여러 스페이스와 내장 도구가 함께 사용될 때의 충돌을 방지한다.
현재 공개 MCP 호환 Gradio 스페이스만 설치할 수 있으며, 비공개 스페이스·비 Gradio 스페이스·임의 MCP URL은 지원하지 않고 프롬프트만으로 병렬 호출을 보장할 수도 없다.

🧠 상세 정리

1. 원격 MCP 도구를 추가한 목적

리치 미니 대화 앱은 이제 공개 허깅페이스 스페이스에 호스팅된 도구를 MCP로 호출할 수 있다. 사용자는 애플리케이션 코드를 직접 편집하지 않고도 허브의 스페이스를 추가해 날씨 확인이나 웹 검색 같은 새로운 능력을 로봇에 제공할 수 있다. 실제 도구는 로컬 컴퓨터가 아니라 해당 스페이스에서 계속 실행되므로, 도구의 임의 코드를 사용자 환경으로 내려받지 않는다. 예시로 날씨 도구 스페이스를 명령 한 번으로 추가한 뒤 평소처럼 앱을 실행하면, 파리의 오늘 날씨처럼 현재 정보가 필요한 질문을 할 수 있다. 또한 호환되는 도구를 직접 스페이스로 공개해 다른 사용자와 공유하는 경로도 열렸다.

2. 기존 도구와 프로필의 통제 구조

리치 미니의 도구는 모델이 대화 도중 실행할 수 있는 동작으로, 각각 이름과 짧은 설명을 가진다. 모델은 이 정보를 읽고 필요한 도구를 선택한 뒤 호출 결과를 응답에 활용하며, 기존 내장 도구는 머리 자세 변경, 춤과 감정 재생, 헤드 트래킹, 카메라 분석, 명시적인 유휴 상태처럼 주로 로봇의 신체와 관련돼 있다. 그러나 코드에 도구가 존재한다는 사실만으로는 사용할 수 없고, 프로필의 tools.txt에 이름이 등록돼야 모델이 호출할 수 있다. 프로필에는 지시문을 담은 instructions.txt와 활성 도구를 정하는 tools.txt가 있으며, 기본 프로필은 전체 내장 도구를 활성화한다. 사용자가 프로필 또는 external_tools 디렉터리에 작성한 로컬 파이썬 도구도 이름과 설명을 정의한 후 tools.txt에 등록해야 한다.

3. 로컬 도구 방식의 한계와 역할 분리

기존 구조에서는 모든 도구가 로컬 파이썬으로 존재해야 했기 때문에, 하드웨어와 직접 통신하는 머리 이동이나 감정 재생에는 적합했지만 웹 검색·날씨·정보 조회에는 불필요한 마찰이 있었다. 이런 비신체 기능을 공유하려면 파이썬 파일을 전달해야 했고, 업데이트할 때마다 파일을 다시 보내야 하며, 독립적인 기능인데도 애플리케이션을 수정해야 했다. 원격 도구는 이를 보완하는 세 번째 유형으로 도입되어, 신뢰가 필요한 로봇 내장 도구는 로컬에 남기고 공유와 독립 업데이트가 필요한 기능은 공개 스페이스에서 운영하도록 구분한다. 일회성 사용자 정의 기능은 기존처럼 external_tools에서 로컬로 유지할 수 있다. 원격 방식은 상태를 보존할 필요가 적은 검색, 날씨, 조회 기능처럼 앱 자체를 건드리지 않고 반복 개선하려는 기능에 적합하다.

4. 설치·활성화·삭제 절차와 저장 정보

tool-spaces add 명령은 허브에서 스페이스를 검증하고 표준 MCP 엔드포인트를 탐색한 뒤, 제공되는 도구를 발견하는 과정을 수행한다. 기본 동작은 발견한 원격 도구 식별자를 현재 프로필의 tools.txt에 추가하는 것이며, 별도 환경 설정이 없다면 활성 프로필은 default이다. 사용자는 --profile 옵션으로 특정 프로필에 활성화하거나, --install-only 옵션으로 스페이스만 설치하고 도구 활성화는 생략할 수 있다. 설치된 스페이스는 list 명령으로 확인하고 remove 명령으로 제거할 수 있으며, 관리형 앱 모드에서는 installed_tool_spaces.json에, 터미널 모드에서는 external_content/installed_tool_spaces.json에 설치 출처가 저장된다. 설치가 끝났더라도 원격 도구 식별자가 해당 프로필의 tools.txt에 없으면 모델은 그 도구를 호출할 수 없다.

5. 원격 도구 이름과 충돌 방지

각 스페이스에는 슬러그에서 파생한 로컬 별칭이 부여되며, 하이픈·마침표·슬래시는 밑줄로 통합된다. 원격 도구의 로컬 식별자는 이 별칭과 실제 도구 이름을 이중 밑줄로 연결한 네임스페이스 형식을 사용하므로, 검색 도구와 날씨 도구처럼 여러 스페이스를 한 프로필에 함께 넣을 수 있다. 구현은 원격 도구 이름에 스페이스 이름이 중복되어 붙은 경우 가능한 범위에서 불필요한 접두사를 제거해 더 간결한 식별자를 만든다. 다만 접두사를 제거했을 때 같은 스페이스 안의 도구끼리 충돌한다면 완전한 네임스페이스 이름으로 되돌아간다. 최종적으로 병합된 전체 도구 집합에서도 모든 Tool.name 값이 고유해야 하며, 서로 다른 출처가 같은 이름을 주장하면 앱은 즉시 실패해 모호한 호출을 막는다.

6. 검색·날씨 카나리 프로필의 구성

새 원격 경로를 전체 신체 도구 집합과 분리해 시험하기 위해 두 개의 집중된 카나리 프로필이 만들어졌다. canary_web_search 프로필은 감정 재생과 중지, 유휴 동작, 머리 이동 등 소수의 표현 도구를 유지하면서 웹 검색 원격 도구를 추가한다. canary_web_search_weather 프로필은 같은 신체 도구와 웹 검색에 날씨 요약 도구까지 더해, 한 대화에서 검색과 날씨 확인을 함께 처리한다. 이를 위해 검색 스페이스와 날씨 스페이스를 각각 추가하면 두 스페이스의 도구가 동일한 프로필에 함께 쌓인다. 제한된 신체 도구 구성을 유지한 덕분에 리치 미니는 최신 웹 정보를 답하면서도 감정이나 머리 움직임을 통한 비언어적 반응을 계속 표현할 수 있다.

7. 프롬프트가 도구 선택과 응답 품질에 미치는 영향

원격 도구 등록은 모델이 도구를 볼 수 있게 만들지만, 어떤 상황에서 어떤 도구를 어떤 순서로 사용할지는 프로필 프롬프트가 좌우한다. 웹 검색 전용 프롬프트는 최신 사실, 뉴스, 실시간 가용성처럼 변할 수 있는 정보를 물을 때 검색을 사용하고, 결과가 충분하면 도구 설명 없이 짧고 직접적인 음성형 답변을 하도록 지시한다. 검색과 날씨를 함께 쓰는 프롬프트는 기온·비·일출·일몰·옷차림 조언에는 날씨 도구를, 뉴스·행사·영업시간·여행 정보·경보에는 웹 검색을 사용하도록 역할을 구분한다. 질문에 날씨와 현재 정보가 함께 들어 있으면 한 도구의 결과가 다른 검색 조건에 필요하지 않은 한 같은 턴에서 두 도구를 병렬로 호출하고, 날씨를 먼저 말한 뒤 행사나 뉴스를 자연스럽게 이어서 하나의 짧은 답으로 합치도록 요구한다. 행사 검색 결과가 구체적이면 실제 행사명·장소·제목을 답하고, 결과가 없으면 다른 사이트를 보라고 돌리지 말고 주목할 행사를 찾지 못했다고 명확히 말하도록 규정한다.

8. 현재 지원 범위와 남은 제약

현재는 표준 /gradio_api/mcp/ 엔드포인트를 제공하는 공개 MCP 호환 Gradio 스페이스를 슬러그로 설치할 수 있고, 여러 스페이스의 동시 사용과 프로필별 활성화, 원격 도구 네임스페이스를 지원한다. 도구 등록은 OpenAI, Gemini, Hugging Face 백엔드에 종속되지 않으며, 로컬 앱으로 임의 코드를 다운로드하지 않는 구조다. 반면 비공개 또는 인증이 필요한 스페이스, 비 Gradio 스페이스, 임의의 원시 MCP URL과 허깅페이스 외부 MCP 서버는 지원되지 않는다. 스페이스가 실제 MCP 서버처럼 동작하지 않아 도구 탐색에 실패하면 설치도 실패하며, 설치 가능 여부는 태그가 아니라 실행 중인 엔드포인트의 동작으로 결정된다. 프롬프트는 병렬 호출을 유도할 수 있을 뿐 보장하지 않으므로, 결정적인 실행 순서나 병렬성이 필요한 경우 해당 조정 로직을 프롬프트가 아니라 코드로 옮겨야 한다.

🧾 핵심 주장 / 시사점

tools.txt를 내장·로컬·원격 도구의 공통 관문으로 유지함으로써, 기능의 실행 위치가 달라져도 프로필 단위의 권한 통제 방식은 바뀌지 않는다.
하드웨어 제어는 로컬에 남기고 검색·날씨 같은 독립 기능은 원격 스페이스로 분리해, 신뢰가 필요한 로봇 핵심부와 공유·업데이트가 잦은 기능의 책임을 구분한다.
도구를 연결하는 기술만으로는 효율적인 복합 질의를 보장할 수 없으며, 도구 역할·병렬 호출 조건·결과 결합 방식을 프롬프트에 명시하되 결정성이 필요하면 코드로 구현해야 한다.

✅ 액션 아이템

공개 MCP 호환 Gradio 스페이스만 설치 대상으로 정하고, 비공개·비 Gradio·임의 URL 경로는 사용하지 않도록 사전에 배제한다.
도구 설치 시 스페이스 검증·MCP 엔드포인트 확인·도구 탐색을 순차 실행해 발견 식별자를 활성 프로필의 tools.txt에 추가하고 호출 가능 범위를 다시 점검한다.
tools.txt를 내장·로컬·원격 공통의 최종 활성화 관문으로 두고, 스페이스별 네임스페이스와 전체 레지스트리 중복 검사 결과로 충돌을 정리한다.