MCP Playground

A comprehensive Python toolkit for interacting with remote Model Context Protocol (MCP) endpoints. Currently supports Server-Sent Events (SSE) with planned support for Streamable HTTP protocols.

🎯 Project Focus

MCP Playground is specifically designed for remote MCP client capabilities, providing robust tools for connecting to and interacting with MCP servers over network protocols:

• ✅ Server-Sent Events (SSE) - Full implementation with real-time streaming
• 🔄 Streamable HTTP - Planned for future releases
• 🤖 LLM Integration - AI-driven tool selection and execution
• 🧪 Interactive Testing - Comprehensive testing environments

🚀 Quick Start

Get up and running in minutes:

# Clone the repository
git clone https://github.com/zanetworker/mcp-playground.git
cd mcp-playground

# Install the package
pip install -e .

# Try the interactive Streamlit app
cd mcp-streamlit-app
pip install -r requirements.txt
streamlit run app.py

🚨 IMPORTANT: When connecting to MCP servers, always use URLs ending with /sse Example: http://localhost:8000/sse (not http://localhost:8000)

Environment Variables

For convenience, you can set API keys and OpenRouter configuration via environment variables:

# Required for LLM providers
export OPENAI_API_KEY="your-openai-key"
export ANTHROPIC_API_KEY="your-anthropic-key"
export OPENROUTER_API_KEY="your-openrouter-key"

# Optional OpenRouter configuration for better rankings
export OPENROUTER_SITE_URL="https://your-site.com"
export OPENROUTER_SITE_NAME="Your App Name"

The Streamlit interface prominently highlights the /sse URL requirement with helpful tooltips and validation.

🛠️ Supported Protocols

Current Support

• Server-Sent Events (SSE) - Real-time streaming communication with MCP servers
• HTTP/HTTPS - Standard request-response patterns

Planned Support

• Streamable HTTP - Enhanced HTTP streaming capabilities
• WebSocket - Bidirectional real-time communication
• gRPC Streaming - High-performance streaming protocol

🤖 LLM Provider Support

MCP Playground integrates with multiple LLM providers for intelligent tool selection:

• OpenAI: GPT-4o, GPT-4, GPT-3.5-Turbo
• Anthropic: Claude 3 Opus, Claude 3 Sonnet, Claude 3 Haiku
• Ollama: Llama 3, Mistral, and other locally hosted models
• OpenRouter: Access to 100+ models through a unified API

📋 Core Features

1. Remote MCP Client

Easily connect to any remote MCP endpoint and interact with available tools:

import asyncio
from mcp_playground import MCPClient

async def main():
    # Connect to a remote MCP endpoint with optional timeout and retry settings
    # IMPORTANT: URL must end with /sse for Server-Sent Events
    client = MCPClient(
        "http://localhost:8000/sse",  # Note the /sse suffix!
        timeout=30.0,      # Connection timeout in seconds
        max_retries=3      # Maximum retry attempts
    )
    
    # List available tools
    tools = await client.list_tools()
    print(f"Found {len(tools)} tools")
    
    # Invoke a calculator tool
    result = await client.invoke_tool(
        "calculator", 
        {"x": 10, "y": 5, "operation": "add"}
    )
    print(f"Result: {result.content}")  # Output: Result: 15
    print(f"Success: {result.error_code == 0}")

asyncio.run(main())

2. LLM-Powered Tool Selection

Let AI choose the right tool based on natural language queries:

import os
from mcp_playground import MCPClient, OpenAIBridge

# Connect to MCP endpoint and create an LLM bridge
client = MCPClient("http://localhost:8000/sse")
bridge = OpenAIBridge(
    client,
    api_key=os.environ.get("OPENAI_API_KEY"),
    model="gpt-4o"
)

# Process a natural language query
result = await bridge.process_query(
    "Convert this PDF to text: https://example.com/document.pdf"
)

# The LLM automatically selects the appropriate tool and parameters
if result["tool_call"]:
    print(f"Tool: {result['tool_call']['name']}")
    print(f"Result: {result['tool_result'].content}")

3. Command-Line Interface

The package includes a powerful CLI tool for interactive testing and analysis:

# Run the CLI tool (note the /sse suffix in the endpoint URL)
python -m mcp_playground.examples.llm_example --provider openai --endpoint http://localhost:8000/sse

Configuration Options:

usage: llm_example.py [-h] [--provider {openai,anthropic,ollama}]
                     [--openai-model {gpt-4o,gpt-4-turbo,gpt-4,gpt-3.5-turbo}]
                     [--anthropic-model {claude-3-opus-20240229,claude-3-sonnet-20240229,claude-3-haiku-20240307}]
                     [--ollama-model OLLAMA_MODEL] [--ollama-host OLLAMA_HOST]
                     [--endpoint ENDPOINT] [--openai-key OPENAI_KEY]
                     [--anthropic-key ANTHROPIC_KEY]

4. Interactive Testing Environment

The included Streamlit app provides a comprehensive testing interface:

Key Features:

