MCP Client Configuration Examples

This document provides configuration examples for various MCP clients to connect to the Proportio server.

Cursor IDE

Method 1: Settings JSON

Add to your Cursor settings (Cmd/Ctrl + , → Open Settings JSON):

{
  "mcpServers": {
    "proportio": {
      "url": "http://localhost:7860/gradio_api/mcp/sse",
      "headers": {
        "X-Api-Key": "your-secure-token-here"
      }
    }
  }
}

Method 2: Workspace Configuration

Create .cursor/mcp.json in your project root:

{
  "proportio": {
    "url": "http://localhost:7860/gradio_api/mcp/sse",
    "headers": {
      "X-Api-Key": "your-secure-token-here"
    }
  }
}

Claude Desktop

Configuration File Location

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%/Claude/claude_desktop_config.json

Local Server Configuration

{
  "mcpServers": {
    "proportio": {
      "command": "python",
      "args": ["/path/to/proportio/app.py"],
      "env": {
        "MCP_TOKEN": "your-secure-token-here"
      }
    }
  }
}

Remote Server Configuration

{
  "mcpServers": {
    "proportio": {
      "url": "https://your-server.com/gradio_api/mcp/sse",
      "headers": {
        "X-Api-Key": "your-secure-token-here"
      }
    }
  }
}

CrewAI

Basic Setup

from crewai import Agent, Task, Crew
from crewai.tools import MCPTool

# Configure the MCP tool
proportio_tool = MCPTool(
    name="proportio_calculator",
    url="http://localhost:7860/gradio_api/mcp/sse",
    headers={"X-Api-Key": "your-secure-token-here"}
)

# Create an agent with the tool
math_agent = Agent(
    role="Mathematical Calculator",
    goal="Perform accurate proportion and percentage calculations",
    backstory="You are an expert mathematician who uses reliable tools for calculations.",
    tools=[proportio_tool],
    verbose=True
)

# Example task
calculation_task = Task(
    description="Calculate what percentage 75 is of 300, then scale that result by 1.5",
    agent=math_agent,
    expected_output="The percentage and scaled result with explanations"
)

# Run the crew
crew = Crew(
    agents=[math_agent],
    tasks=[calculation_task]
)

result = crew.kickoff()
print(result)

Advanced CrewAI Setup with Multiple Tools

from crewai import Agent, Task, Crew
from crewai.tools import MCPTool

class ProportioTools:
    def __init__(self, base_url="http://localhost:7860", api_key="your-token"):
        self.base_url = f"{base_url}/gradio_api/mcp/sse"
        self.headers = {"X-Api-Key": api_key}
    
    def get_tools(self):
        return [
            MCPTool(
                name="percent_calculator",
                url=self.base_url,
                headers=self.headers,
                description="Calculate percentages accurately"
            ),
            MCPTool(
                name="proportion_solver",
                url=self.base_url,
                headers=self.headers,
                description="Solve proportion equations"
            ),
            MCPTool(
                name="dimension_resizer",
                url=self.base_url,
                headers=self.headers,
                description="Resize dimensions with scaling"
            )
        ]

# Usage
proportio = ProportioTools(api_key="your-secure-token-here")
tools = proportio.get_tools()

agent = Agent(
    role="Design Calculator",
    goal="Help with design calculations and proportions",
    tools=tools
)

OpenAI Agents SDK

Basic Configuration

from openai_agents import Agent
from openai_agents.mcp import MCPConnection

# Setup MCP connection
mcp_conn = MCPConnection(
    url="http://localhost:7860/gradio_api/mcp/sse",
    headers={"X-Api-Key": "your-secure-token-here"}
)

# Create agent with MCP tools
agent = Agent(
    name="Math Assistant",
    model="gpt-4",
    mcp_connections=[mcp_conn]
)

# Use the agent
response = agent.run("What percentage is 45 out of 180?")
print(response)

Generic HTTP Client (for testing)

Using curl

# Test percent_of tool
curl -X POST http://localhost:7860/gradio_api/mcp/sse \
  -H "X-Api-Key: your-secure-token-here" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "percent_of",
      "arguments": {
        "part": 25,
        "whole": 100
      }
    }
  }'

Using Python requests

import requests
import json

