Valeo Connector (MCP) — MVP

Valeo Health 회원 데이터를 Claude 커넥터로 변환하는 원격 MCP 서버로, Function Health 커넥터와 동일한 방식으로 작동합니다.

• 의존성 제로. 표준 라이브러리 Python만 사용합니다. 기본 macOS python3에서 실행됩니다.

• 전송 방식: Streamable HTTP (MCP 스펙 2025-06-18), 단일 /mcp 엔드포인트.

• 인증: 아직 없음(데모). 모든 데이터는 sample_data.py에서 제공됩니다.

• 읽기 전용. 모든 도구에 readOnlyHint: true가 주석으로 표시되어 있습니다.

라이브 데모 엔드포인트 (샘플 데이터, 인증 없음):

https://valeo-connector.onrender.com/mcp

Claude의 Settings > Connectors > Add custom connector에서 해당 URL을 추가하세요. 상태 확인: https://valeo-connector.onrender.com/health. 무료 인스턴스이므로 약 15분간 유휴 상태면 절전 모드로 전환되며, 절전 후 첫 호출은 30~60초가 소요됩니다 — 데모 전에 상태 확인 URL을 열어预热하세요.

파일

Related MCP server: health-mcp

도구

샘플 패널의 건강 카테고리: 심장, 대사, 비타민 및 미네랄, 갑상선, 간, 신장, 혈액 및 면역, 호르몬, 남성 건강.

Function Health와 마찬가지로 이 커넥터는 의도적으로 요약 수준 데이터만 노출합니다 — 수치, 카테고리, 플래그 및 방향성("비타민 D, 낮음, 유의미")만 제공하며 원시 검사 수치는 절대 제공하지 않습니다.

아이콘

서버는 MCP 아이콘 필드(SEP-973)에 따라 serverInfo에 정사각형 브랜드 아이콘을 데이터 URI로 광고하며, /icon.png, /icon-128.png, /favicon.ico에서도 제공합니다.

Claude.ai는 현재 사용자 지정 커넥터에 대해 이를 렌더링하지 않습니다 — 사용자 지정 커넥터는 서버가 선언한 내용과 관계없이 일반 아이콘을 표시합니다 (claude-ai-mcp#152). 선언하는 데 비용이 들지 않으며 해당 기능이 출시되는 날 바로 작동합니다. 오늘 브랜드 아이콘을 사용하려면 Connectors Directory 등록이 필요하며, 제출 시 아이콘이 업로드됩니다.

실행

./run.sh

그런 다음 다른 터미널에서:

python3 test_server.py

상태 확인: http://127.0.0.1:8787/health

데모 경로 1 — Claude Code (가장 빠름, 약 30초)

.mcp.json은 이미 http://127.0.0.1:8787/mcp를 가리키고 있습니다. 서버를 시작하고, 이 폴더에서 Claude Code를 열고, 프롬프트가 표시되면 valeo 서버를 승인한 후 다음을 물어보세요:

내 검사 결과는 어떤가요, 그리고 프로그램은 어떻게 진행되고 있나요?

데모 경로 2 — Claude 구독이 있는 모든 사용자 (공개 URL)

Claude의 서버가 사용자의 엔드포인트를 호출하므로 안정적인 공개 HTTPS URL이 필요합니다. localhost나 재시작 시 사라지는 터널로는 충분하지 않습니다. 저장소를 배포한 후 유료 Claude 요금제(Pro, Max, Team, Enterprise) 사용자는 누구나 직접 추가할 수 있습니다:

Claude → Settings → Connectors → Add custom connector → 붙여넣기

https://valeo-connector.onrender.com/mcp

배포

render.yaml과 Dockerfile이 모두 저장소에 있으며 server.py를 변경 없이 실행합니다.

Render (CLI 불필요, 무료, 카드 불필요):

1. 이 README 상단의 Deploy to Render 버튼을 클릭하거나, render.com → New → Blueprint → 이 저장소 선택 → Apply. 어느 쪽이든 render.yaml을 읽습니다.

2. GitHub로 로그인하고 저장소 접근을 승인합니다.

3. https://valeo-connector.onrender.com이 생성됩니다 (이름이 사용 중이면 Render가 접미사를 추가할 수 있습니다). 커넥터 URL은 여기에 /mcp를 더한 것입니다. main에 푸시하면 자동 재배포됩니다.

Claude에 연결하기 전에 배포를 검증하세요:

python3 test_server.py https://valeo-connector.onrender.com

22개 검사 모두 로컬에서와 동일하게 라이브 URL에서 통과해야 합니다.

무료 인스턴스는 약 15분 유휴 후 절전 모드로 전환되므로, 절전 후 첫 호출은 30~60초가 소요됩니다 (Claude의 도구 타임아웃은 300초이므로 여전히 작동합니다 — 다만 느리게 느껴질 뿐입니다). $7 요금제 또는 Valeo 자체 인프라를 사용하면 이 문제가 해결됩니다.

모든 컨테이너 호스트 (Cloud Run, Fly, Railway)는 Dockerfile로 작동합니다. HOST=0.0.0.0을 설정하세요. 서버는 환경에서 PORT를 읽습니다.

결국 이 서비스는 Valeo 자체 도메인에서 운영되어야 합니다 — Function Health는 https://services.functionhealth.com/ai-chat/mcp에서 자체 서비스를 제공합니다.

URL을 공유하기 전에 알아야 할 두 가지

1. 아직 인증이 없으므로 모든 사용자가 동일한 가상 회원 데이터를 봅니다. 데모에는 적합하며 서버 자체의 Claude 지침에도 명시되어 있습니다. 실제 회원 데이터를 이 서비스에 연결하기 전에 반드시 변경해야 하는 유일한 사항입니다.

2. Claude의 Connectors Directory에 등록하는 것은 별도의 단계입니다 — Anthropic에 신청해야 합니다. 등록이 없어도 커넥터는 작동합니다. 다만 사용자가 디렉터리에서 찾는 대신 URL을 직접 입력하면 됩니다.

MVP 이후 추가할 사항

1. OAuth 2.0 — 각 회원이 자신의 데이터만 볼 수 있도록 합니다. Claude는 Dynamic Client Registration을 지원하며, 호스팅된 표면의 콜백은 https://claude.ai/api/mcp/auth_callback입니다. /.well-known/oauth-protected-resource(RFC 9728)를 제공하고 토큰 범위를 지정하세요 (read:labs, read:programs, read:appointments).

2. 실제 데이터: sample_data.py를 토큰에 연결된 인증된 Valeo API 호출로 교체합니다.

3. 안정적인 호스팅: 의존성이 없으므로 모든 Python 호스트에서 작동합니다.

4. 문서 페이지: Function Health와 같은 문서 페이지를 만들고 Connectors Directory에 제출합니다.

알아두면 좋은 제한 사항

의학적 조언이 아닙니다. 요약 수준 데이터만 제공합니다.