LLM Gateway MCP server for AI agents

The Ultimate MCP Server is a comprehensive Model Context Protocol (MCP) server that provides AI agents with dozens of powerful capabilities through a standardized interface. It serves as a complete AI agent operating system, enabling advanced functionalities beyond what AI models can natively perform.

Installation

To install the Ultimate MCP Server:

# Install uv (fast Python package manager) if you don't have it:
curl -LsSf https://astral.sh/uv/install.sh | sh

# Clone the repository
git clone https://github.com/Dicklesworthstone/ultimate_mcp_server.git
cd ultimate_mcp_server

# Create a virtual environment and install dependencies using uv:
uv venv --python 3.13
source .venv/bin/activate
uv lock --upgrade
uv sync --all-extras

Configuration

Create a .env file in the root directory with your API keys and configuration:

# --- API Keys (at least one provider required) ---
OPENAI_API_KEY=your_openai_sk-...
ANTHROPIC_API_KEY=your_anthropic_sk-...
GEMINI_API_KEY=your_google_ai_studio_key...
# Optional: Additional provider keys
DEEPSEEK_API_KEY=your_deepseek_key...
OPENROUTER_API_KEY=your_openrouter_key...
GROK_API_KEY=your_grok_key...

# --- Server Configuration ---
GATEWAY_SERVER_PORT=8013
GATEWAY_SERVER_HOST=127.0.0.1 # Change to 0.0.0.0 for external access

# --- Optional Configuration ---
# LOG_LEVEL=INFO # DEBUG, INFO, WARNING, ERROR, CRITICAL
# GATEWAY_CACHE_ENABLED=true
# FILESYSTEM__ALLOWED_DIRECTORIES=["/path/to/safe/dir1","/path/to/safe/dir2"]

Running the Server

Start the server using the command-line interface:

# Basic server start with default settings
umcp run

# Run with specific host and port
umcp run -h 0.0.0.0 -p 9000

# Use streamable-http transport (recommended for HTTP clients)
umcp run -t shttp

# Run only with specific tools
umcp run --include-tools completion chunk_document read_file write_file

# Run with all tools except certain ones
umcp run --exclude-tools browser_init browser_navigate

Using the Server

The server exposes dozens of powerful capabilities through MCP tools that can be called by AI agents like Claude or custom applications using the MCP client. Here are some key functionalities:

Text Generation and Processing

Generate text completions with any configured provider
Summarize documents and chunk large texts
Extract structured data (JSON, tables) from unstructured text
Process text using local utilities (grep, awk, jq)

Cognitive and Memory Systems

Store and retrieve agent memories with metadata
Build persistent knowledge across sessions
Generate reflections based on accumulated knowledge

Web and Browser Automation

Navigate websites and extract information
Fill forms and interact with web interfaces
Take screenshots and download files

Document Processing

Manipulate Excel spreadsheets with natural language instructions
Perform OCR on images and PDFs
Process documents with intelligent chunking and summarization

Data Analysis and Retrieval

Execute SQL queries against databases
Build and query entity relationship graphs
Perform vector searches and retrieval-augmented generation (RAG)

Tool Management

Discover available tools dynamically
Register external APIs as tools
Get tool recommendations for specific tasks

Command-Line Interface

The server provides a powerful CLI for management:

# List available providers
umcp providers

# Test a specific provider
umcp test anthropic --model claude-3-5-sonnet-20241022

# Generate text directly from CLI
umcp complete --prompt "Write a short poem about coding"

# List available tools
umcp tools

# Run example scripts
umcp examples rag_example

Security Considerations

When deploying the server:

Use environment variables for API keys, never hardcode them
Configure allowed directories for filesystem tools
Run behind a reverse proxy with proper authentication
Consider network exposure and access control
Update dependencies regularly

Advanced Usage

The server supports various deployment options:

Running as a background service with systemd or supervisor
Using Docker with appropriate volume mapping
Scaling with container orchestration like Kubernetes
Configuring persistent storage for caching and memory systems

For detailed information on specific tools, advanced configuration, and example code, refer to the project documentation and example files.

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "llm-gateway" '{"command":"umcp","args":["run","-t","shttp"]}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "llm-gateway": {
            "command": "umcp",
            "args": [
                "run",
                "-t",
                "shttp"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

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

2. Add this to your configuration file:

{
    "mcpServers": {
        "llm-gateway": {
            "command": "umcp",
            "args": [
                "run",
                "-t",
                "shttp"
            ]
        }
    }
}

3. Restart Claude Desktop for the changes to take effect