Connect to MCP Server

CUGA can connect to any MCP (Model Context Protocol) server to access tools and resources. This guide shows you how to configure and run CUGA with an MCP server.

📖 Quick Overview

This guide covers three ways to set up MCP servers with CUGA:

• Option A: Using an Existing Server - Connect to pre-built MCP servers (e.g., GitHub) using STDIO transport
• Option B: Creating a Local STDIO Server - Build a custom command-line based MCP server (local development)
• Option C: Creating an HTTP Server - Build a custom HTTP-based MCP server (recommended for production/remote access)

📋 Prerequisites

Before starting, ensure you have:

• Python 3.12+ - Download here
• uv package manager - Installation guide
• CUGA installed - Clone from GitHub
• Node.js (for MCP filesystem server) - Download here

Setup Steps

# Navigate to CUGA directory
cd cuga-agent

# Create and activate virtual environment
uv venv --python=3.12 && source .venv/bin/activate

# Install dependencies
uv sync

# Create .env file with your API keys
echo "OPENAI_API_KEY=your-openai-api-key-here" > .env
# Or use another LLM provider (see CUGA README for options)

💡 Tip: For LLM configuration options (OpenAI, WatsonX, Azure, etc.), see the CUGA README.

✅ What You'll Do

1. Set up an MCP server (or use an existing one).
2. Configure CUGA to connect to the server.
3. Start CUGA in demo mode with MCP tools available.

⚙️ Configuration Steps

1. Settings File

CUGA uses MCP servers in all modes. Check your settings.toml (located at src/cuga/settings.toml):

[advanced_features]
mode = "api"

💡 Tip: MCP servers work in api and hybrid modes. Learn more about hybrid here.

2. MCP Server Registry (mcp_servers.yaml)

Default location:

src/cuga/backend/tools_env/registry/config/mcp_servers.yaml

To use a custom file:

export MCP_SERVERS_FILE="<path-to-file>"

Example:

mcpServers:
  filesystem:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-filesystem", "./workspace"]
    transport: stdio
    description: Local file system operations

3. Setting Up Your MCP Server

You can either use an existing MCP server or create your own.

Option A: Using an Existing Server

Install the server and add it to mcp_servers.yaml:

mcpServers:
  github:
    command: npx
    args: ["@modelcontextprotocol/server-github"]
    transport: stdio
    description: GitHub MCP server for repository operations
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "<your-token>"

Option B: Creating a Local STDIO Server

Create a custom local MCP server using STDIO transport with the MCP Python SDK:

import asyncio
from mcp.server import Server
from mcp.server.stdio import stdio_server
from mcp.types import Tool, TextContent

server = Server("weather-server")

@server.list_tools()
async def list_tools():
    return [
        Tool(
            name="get_weather",
            description="Get the current weather for a city",
            inputSchema={
                "type": "object",
                "properties": {
                    "city": {
                        "type": "string",
                        "description": "The name of the city (e.g., 'San Francisco', 'New York')"
                    }
                },
                "required": ["city"]
            }
        )
    ]

@server.call_tool()
async def call_tool(name: str, arguments: dict):
    if name == "get_weather":
        city = arguments.get("city", "unknown")
        return [TextContent(
            type="text",
            text=f"Weather in {city}: Sunny, 72°F"
        )]
    raise ValueError(f"Unknown tool: {name}")

async def main():
    async with stdio_server() as streams:
        await server.run(
            streams[0],
            streams[1],
            server.create_initialization_options()
        )

if __name__ == "__main__":
    asyncio.run(main())

Save this file as my_server.py in your CUGA directory.

Register it in mcp_servers.yaml:

mcpServers:
  my_server:
    command: python
    args: ["./my_server.py"]
    transport: stdio
    description: Weather information service. Provides current weather conditions and temperature for any city.

💡 Tip: STDIO transport is ideal for local development and command-line tools. For production deployments or remote access, see Option C below.

Option C: Creating an HTTP Server

Create a custom HTTP-based MCP server for remote access or production deployments using FastMCP:

from fastmcp import FastMCP

# Create an MCP server
mcp = FastMCP("weather-server")

@mcp.tool()
def get_weather(city: str) -> str:
    """Get the current weather for a city.

    Args:
        city: The name of the city (e.g., 'San Francisco', 'New York')

    Returns:
        Weather information for the city
    """
    return f"Weather in {city}: Sunny, 72°F"

if __name__ == "__main__":
    # Run with HTTP transport on port 8000
    mcp.run(transport="http", port=8000)

Save this file as weather_http_server.py in your CUGA directory.

Install the required dependencies:

pip install fastmcp

Start the HTTP server:

python weather_http_server.py

Register it in mcp_servers.yaml:

mcpServers:
  weather_http:
    url: http://localhost:8000/mcp
    transport: http
    description: HTTP-based weather information service. Provides current weather conditions and temperature for any city via HTTP transport.

💡 Tip: HTTP transport is recommended for production environments as it allows the MCP server to run independently and be accessed remotely. Multiple CUGA instances can connect to the same HTTP server. For more about MCP servers, see the MCP Python SDK documentation.

🔐 Adding Environment Variables (Optional)

Pass secrets or configuration through environment variables:

mcpServers:
  my_server:
    command: python
    args: ["./my_server.py"]
    transport: stdio
    description: Weather information service. Provides current weather conditions and temperature for any city.
    env:
      API_KEY: "<your-weather-api-key>"
      DEBUG: "true"

✅ Environment variables are loaded from your system or .env file before CUGA starts.

▶️ Running CUGA with MCP Servers

Make sure your virtual environment is activated, then start CUGA:

# Ensure virtual environment is activated
source .venv/bin/activate

# Start CUGA demo mode
cuga start demo

What happens next:

• ✅ Loads all MCP servers from mcp_servers.yaml.
• ✅ Establishes connections to each server.
• ✅ Makes all server tools available to CUGA.
• ✅ Launches demo mode and opens in your browser after a few seconds at http://localhost:8005.

🎯 You're Ready!

Now you can query CUGA using tools from your MCP servers. The orchestrator will automatically select and call the appropriate tools to complete your tasks.

Example Queries

Try a sample query based on your server:

GitHub server:

Get the last commit on cuga-project/cuga-agent

Python STDIO weather server:

What's the weather in San Francisco?

HTTP weather server:

What's the weather in New York?

Filesystem server:

List all files in the cuga_workspace directory

🔍 Troubleshooting

Common Issues

Issue: cuga: command not found

• Solution: Ensure virtual environment is activated: source .venv/bin/activate

Issue: MCP server fails to start

• Solution: Check that the command/binary exists. For npx commands, ensure Node.js is installed.

Issue: Filesystem server errors

• Solution: Ensure the workspace directory exists: mkdir -p cuga_workspace

Issue: GitHub server authentication fails

• Solution: Verify your GITHUB_PERSONAL_ACCESS_TOKEN is set correctly in the env section of mcp_servers.yaml

Issue: Python MCP server not working

• Solution: Ensure the MCP Python SDK is installed in your virtual environment: pip install mcp

Issue: HTTP MCP server connection fails

• Solution:
  • Ensure the HTTP server is running: check if you can access the URL in your browser
  • Verify the port is not blocked by a firewall
  • For FastMCP servers, ensure you have installed: pip install fastmcp
  • Check server logs for any errors

Issue: Browser doesn't open

• Solution: Manually navigate to http://localhost:8005