MCP Gradio Client Proof of Concept

This repository is a proof of concept for implementing a Model Context Protocol (MCP) client using Gradio. It demonstrates how to interact with MCP servers using both STDIO and SSE communication methods within a Gradio interface.

The Model Context Protocol (MCP) aims to standardize the interaction between language models and tools, providing a uniform interface for communication. This proof of concept showcases the practical application of MCP in building AI assistants with tool integration.

Table of Contents

- Introduction
- Features
- Installation
- Configuration
- STDIO Server Definition
- SSE Server Definition
- Usage
- Notes
- License
- Contributing

Introduction

This project implements an MCP client within a Gradio application, allowing users to interact with tools exposed via the MCP. By leveraging the MCP's standardized communication protocol, the client can seamlessly integrate with various tools, enhancing the capabilities of language models.

Key elements from the Model Context Protocol:

- Standardization: MCP provides a standardized way for language models to interact with tools, promoting interoperability.
- Communication Methods: Supports multiple communication methods, including STDIO and SSE, for flexibility in tool integration.
- Tool Integration: Enables language models to use external tools, enhancing their functionality and applicability.

Features

- Gradio Interface: User-friendly interface for interacting with the MCP client and tools.
- STDIO and SSE Support: Demonstrates how to connect to MCP servers using both STDIO and SSE methods.
- Dynamic Tool Loading: Automatically discovers and integrates tools exposed by MCP servers.
- Debugging Support: Optional debug mode to aid in development and troubleshooting.

Installation

Prerequisites

- Python 3.12 or higher
- Node.js
- uvicorn (for UVX for STDIO servers)
- NPX (for NPX for STDIO servers)
- Python (for Python module STDIO servers)
- OpenAI API Key (for language model interaction)

Steps

1. Clone the Repository

   git clone https://github.com/yourusername/mcp-gradio-client.git
   cd mcp-gradio-client
   

2. Create a Virtual Environment
Unix/macOS:

   python -m venv venv

   source venv/bin/activate  # On Windows use venv\Scripts\activate

   

Windows:

    python -m venv .venv

    .venv\Scripts\activate

    

3. Install Dependencies

   pip install -r requirements.txt
   

4. Set Up Environment Variables

Create a .env file in the root directory using .env.example as a reference and add your OpenAI API key:

   OPENAI_API_KEY=your_openai_api_key
   

5. Running the App

Start the Gradio application:

   python gradio_ui.py
   

Understanding MCP STDIO vs SSE Servers

See stdio_versus_sse_mcp_servers.md for details on the differences between the two server types.

Configuration

The application requires a config.json file to define MCP servers. This file should be placed in the root directory.
config.json should have the following format:

{
  "mcpServers": {
    "stdio_server_name": {
      "type": "stdio",
      "command": "uvx",
      "args": [], 
      "env": {}
    },
    "sse_server_name": {
      "type": "sse",
      "url": "http://127.0.0.1:3001/sse",
      "headers": {}
    }
  }
}

See Information - How to Configure the config.json file for details. Please note, while the file structure if very similar to what Claude Desktop uses, it is not exactly the same.
There are several important differences (all annotated in the other readme)
- "type": "stdio"|"sse" is required to specify which type of servers you are using
- "command": "uvx"|"npx"|"python" may need to be adjusted for windows users. Example, npx will need to be npx.cmd for Windows

STDIO Server Definition

- Type: Should be set to "stdio". - Command: The command to start the STDIO server (e.g., "python", "uv", "uvx", or "npx"). - Args: Arguments for the command (e.g., ["weather_server.py"]). - Env: Environment variables required by the server.

Note: STDIO servers are instantiated by Gradio and do not need to be manually started. They are typically launched via npx, uvicorn/uvx, or python -m command arguments. Some Python STDIO servers must be downloaded and installed first if they're not recognized packages.

SSE Server Definition

- Type: Should be set to "sse". - URL: The endpoint where the SSE server is running. - Headers: (Optional) Any headers required for the connection.

Note: SSE servers must be manually up and running for the Gradio client to connect. Ensure that the SSE server is started before running the Gradio application.

Usage

1. Start SSE Servers (if any)
Ensure any SSE servers defined in your config.json are running.

2. Run the Gradio Application

   python gradio_ui.py

   

3. Interact with the Interface
Open the provided URL in your web browser (usually http://127.0.0.1:7860) to access the Gradio interface.

4. Ask Questions
Use the chat interface to interact with the language model and the tools provided by the MCP servers.

Notes

- STDIO Servers: Gradio will automatically instantiate STDIO servers as needed based on your configuration. - SSE Servers: Must be started manually before running the Gradio client. - Debug Mode: Enable or disable debug mode using the checkbox in the interface to view detailed logs. - Tool Installation: Some tools may require additional installation steps if they are not standard packages. Ensure all necessary tools are installed and accessible.

License

This project is licensed under the MIT License. See the LICENSE file for details.

---

For more information on the Model Context Protocol and its capabilities, visit the official MCP documentation.

Contributing

<details>

<summary><h3>Open Developer Guide</h3></summary>

Prerequisites

Gradio requires Python 3.12+

Installation

Create a fork of this repository, then clone it:

git clone xxxxx
cd xxx

Next, create a virtual environment and install FastMCP:
Unix/macOS:

uv venv

source .venv/bin/activate

uv sync --frozen --all-extras --dev

Windows

venv

.venv/bin/activate

Testing

Please make sure to test any new functionality. Your tests should be simple and atomic and anticipate change rather than cement complex patterns.

Run tests from the root directory:

pytest -v

Formatting

This POC enforces a variety of required formats, which you can automatically enforce with pre-commit.

Install the pre-commit hooks:

pre-commit install

The hooks will now run on every commit (as well as on every PR). To run them manually:

pre-commit run --all-files

Opening a Pull Request

Fork the repository and create a new branch:

git checkout -b my-branch

Make your changes and commit them:

git add . && git commit -m "My changes"

Push your changes to your fork:

git push origin my-branch

Feel free to reach out in a GitHub issue or discussion if you have any questions!

</details>