• Multiple Chat Modes:
  • Auto Mode: LLM automatically decides when to use tools
  • Chat Mode: Direct conversation without MCP tools
  • Tools Mode: Always attempt to use MCP tools
• Multi-LLM Support: OpenAI, Anthropic, Ollama, and OpenRouter integration
• Dynamic Configuration: Connect to any MCP endpoint with real-time status
• Tool Discovery: Automatic detection and display of available tools
• Beautiful Response Formatting: Special formatting for structured data
• Error Handling: Robust connection management with clear error messages

To run the Streamlit app:

cd mcp-streamlit-app
pip install -r requirements.txt
streamlit run app.py

📦 Installation

From Source

git clone https://github.com/zanetworker/mcp-playground.git
cd mcp-playground
pip install -e .

Using pip (once published)

pip install mcp-playground

🔧 API Reference

MCPClient

client = MCPClient(endpoint, timeout=30.0, max_retries=3)

Parameters:

• endpoint: The MCP endpoint URL (must be http or https and end with /sse)
• timeout: Connection timeout in seconds (default: 30.0)
• max_retries: Maximum number of retry attempts (default: 3)

⚠️ URL Requirements:

• The endpoint URL must end with /sse for Server-Sent Events communication
• Examples of correct URLs:
  • http://localhost:8000/sse
  • https://my-mcp-server.com/sse
  • http://192.168.1.100:3000/sse

Methods

async list_tools() -> List[ToolDef]

Lists available tools from the MCP endpoint.

async invoke_tool(tool_name: str, kwargs: Dict[str, Any]) -> ToolInvocationResult

Invokes a specific tool with parameters.

async check_connection() -> bool

Check if the MCP endpoint is reachable.

get_endpoint_info() -> Dict[str, Any]

Get information about the configured endpoint.

Error Handling

The client includes robust error handling with specific exception types:

from mcp_playground import MCPClient, MCPConnectionError, MCPTimeoutError

try:
    client = MCPClient("http://localhost:8000/sse")
    tools = await client.list_tools()
except MCPConnectionError as e:
    print(f"Connection failed: {e}")
except MCPTimeoutError as e:
    print(f"Operation timed out: {e}")

LLM Bridges

OpenAIBridge

bridge = OpenAIBridge(mcp_client, api_key, model="gpt-4o")

AnthropicBridge

bridge = AnthropicBridge(mcp_client, api_key, model="claude-3-opus-20240229")

OllamaBridge

bridge = OllamaBridge(mcp_client, model="llama3", host=None)

OpenRouterBridge

bridge = OpenRouterBridge(mcp_client, api_key, model="anthropic/claude-3-opus")

🔄 Advanced Features

Retry Logic and Resilience

The client includes automatic retry logic with exponential backoff:

# Configure custom retry behavior
client = MCPClient(
    "http://localhost:8000/sse",
    timeout=60.0,     # Longer timeout for slow servers
    max_retries=5     # More retry attempts
)

# The client automatically retries failed operations
# with exponential backoff: 1s, 2s, 4s, 8s, 16s

Connection Health Monitoring

# Check if endpoint is reachable before operations
if await client.check_connection():
    tools = await client.list_tools()
else:
    print("Server is not reachable")

# Get detailed endpoint information
info = client.get_endpoint_info()
print(f"Connected to: {info['hostname']}:{info['port']}")

📋 Requirements

• Python 3.8+
• mcp>=0.1.0 (Model Context Protocol library)
• pydantic>=2.0.0 (Data validation)
• openai>=1.70.0 (for OpenAI integration)
• anthropic>=0.15.0 (for Anthropic integration)
• ollama>=0.1.7 (for Ollama integration)
• streamlit (for the interactive test app)

🐛 Troubleshooting

Common Issues

"unhandled errors in a TaskGroup" Error: This typically occurs with asyncio compatibility issues. The Streamlit app handles this automatically, but for custom implementations, ensure proper async context management.

Connection Timeouts:

• Increase the timeout parameter: MCPClient(endpoint, timeout=60.0)
• Check if the MCP server is running and accessible
• Verify the endpoint URL is correct and ends with /sse

Import Errors:

• Ensure all dependencies are installed: pip install -e .
• Check Python version compatibility (3.8+)

LLM Integration Issues:

• Verify API keys are set correctly
• Check model names match supported versions
• For Ollama, ensure the service is running locally

🚀 Roadmap

Upcoming Features

• Streamable HTTP Support - Enhanced HTTP streaming capabilities
• WebSocket Integration - Real-time bidirectional communication
• Connection Pooling - Improved performance for multiple connections
• Advanced Caching - Smart caching for tool definitions and results
• Monitoring Dashboard - Real-time monitoring of MCP connections
• Plugin System - Extensible architecture for custom protocols

🤝 Development

For information on development setup, contributing guidelines, and available make commands, see DEVELOPMENT.md.

📄 License

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

🙏 Acknowledgments

• Model Context Protocol (MCP) specification and community
• OpenAI, Anthropic, and Ollama for LLM API access
• Streamlit for the interactive testing framework