GEAI-PROXY(1)

NAME
geai-proxy - proxy service for managing Model Context Protocol (MCP) servers with GEAI

SYNOPSIS
geai-proxy [OPTIONS] CONFIG_FILE

DESCRIPTION
The GEAI Proxy is a Python-based tool that acts as an intermediary between the GEAI API and various tool servers. It manages the registration, execution, and result handling of tool operations through a proxy service.

To install:
pip install pygeai

CONFIGURATION
The GEAI Proxy requires two distinct types of configuration:

  1. MCP Servers Configuration
This section declares the Model Context Protocol (MCP) servers that this proxy will link with GEAI. The configuration follows the Claude Desktop standard format and supports multiple servers in one file.

Configuration File Format
    The configuration file should be in JSON format with the following structure:
    {
      "mcpServers": {
        "serverName1": {
          "command": "command-to-launch-server",
          "args": ["arg1", "arg2", ...]
        },
        "serverName2": {
          "command": "command-to-launch-server",
          "args": ["arg1", "arg2", ...]
        }
      }
    }

Example: Puppeteer Server
    {
      "mcpServers": {
        "puppeteer": {
          "command": "npx",
          "args": ["-y", "@modelcontextprotocol/server-puppeteer"]
        }
      }
    }

Example: Filesystem Server
    {
      "mcpServers": {
        "filesystem": {
          "command": "npx",
          "args": ["-y", "@modelcontextprotocol/server-filesystem", "~/mcp-shared-folder"]
        }
      }
    }

Example: HTTP+SSE Server
    {
      "mcpServers": {
        "markitdown": {
          "uri": "http://localhost:5000/sse"
        }
      }
    }

Example: Multiple Servers Combined
    {
      "mcpServers": {
        "puppeteer": {
          "command": "npx",
          "args": ["-y", "@modelcontextprotocol/server-puppeteer"]
        },
        "filesystem": {
          "command": "npx",
          "args": ["-y", "@modelcontextprotocol/server-filesystem", "~/mcp-shared-folder"]
        },
        "markitdown": {
          "uri": "http://localhost:5000/sse"
        },
        "custom-server": {
          "command": "python",
          "args": ["path/to/your/custom_mcp_server.py"]
        }
      }
    }

  2. Proxy Authentication Configuration
This section establishes the connection between the proxy and GEAI and manages user aliases.

Automatic Configuration (First Run)
    geai-proxy sample-mcp-config.json --alias myalias

Manual Configuration (Reconfiguration)
    geai-proxy --configure --alias myalias
    During interactive setup, the CLI will prompt you for each required setting:
    # Configuring GEAI proxy settings...
    Generated new proxy ID: 37bae96b-bc99-4110-bb61-b912b28f9e32
    -> Insert proxy ID (UUID) (Current: 37bae96b-bc99-4110-bb61-b912b28f9e32, Leave empty to keep):
    -> Insert proxy API key:
    -> Insert proxy base URL:
    -> Insert proxy name:
    -> Insert proxy description:

USAGE
To start the proxy server with a specific configuration and alias:
geai-proxy sample-mcp-config.json --alias myalias

Command Line Arguments:

config_file
    Path to the MCP servers configuration file (JSON format).

--alias ALIAS
    Alias for the proxy settings.

--configure
    Reconfigure proxy authentication settings.

FILES
pygeai/proxy/sample-mcp-config.json Sample configuration file for MCP servers.

SEE ALSO
pygeai(1)

THIRD-PARTY COMPONENTS
This software includes code from the a2a-python project developed by Google LLC, which is licensed under the Apache License, Version 2.0. Only the vendored component located in pygeai/vendor/a2a/ is subject to the Apache License. The rest of this software is licensed under the MIT License. For full license details, see:

•   https://github.com/google/a2a-python

•   pygeai/vendor/a2a/LICENSE

AUTHOR
Written by the GEAI development team.

COPYRIGHT
Copyright © 2025 GEAI development team. This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.