def call_proportio_tool(tool_name, arguments, api_key="your-token"):
    url = "http://localhost:7860/gradio_api/mcp/sse"
    headers = {
        "X-Api-Key": api_key,
        "Content-Type": "application/json"
    }
    
    payload = {
        "jsonrpc": "2.0",
        "id": 1,
        "method": "tools/call",
        "params": {
            "name": tool_name,
            "arguments": arguments
        }
    }
    
    response = requests.post(url, headers=headers, json=payload)
    return response.json()

# Examples
result1 = call_proportio_tool("percent_of", {"part": 75, "whole": 300})
print(f"Percentage: {result1}")

result2 = call_proportio_tool("solve_proportion", {"a": 3, "b": 4, "c": 6, "d": None})
print(f"Missing value: {result2}")

result3 = call_proportio_tool("resize_dimensions", {
    "width": 1920, 
    "height": 1080, 
    "scale": 0.5
})
print(f"New dimensions: {result3}")

Environment-Specific Configurations

Development Environment

# .env file
MCP_TOKEN=dev-token-123
DEBUG=true
LOG_LEVEL=DEBUG
RELOAD=true

Production Environment

# .env file
MCP_TOKEN=prod-secure-token-xyz789
DEBUG=false
LOG_LEVEL=WARNING
MAX_REQUEST_SIZE=32768

Hugging Face Spaces

Set these as Space secrets:

MCP_TOKEN: Your secure authentication token
LOG_LEVEL: INFO or WARNING

Access URL: https://your-username-proportio.hf.space/gradio_api/mcp/sse

Security Best Practices

Token Generation

Generate secure tokens:

# Python
python -c "import secrets; print(secrets.token_urlsafe(32))"

# OpenSSL
openssl rand -base64 32

# Node.js
node -e "console.log(require('crypto').randomBytes(32).toString('base64url'))"

Token Rotation

Generate new token
Update all client configurations
Update server environment variable
Restart server
Verify all clients work with new token

Network Security

Use HTTPS in production
Implement rate limiting at reverse proxy level
Monitor for unusual usage patterns
Keep logs for security auditing

Troubleshooting

Common Connection Issues

"Connection refused"
- Check if server is running: curl http://localhost:7860
- Verify port is not blocked by firewall
"Invalid API key"
- Ensure X-Api-Key header is included
- Check token matches MCP_TOKEN environment variable
- Verify no extra spaces or characters in token
"Request timeout"
- Check server logs for errors
- Verify network connectivity
- Increase client timeout settings

Debug Mode

Enable debug logging to troubleshoot issues:

export DEBUG=true
export LOG_LEVEL=DEBUG
python app.py

This will show detailed logs of all MCP requests and responses.

Roo Code Assistant

Configuration

Roo uses MCP servers automatically when they're running locally. Simply start the Proportio server:

python app.py

Roo will detect the running MCP server at http://localhost:7860/gradio_api/mcp/sse and make the tools available.

Usage Examples

Human: Calculate what percentage 45 is of 180

Roo: I'll use the proportion calculator to find what percentage 45 is of 180.

[Using percent_of tool with part=45, whole=180]

45 is 25% of 180.

Human: I need to resize an image from 1920x1080 to half the size

Roo: I'll help you calculate the new dimensions using the resize tool.

[Using resize_dimensions tool with width=1920, height=1080, scale=0.5]

The new dimensions would be 960 × 540 pixels.

OpenWebUI

Configuration File

Add to your OpenWebUI configuration (config.yaml or environment):

mcp:
  servers:
    proportio:
      url: "http://localhost:7860/gradio_api/mcp/sse"
      headers:
        X-Api-Key: "your-secure-token-here"
      tools:
        - percent_of
        - solve_proportion
        - scale_by_ratio
        - direct_k
        - resize_dimensions

Environment Variables

# OpenWebUI MCP configuration
OPENWEBUI_MCP_SERVERS='[
  {
    "name": "proportio",
    "url": "http://localhost:7860/gradio_api/mcp/sse",
    "headers": {"X-Api-Key": "your-secure-token-here"}
  }
]'

Docker Compose with OpenWebUI

