Building MCP Servers with Gradio

Gradio now enables developers to launch their applications as Model Context Protocol (MCP) servers, allowing Large Language Models (LLMs) to call Gradio apps as tools. This integration transforms any Python function within a Gradio app into a standardized tool that MCP-compatible clients—such as Cursor, Cline, or Claude Desktop—can utilize to perform specific calculations, generate media, or process data.

Deploying an MCP Server in Gradio

Developers can convert a Gradio app into an MCP server by setting mcp_server=True within the .launch() method or by setting the environment variable GRADIO_MCP_SERVER=True.

When launched, the app starts both the standard Gradio web interface and an MCP server, exposing a URL endpoint (typically http://your-server:port/gradio_api/mcp/sse) that can be added to an MCP client's configuration. Gradio automatically uses the function's docstring to generate the tool's description and parameter schemas for the LLM.

For clients that do not support Server-Sent Events (SSE), such as Claude Desktop, the mcp-remote Node.js tool can be used as a bridge.

Advanced MCP Capabilities

Beyond basic tool conversion, Gradio provides specialized decorators to implement the full range of MCP features:

  • MCP Tools: While functions are registered as tools by default, the @gr.mcp.tool() decorator can be used explicitly.
  • MCP Resources: The @gr.mcp.resource() decorator allows developers to expose specific data sources to the LLM.
  • MCP Prompts: The @gr.mcp.prompt() decorator enables the definition of reusable prompt templates.
  • MCP-Only Functions: Using gr.api(), developers can create functions that are available to the MCP server but remain hidden from the Gradio user interface.

Key Integration Features

Automatic Tool Conversion and Schema Management

Every API endpoint in a Gradio app is automatically converted into an MCP tool. The resulting names, descriptions, and input schemas are accessible via the /gradio_api/mcp/schema endpoint or through the "View API" link in the app's footer.

File and Data Handling

The integration includes automated handling for file data conversions, including:

  • Converting base64-encoded strings to file data.
  • Processing and returning image files in the correct format.
  • Managing temporary file storage.
  • Support for an automatic file upload MCP server for local file access.

Performance Analytics

Gradio includes built-in tracking for MCP tools and API endpoints. The "View API" page displays success rates, latency percentiles, and request counts, with color-coded indicators (green for 100% success, red for 0%) to help developers optimize tool reliability.

Hosting and Authentication on Hugging Face Spaces

Developers can host their MCP servers for free by publishing Gradio applications to Hugging Face Spaces.

For private Spaces, authentication is supported by adding a Bearer token to the MCP client configuration:

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

Sources