Gradio로 MCP 서버 구축

Gradio는 이제 개발자들이 애플리케이션을 Model Context Protocol (MCP) 서버로 실행할 수 있게 하여, 대형 언어 모델(LLM)이 Gradio 앱을 도구로 호출할 수 있도록 합니다. 이 통합은 Gradio 앱 내의 모든 Python 함수를 표준화된 도구로 변환하여, Cursor, Cline, Claude Desktop과 같은 MCP 호환 클라이언트가 특정 계산을 수행하거나, 미디어를 생성하거나, 데이터를 처리하는 데 활용할 수 있게 합니다.

Gradio에서 MCP 서버 배포

개발자는 .launch() 메서드에서 mcp_server=True를 설정하거나 환경 변수 GRADIO_MCP_SERVER=True를 지정함으로써 Gradio 앱을 MCP 서버로 변환할 수 있습니다.

앱을 실행하면 표준 Gradio 웹 인터페이스와 MCP 서버가 동시에 시작되어 URL 엔드포인트(보통 http://your-server:port/gradio_api/mcp/sse)를 노출합니다. 이 엔드포인트는 MCP 클라이언트 설정에 추가할 수 있습니다. Gradio는 함수의 docstring을 자동으로 사용해 도구의 설명과 LLM을 위한 매개변수 스키마를 생성합니다.

Claude Desktop과 같이 Server-Sent Events(SSE)를 지원하지 않는 클라이언트의 경우, mcp-remote Node.js 도구를 브리지로 사용할 수 있습니다.

고급 MCP 기능

기본 도구 변환을 넘어, Gradio는 MCP 기능 전체를 구현할 수 있는 특수 데코레이터를 제공합니다:

  • MCP Tools: 함수가 기본적으로 도구로 등록되지만, @gr.mcp.tool() 데코레이터를 명시적으로 사용할 수 있습니다.
  • MCP Resources: @gr.mcp.resource() 데코레이터를 사용하면 개발자가 특정 데이터 소스를 LLM에 노출할 수 있습니다.
  • MCP Prompts: @gr.mcp.prompt() 데코레이터를 통해 재사용 가능한 프롬프트 템플릿을 정의할 수 있습니다.
  • MCP-Only Functions: gr.api()를 사용하면 MCP 서버에만 제공되고 Gradio 사용자 인터페이스에서는 숨겨진 함수를 만들 수 있습니다.

주요 통합 기능

자동 도구 변환 및 스키마 관리

Gradio 앱의 모든 API 엔드포인트는 자동으로 MCP 도구로 변환됩니다. 생성된 이름, 설명 및 입력 스키마는 /gradio_api/mcp/schema 엔드포인트나 앱 하단의 "View API" 링크를 통해 확인할 수 있습니다.

파일 및 데이터 처리

통합에는 파일 데이터 변환을 위한 자동 처리가 포함되며, 다음과 같습니다:

  • Base64 인코딩된 문자열을 파일 데이터로 변환합니다.
  • 이미지 파일을 올바른 형식으로 처리하고 반환합니다.
  • 임시 파일 저장소를 관리합니다.
  • 로컬 파일 접근을 위한 자동 파일 업로드 MCP 서버를 지원합니다.

성능 분석

Gradio는 MCP 도구와 API 엔드포인트에 대한 내장 추적 기능을 제공합니다. "View API" 페이지에서는 성공률, 지연 시간 백분위수, 요청 수를 색상 표시(성공 100%는 초록색, 0%는 빨간색)와 함께 보여주어 개발자가 도구 신뢰성을 최적화할 수 있도록 돕습니다.

Hugging Face Spaces에서 호스팅 및 인증

개발자는 Gradio 애플리케이션을 Hugging Face Spaces에 배포함으로써 MCP 서버를 무료로 호스팅할 수 있습니다.

비공개 Spaces의 경우, MCP 클라이언트 설정에 Bearer 토큰을 추가하여 인증을 지원합니다:

{
  "mcpServers": {
    "gradio": {
      "url": "https://your-private-space.hf.space/gradio_api/mcp/sse",
      "headers": {
        "Authorization": "Bearer <YOUR-HUGGING-FACE-TOKEN>"
      }
    }
  }
}

Sources