Remote MCP Server

Xano 통합을 통한 Snappy MCP 서버

도구 관리, 세션 추적 및 OAuth를 위한 Xano 데이터베이스 통합 기능을 갖춘 Cloudflare Workers 기반 원격 MCP 서버입니다. 이제 최신 Streamable HTTP 전송 프로토콜(2024년 11월 5일 기준)을 완벽하게 지원합니다.

지역적으로 개발하다

지엑스피1

브라우저에서 http://localhost:8787/ 열 수 있어야 합니다.

MCP 서버에 연결하세요

MCP 검사기 사용(레거시)

이전 SSE 전송을 통해 새로운 MCP API를 탐색하려면 MCP Inspector를 사용할 수 있습니다.

• npx @modelcontextprotocol/inspector 로 시작하세요
• 검사기 내에서 전송 유형을 SSE 로 전환하고 연결할 MCP 서버의 URL로 http://localhost:8787/sse 입력한 후 "연결"을 클릭합니다.
• (가상) 사용자/비밀번호 로그인 화면으로 이동합니다. 이메일 주소와 비밀번호를 입력하여 로그인하세요.
• MCP 검사기로 다시 돌아가서 정의된 도구를 나열하고 호출할 수 있습니다!

Workers AI Playground(스트리밍 가능 HTTP) 사용

최신 Streamable HTTP 전송 프로토콜로 테스트하려면:

1. Workers AI Playground를 방문하세요
2. MCP 서버에 연결하라는 메시지가 표시되면 엔드포인트 URL을 입력하세요.
   https://remote-mcp-server.robertjboulos.workers.dev/mcp
   또는 로컬 테스트를 위해:
   http://localhost:8787/mcp
3. 메시지가 표시되면 인증 자격 증명을 제공하세요.
   • auth_token : Xano 인증 토큰
   • user_id : Xano 사용자 ID
4. Playground는 새로운 프로토콜을 사용하여 세션 관리를 자동으로 처리합니다.

Claude Desktop을 로컬 MCP 서버에 연결하세요

레거시 SSE 운송

이전 SSE 전송을 사용하여 연결하려면 Anthropic의 빠른 시작을 따르고 Claude Desktop에서 설정 > 개발자 > 구성 편집으로 이동하여 구성 파일을 찾으세요.

텍스트 편집기에서 파일을 열고 다음 구성으로 바꾸세요.

이렇게 하면 로컬 프록시가 실행되고 Claude가 HTTP를 통해 MCP 서버와 통신할 수 있습니다.

스트리밍 가능한 HTTP 전송(권장)

Claude Desktop에서 더 새롭고 효율적인 Streamable HTTP 전송을 사용하려면 대신 /mcp 엔드포인트를 사용하도록 구성을 업데이트하세요.

YOUR_XANO_AUTH_TOKEN 과 YOUR_USER_ID 실제 자격 증명으로 바꾸세요.

Claude를 열면 브라우저 창이 열리고 로그인할 수 있습니다. 오른쪽 하단에 사용 가능한 도구가 표시됩니다. 오른쪽 프롬프트가 나타나면 Claude가 도구를 호출할지 묻습니다.

Xano 통합

이 MCP 서버는 다음을 위한 백엔드로 Xano를 사용합니다.

1. 도구 관리 : Xano의 ____mcp_tools 테이블에 도구를 정의하면 해당 도구가 MCP 서버에 자동으로 등록됩니다.
2. 세션 추적 : 모든 MCP 세션은 고유한 세션 ID를 사용하여 ___mcp_sessions 테이블에서 추적됩니다.
3. OAuth 인증 : OAuth 토큰과 상태는 Xano의 ___oauth_tokens 및 ___oauth_states 테이블에 저장됩니다.
4. 로깅 : 모든 MCP 요청은 ___mcp_logs 테이블에 기록됩니다.

스트리밍 가능한 HTTP 구현

이 서버는 다음 기능을 갖춘 최신 Model Context Protocol Streamable HTTP 전송(2024-11-05)을 구현합니다.

인증 방법

서버는 최대 호환성을 위해 여러 인증 메커니즘을 지원합니다.

1. URL 매개변수 : ?auth_token=xxx&user_id=yyy (레거시 방법)
2. 권한 부여 헤더 : 권한 부여: x-user-id 헤더가 있는 Authorization: Bearer xxx (현대 방식)
3. 요청 본문 : 인증 매개변수는 초기화 페이로드에 포함될 수 있습니다.

세션 관리

서버는 최신 사양에 따라 세션 ID를 처리합니다.

1. 세션 생성 : 서버는 새 연결에 대해 고유한 세션 ID를 생성합니다.
2. 세션 추적 : 클라이언트는 이 ID를 저장하고 향후 요청에 ?sessionId=xxx 로 포함합니다.
3. 상태 지속성 : 각 세션은 Xano에서 자체 상태를 유지하며 이는 요청 간에 지속됩니다.

프로토콜 준수

구현에는 다음에 대한 적절한 지원이 포함됩니다.

1. 통합 메시지 엔드포인트 : /mcp/message 엔드포인트 패턴 지원
2. 프로토콜 헤더 : 모든 응답에는 MCP-Available-Transports 와 같은 적절한 헤더가 포함됩니다.
3. SSE 스트리밍 : 스트리밍 응답에 대한 향상된 SSE 지원
4. 응답 형식 : 프로토콜별 확장이 포함된 표준 JSON-RPC 2.0 형식

Xano 설정

1. 필요한 테이블이 포함된 Xano 프로젝트를 만듭니다(데이터베이스 스키마 참조)
2. 다음에 대한 API 엔드포인트를 만듭니다.
   • /api/tools - GET - 모든 도구 나열
   • /api/tools/execute/{tool_name} - POST - 특정 도구 실행
   • /api/sessions - POST - 새 세션 생성
   • /api/sessions/update-activity - PUT - 세션 활동 업데이트
   • /api/oauth/tokens - POST - OAuth 토큰 저장
   • /api/oauth/tokens/{user_id}/{provider} - GET - OAuth 토큰 가져오기
   • /api/oauth/states - POST - OAuth 상태 저장
   • /api/oauth/states/{state} - GET - OAuth 상태 검증
   • /api/logs - POST - MCP 요청 기록

Cloudflare에 배포

1. npx wrangler kv namespace create OAUTH_KV
2. wrangler.jsonc 에 kv 네임스페이스 ID를 추가하려면 지침을 따르세요.
3. wrangler.jsonc 의 XANO_API_KEY 변수에 Xano API 키를 추가합니다.
4. npm run deploy

원격 MCP 클라이언트에서 새로 배포된 원격 MCP 서버를 호출합니다.

위의 "로컬에서 개발"에서 한 것처럼 MCP 검사기를 실행합니다.

npx @modelcontextprotocol/inspector@latest

그런 다음 검사기에 Worker의 workers.dev URL(예: worker-name.account-name.workers.dev/sse )을 연결할 MCP 서버의 URL로 입력하고 "연결"을 클릭합니다.

이제 원격 MCP 클라이언트에서 MCP 서버에 연결되었습니다.

Claude Desktop을 원격 MCP 서버에 연결하세요

Claude 구성 파일을 업데이트하여 workers.dev URL(예: worker-name.account-name.workers.dev/sse )을 가리키고 Claude를 다시 시작합니다.

디버깅

문제가 발생하면 Claude를 다시 시작하거나 다음 명령을 사용하여 명령줄에서 MCP 서버에 직접 연결을 시도하면 도움이 될 수 있습니다.

드물지만 ~/.mcp-auth 에 추가된 파일을 지우는 것이 도움이 될 수 있습니다.