The way to Construct an MCP Server with Gradio

Updated! (September 2025) This post has been updated with the newest Gradio MCP features including Resources, Prompts, enhanced authentication, and plenty of more.

Gradio is a Python library utilized by greater than 1 million developers every month to construct interfaces for machine learning models. Beyond just creating UIs, Gradio also exposes API capabilities and — now! — Gradio apps may be launched Model Context Protocol (MCP) servers for LLMs. Which means your Gradio app, whether it’s a picture generator or a tax calculator or something else entirely, may be called as a tool by an LLM.

This guide will show you easy methods to use Gradio to construct an MCP server in only just a few lines of Python.

Prerequisites

If not already installed, please install Gradio with the MCP extra:

pip install "gradio[mcp]"

This may install the mandatory dependencies, including the mcp package. You may also need an LLM application that supports tool calling using the MCP protocol, reminiscent of Claude Desktop, Cursor, or Cline (these are generally known as “MCP Clients”).

Why Construct an MCP Server?

An MCP server is a standardized option to expose tools in order that they may be utilized by LLMs. An MCP server can provide LLMs with every kind of additional capabilities, reminiscent of the power to generate or edit images, synthesize audio, or perform specific calculations reminiscent of prime factorize numbers.

Gradio makes it easy to construct these MCP servers, turning any Python function right into a tool that LLMs can use.

Example: Counting Letters in a Word

LLMs are famously not great at counting the variety of letters in a word (e.g., the variety of “r”s in “strawberry”). But what if we equip them with a tool to assist? Let’s start by writing a straightforward Gradio app that counts the variety of letters in a word or phrase:

import gradio as gr

def letter_counter(word, letter):
    """Count the occurrences of a selected letter in a word.
    
    Args:
        word: The word or phrase to research
        letter: The letter to count occurrences of
        
    Returns:
        The variety of times the letter appears within the word
    """
    return word.lower().count(letter.lower())

demo = gr.Interface(
    fn=letter_counter,
    inputs=["text", "text"],
    outputs="number",
    title="Letter Counter",
    description="Count how repeatedly a letter appears in a word"
)

demo.launch(mcp_server=True)

Notice that we have now set mcp_server=True in .launch(). That is all that is needed on your Gradio app to function an MCP server! Now, if you run this app, it is going to:

1. Start the regular Gradio web interface
2. Start the MCP server
3. Print the MCP server URL within the console

The MCP server can be accessible at:

http://your-server:port/gradio_api/mcp/sse

Gradio mechanically converts the letter_counter function into an MCP tool that may be utilized by LLMs. The docstring of the function is used to generate the outline of the tool and its parameters.

All you should do is add this URL endpoint to your MCP Client (e.g., Cursor, Cline, or Tiny Agents), which usually means pasting this config within the settings:

{
  "mcpServers": {
    "gradio": {
      "url": "http://your-server:port/gradio_api/mcp/sse"
    }
  }
}

Some MCP Clients, notably Claude Desktop, don’t yet support SSE-based MCP Servers. In those cases, you should utilize a tool reminiscent of mcp-remote. First install Node.js. Then, add the next to your personal MCP Client config:

{
  "mcpServers": {
    "gradio": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://your-server:port/gradio_api/mcp/sse"
      ]
    }
  }
}

(By the best way, you’ll find the precise config to copy-paste by going to the “View API” link within the footer of your Gradio app, after which clicking on “MCP”).

Recent Major Improvements

Gradio has recently added several powerful features to MCP servers. For an in depth overview of 5 major improvements including seamless local file support, real-time progress notifications, OpenAPI to MCP transformation, enhanced authentication, and customizable tool descriptions, take a look at our dedicated blog post: Five Big Improvements to Gradio MCP Servers.

Advanced MCP Features

MCP Resources and Prompts

Beyond tools, MCP supports resources (for exposing data) and prompts (for outlining reusable templates). Gradio provides decorators to simply create MCP servers with all three capabilities. You may read more in our dedicated guide, here:

import gradio as gr

@gr.mcp.tool()  
def add(a: int, b: int) -> int:
    """Add two numbers"""
    return a + b

@gr.mcp.resource("greeting://{name}")
def get_greeting(name: str) -> str:
    """Get a customized greeting"""
    return f"Hello, {name}!"

