docs/client_examples.md

# 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):

```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:

```json

{

  "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

```json

{

  "mcpServers": {

    "proportio": {

      "command": "python",

      "args": ["/path/to/proportio/app.py"],

      "env": {

        "MCP_TOKEN": "your-secure-token-here"

      }

    }

  }

}

```

### Remote Server Configuration

```json

{

  "mcpServers": {

    "proportio": {

      "url": "https://your-server.com/gradio_api/mcp/sse",

      "headers": {

        "X-Api-Key": "your-secure-token-here"

      }

    }

  }

}

```

## CrewAI

### Basic Setup

```python

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

```python

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

```python

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

```bash

# 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

```python

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

```bash

# .env file

MCP_TOKEN=dev-token-123

DEBUG=true

LOG_LEVEL=DEBUG

RELOAD=true

```

### Production Environment

```bash

# .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:

```bash

# 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

1. Generate new token
2. Update all client configurations
3. Update server environment variable
4. Restart server
5. 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

1. **"Connection refused"**
   - Check if server is running: `curl http://localhost:7860`
   - Verify port is not blocked by firewall

2. **"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

3. **"Request timeout"**
   - Check server logs for errors
   - Verify network connectivity
   - Increase client timeout settings

### Debug Mode

Enable debug logging to troubleshoot issues:

```bash

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:

```bash

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):

```yaml

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

```bash

# 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

```yaml

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:

```json

{

  "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

1. Start the Proportio server: `python app.py`
2. Open Msty and go to Settings → MCP Servers
3. Add a new server with the configuration above
4. 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:

```bash

#!/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

```python

#!/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.