version: '3.8'
services:
  proportio:
    build: .
    ports:
      - "7860:7860"
    environment:
      - MCP_TOKEN=your-secure-token-here
    networks:
      - webui_network

  openwebui:
    image: ghcr.io/open-webui/open-webui:main
    ports:
      - "3000:8080"
    environment:
      - OPENWEBUI_MCP_SERVERS=[{"name":"proportio","url":"http://proportio:7860/gradio_api/mcp/sse","headers":{"X-Api-Key":"your-secure-token-here"}}]
    depends_on:
      - proportio
    networks:
      - webui_network

networks:
  webui_network:
    driver: bridge

Msty

Configuration

In Msty's settings, add the MCP server:

{
  "mcp_servers": {
    "proportio": {
      "type": "sse",
      "url": "http://localhost:7860/gradio_api/mcp/sse",
      "auth": {
        "type": "header",
        "header_name": "X-Api-Key",
        "header_value": "your-secure-token-here"
      },
      "description": "Mathematical proportion calculations"
    }
  }
}

Using with Msty

Start the Proportio server: python app.py
Open Msty and go to Settings → MCP Servers
Add a new server with the configuration above
The tools will be available in chat sessions

Example Msty Usage

You: I need to solve this proportion: 3/4 = x/12. What is x?

Msty: I'll use the proportion solver to find the missing value.

[Using solve_proportion tool]

The missing value x is 9. So 3/4 = 9/12.

Local Development Setup Script

Create a setup script for easy local development:

#!/bin/bash
# setup_local_mcp.sh

# Generate secure token
TOKEN=$(python -c "import secrets; print(secrets.token_urlsafe(32))")

# Create .env file
cat > .env << EOF
MCP_TOKEN=$TOKEN
DEBUG=true
LOG_LEVEL=DEBUG
RELOAD=true
EOF

echo "Generated secure token: $TOKEN"
echo "Add this to your MCP clients' X-Api-Key header"

# Start the server
python app.py

Make it executable: chmod +x setup_local_mcp.sh

Testing Your MCP Connection

Quick Test Script

#!/usr/bin/env python3
"""Test script for Proportio MCP server connection"""

import requests
import json
import sys

def test_mcp_connection(base_url="http://localhost:7860", api_key="your-token"):
    """Test MCP server connection and tools."""
    
    url = f"{base_url}/gradio_api/mcp/sse"
    headers = {
        "X-Api-Key": api_key,
        "Content-Type": "application/json"
    }
    
    # Test cases
    tests = [
        {
            "name": "Percentage Calculation",
            "tool": "percent_of",
            "args": {"part": 25, "whole": 100},
            "expected": 25.0
        },
        {
            "name": "Proportion Solving",
            "tool": "solve_proportion", 
            "args": {"a": 3, "b": 4, "c": 6, "d": None},
            "expected": 8.0
        },
        {
            "name": "Dimension Resizing",
            "tool": "resize_dimensions",
            "args": {"width": 100, "height": 50, "scale": 2.0},
            "expected": {"new_width": 200.0, "new_height": 100.0}
        }
    ]
    
    print(f"Testing MCP server at {url}")
    print(f"Using API key: {api_key[:8]}...")
    print("-" * 50)
    
    for test in tests:
        try:
            payload = {
                "jsonrpc": "2.0",
                "id": 1,
                "method": "tools/call",
                "params": {
                    "name": test["tool"],
                    "arguments": test["args"]
                }
            }
            
            response = requests.post(url, headers=headers, json=payload, timeout=10)
            
            if response.status_code == 200:
                result = response.json()
                print(f"✅ {test['name']}: PASSED")
                print(f"   Result: {result}")
            else:
                print(f"❌ {test['name']}: FAILED (HTTP {response.status_code})")
                print(f"   Response: {response.text}")
                
        except Exception as e:
            print(f"❌ {test['name']}: ERROR - {str(e)}")
        
        print()

if __name__ == "__main__":
    api_key = input("Enter your API key (or press Enter for 'test-token'): ").strip()
    if not api_key:
        api_key = "test-token"
    
    test_mcp_connection(api_key=api_key)

Save as test_mcp.py and run: python test_mcp.py

This comprehensive guide covers all major MCP clients including Roo, OpenWebUI, and Msty, providing practical examples for integrating the Proportio server into your development workflow.