@gr.mcp.prompt()
def greet_user(name: str, style: str = "friendly") -> str:
    """Generate a greeting prompt"""
    styles = {
        "friendly": "Please write a warm, friendly greeting",
        "formal": "Please write a proper, skilled greeting", 
        "casual": "Please write an informal, relaxed greeting",
    }
    return f"{styles.get(style, styles['friendly'])} for somebody named {name}."

demo = gr.TabbedInterface(
    [
        gr.Interface(add, [gr.Number(value=1), gr.Number(value=2)], gr.Number()),
        gr.Interface(get_greeting, gr.Textbox("Abubakar"), gr.Textbox()),
        gr.Interface(greet_user, [gr.Textbox("Abubakar"), gr.Dropdown(choices=["friendly", "formal", "casual"])], gr.Textbox()),
    ],
    ["Add", "Get Greeting", "Greet User"]
)

demo.launch(mcp_server=True)

MCP-Only Functions

Gradio also lets you create functions that only appear within the MCP server (not within the UI) using gr.api():

import gradio as gr

def slice_list(lst: list, start: int, end: int) -> list:
    """
    A tool that slices a listing given a start and end index.
    Args:
        lst: The list to slice.
        start: The beginning index.
        end: The tip index.
    Returns:
        The sliced list.
    """
    return lst[start:end]

with gr.Blocks() as demo:
    gr.Markdown("This app includes MCP-only tools not visible within the UI.")
    gr.api(slice_list)

demo.launch(mcp_server=True)

Key features of the Gradio <> MCP Integration

1. Tool Conversion: Each API endpoint in your Gradio app is mechanically converted into an MCP tool with a corresponding name, description, and input schema. To view the tools and schemas, visit http://your-server:port/gradio_api/mcp/schema or go to the “View API” link within the footer of your Gradio app, after which click on “MCP”.

   Gradio allows developers to create sophisticated interfaces using easy Python code that provide dynamic UI manipulation for immediate visual feedback.

2. Environment variable support. There are two ways to enable the MCP server functionality:

   • Using the mcp_server parameter, as shown above:

     demo.launch(mcp_server=True)
     

   • Using environment variables:

     export GRADIO_MCP_SERVER=True
     

3. File Handling: The server mechanically handles file data conversions, including:

   • Converting base64-encoded strings to file data
   • Processing image files and returning them in the proper format
   • Managing temporary file storage
   • Automatic file upload MCP server for seamless local file support

   Recent Gradio updates have improved its image handling capabilities with features like Photoshop-style zoom and pan and full transparency control.

4. Performance Analytics: Gradio mechanically tracks and displays performance metrics for all of your MCP tools and API endpoints. View success rates, latency percentiles, and request counts directly within the “View API” page to allow you to and your users select probably the most reliable and fastest tools. Metrics are color-coded: green for 100% success, red for 0% success, and orange for in-between rates.

5. Hosted MCP Servers on 󠀠🤗 Spaces: You may publish your Gradio application without cost on Hugging Face Spaces, which can help you have a free hosted MCP server. Gradio is an element of a broader ecosystem that features Python and JavaScript libraries for constructing or querying machine learning applications programmatically.

Here’s an example of such a Space: https://huggingface.co/spaces/abidlabs/mcp-tools. Notice that you may add this config to your MCP Client to begin using the tools from this Space immediately:

{
  "mcpServers": {
    "gradio": {
      "url": "https://abidlabs-mcp-tools.hf.space/gradio_api/mcp/sse"
    }
  }
}

Private Spaces Authentication

It’s also possible to use private Huggingface Spaces as MCP servers by providing authentication:

{
  "mcpServers": {
    "gradio": {
      "url": "https://your-private-space.hf.space/gradio_api/mcp/sse",
      "headers": {
        "Authorization": "Bearer "
      }
    }
  }
}

Conclusion

By utilizing Gradio to construct your MCP server, you possibly can easily add many various sorts of custom functionality to your LLM. With the recent improvements including resources, prompts, higher authentication, file handling, and performance metrics, Gradio provides a comprehensive platform for constructing sophisticated MCP servers.

Further Reading

If you must dive deeper, listed below are some articles that we recommend: