Omnimcp

🚀 OmniMCP

Semantic router for MCP ecosystems

Discover and execute tools across multiple MCP servers without context bloat

🚀 Quick Start

Step 1: Create your MCP servers config (mcp-servers.json)

This is an enhanced schema of Claude Desktop's MCP configuration with additional OmniMCP-specific fields.

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",  // or "uvx", "docker", any executable
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/directory"],
      "env": {},  // optional: environment variables for this server
      "timeout": 30.0,  // optional: seconds to wait for MCP server startup (default: 30)
      "hints": ["file operations", "read write files"],  // optional: help semantic search discover this server
      "blocked_tools": [],  // optional: tools to index but block at runtime
      "ignore": false,  // optional: skip indexing this server entirely
      "overwrite": false  // optional: force re-indexing even if already indexed
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {"GITHUB_TOKEN": "..."},
      "blocked_tools": ["delete_repository", "fork_repository"]  // indexed but execution blocked
    },
    "elevenlabs": {
      "command": "uvx",
      "args": ["elevenlabs-mcp"],
      "env": {"ELEVENLABS_API_KEY": "..."},
      "hints": [
        "When the user requests audio generation (speech or music), always execute in background mode",
        "Proactively offer to play audio using the ElevenLabs tool when contextually relevant"
      ]
    },
    "exa": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.exa.ai/mcp"],
      "env": {"EXA_API_KEY": "..."},
      "hints": [
        "Always execute web searches in background mode to avoid blocking the conversation",
        "Multiple Exa tool calls can be fired in parallel to efficiently gather information from different sources"
      ]
    }
  }
}

Step 2: Set environment variables

export OPENAI_API_KEY="sk-..."
export QDRANT_DATA_PATH="/path/to/qdrant_data"
export TOOL_OFFLOADED_DATA_PATH="/path/to/tool_offloaded_data"

Step 3: Index your servers (recommended before serving)

uvx --env-file .env omnimcp index --config-path mcp-servers.json

Step 4: Run the server

# Default: HTTP transport (recommended)
uvx --env-file .env omnimcp serve --config-path mcp-servers.json --transport http --host 0.0.0.0 --port 8000

# stdio transport (for local MCP clients - requires pre-indexing)
uvx --env-file .env omnimcp serve --config-path mcp-servers.json --transport stdio

✨ Features

Solving MCP Ecosystem Problems

• Context Bloat: Traditional MCP tool definitions consume a large number of tokens, leaving limited space for actual conversation, documents, and reasoning. OmniMCP exposes a single semantic_router tool, reducing token usage from ~60K to ~3K.
• Hallucinations: With a large number of similar tools, models are more likely to pick wrong tools and hallucinate parameters. OmniMCP's semantic search and progressive schema loading help improve tool selection accuracy.
• Caching Issues: Dynamic tool loading breaks caching. OmniMCP's approach ensures that prompt caches stay intact as the tool definition never changes.
• Context Bloat from Tool Results: Large tool results can bloat the context. OmniMCP handles large results through content offloading, such as chunking text, describing images, and storing results for retrieval.

Key Features

• Semantic Search: Find relevant tools by intent, not name. Tools are pre-indexed with embeddings, searched at runtime, and returned as text results.
• Lazy Server Loading: Servers start only when needed and shut down when done.
• Progressive Schema Loading: Full JSON schema is fetched only before execution and returned as text in the conversation.
• Content Offloading: Large results are chunked, images are described, and results are stored for retrieval.

📦 Installation

uv pip install omnimcp // or uv add omnimcp 

💻 Usage Examples

Basic Usage

# Search for tools
search_tools("read CSV files and analyze data")
    → Returns: filesystem.read_file, database.query (ranked by relevance)

# Get tool details
get_tool_details("filesystem", "read_file")
    → Returns: Full JSON schema with parameters

# Manage server
manage_server("filesystem", "start")
    → Launches the server process

# Execute tool
execute_tool("filesystem", "read_file", {"path": "/data/sales.csv"})
    → Returns: File content (chunked if large)

Advanced Usage

# Queue for background execution
execute_tool("server", "slow_tool", args, in_background=True, priority=1)
# Returns: task_id

# Check status
poll_task_result(task_id)
# Returns: status, result when done

📚 Documentation

Configuration

Environment Variables

OmniMCP requires several environment variables to operate. You must configure these before running index or serve commands.

Qdrant connection (choose ONE mode):

Optional variables (with defaults):

Setup methods:

Option 1: Local file storage (simplest)

export OPENAI_API_KEY="sk-proj-..."
export QDRANT_DATA_PATH="/path/to/qdrant_data"
export TOOL_OFFLOADED_DATA_PATH="/path/to/tool_offloaded_data"

Option 2: Docker Qdrant server

# Start Qdrant in Docker
docker run -p 6333:6333 -p 6334:6334 qdrant/qdrant

# Configure OmniMCP
export OPENAI_API_KEY="sk-proj-..."
export QDRANT_URL="http://localhost:6333"
export TOOL_OFFLOADED_DATA_PATH="/path/to/tool_offloaded_data"

Option 3: Qdrant Cloud

export OPENAI_API_KEY="sk-proj-..."
export QDRANT_URL="https://your-cluster.qdrant.io"
export QDRANT_API_KEY="your-qdrant-api-key"
export TOOL_OFFLOADED_DATA_PATH="/path/to/tool_offloaded_data"

Option 4: Create a .env file

# .env
OPENAI_API_KEY=sk-proj-...
QDRANT_DATA_PATH=/path/to/qdrant_data
# OR for remote: QDRANT_URL=http://localhost:6333
TOOL_OFFLOADED_DATA_PATH=/path/to/tool_offloaded_data

Then use the --env-file flag when running commands:

uvx --env-file .env omnimcp index --config-path mcp-servers.json

Transport Modes

HTTP Transport (Default - Recommended)

Best for most use cases: remote access, web integrations, or when using with mcp-remote or mcp-proxy.

uvx omnimcp serve --config-path mcp-servers.json --transport http --host 0.0.0.0 --port 8000

Use cases:

• Remote access - Serve OmniMCP on a server, connect from anywhere
• Multiple clients - Share one OmniMCP instance across multiple agents
• Web integrations - REST API access to your MCP ecosystem
• mcp-remote/mcp-proxy - Expose OmniMCP through MCP proxy layers

Example with mcp-remote:

npm install mcp-remote

{
  "mcpServers": {
    "omnimcp-remote": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://your-server:port/mcp"]
    }
  }
}

HTTP mode advantages:

• Indexing happens once on server startup
• Multiple clients share the same indexed data

stdio Transport

Best for local MCP clients that communicate via standard input/output (Claude Desktop, Cline, etc.).

⚠️ IMPORTANT: You MUST run uvx omnimcp index before using stdio mode to avoid slow startup times.

uvx omnimcp serve --config-path mcp-servers.json --transport stdio

Recommended workflow:

1. Index first - Run omnimcp index before adding to your MCP client config
2. Then mount - Add OmniMCP to your client's MCP configuration
3. Start serving - Client launches OmniMCP automatically via stdio

Example client config (claude_desktop_config.json):

{
  "mcpServers": {
    "omnimcp": {
      "command": "uvx",
      "args": ["omnimcp", "serve"],
      "env": {
        "CONFIG_PATH": "/path/mcp/config/file",
        "TRANSPORT": "stdio|http",
        "OPENAI_API_KEY": "sk-...",
        "QDRANT_DATA_PATH": "/path/to/qdrant_data",
        "TOOL_OFFLOADED_DATA_PATH": "/path/to/tool_offloaded_data"
        // add other env keys
      }
    }
  }
}

Troubleshooting uvx Issues

Error: spawn uvx ENOENT or command not found: uvx

This means uv is not installed or not in your PATH. Detailed troubleshooting guide • Official MCP docs.

Quick fixes:

1. Install uv (if not installed):

   # macOS/Linux
   brew install uv
   
   # or official installer
   curl -LsSf https://astral.sh/uv/install.sh | sh
   

2. Ensure uv is in PATH (macOS/Linux):

   # Check if installed
   which uvx
   
   # If not found, add to PATH (add to ~/.zshrc or ~/.bashrc)
   export PATH="$HOME/.local/bin:$PATH"
   
   # Or create symlink
   sudo ln -s ~/.local/bin/uvx /usr/local/bin/uvx
   

3. Use absolute path in config (find with which uvx):

   "command": "/Users/you/.local/bin/uvx"  // macOS
   "command": "C:\\Users\\you\\.local\\bin\\uvx.exe"  // Windows
   

Alternative: Use mcp-remote for HTTP mode

If uvx issues persist, run OmniMCP via HTTP and connect through mcp-remote:

# Terminal 1: Run OmniMCP HTTP server
uvx omnimcp serve --config-path mcp-servers.json --transport http --port 8000

// Claude Desktop config
{
  "mcpServers": {
    "omnimcp": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://localhost:8000/mcp"]
    }
  }
}

This bypasses stdio issues and works reliably across platforms.

Operations

Content Management

Large tool results are automatically handled:

• Text > 5000 tokens → Chunked, preview returned with reference ID
• Images → Offloaded, described with GPT-4 vision, reference returned
• Audio → Offloaded, reference returned

Retrieve full content with get_content(ref_id, chunk_index).

🔧 Technical Details

Architecture: Meta-Tool Pattern

OmniMCP uses the meta-tool pattern, similar to Claude Code's Agent Skills system. Instead of exposing dozens of individual tools, it exposes a single semantic_router tool as the only entry point to your entire MCP ecosystem.

Progressive Disclosure Workflow

Architecture & Request Flow

How It Works

Traditional MCP approach:

tools: [
  {name: "github_create_issue", description: "..."},
  {name: "github_create_pr", description: "..."},
  {name: "filesystem_read", description: "..."},
  // ... 50+ more tools
]

❌ Problems: Context bloat, tool hallucination, no caching

OmniMCP's meta-tool approach:

{
  "tools": [
    {
      "name": "semantic_router",
      "description": "Universal gateway to MCP ecosystem...\n
        OPERATIONS: search_tools, get_server_info, execute_tool...\n
        LIST OF INDEXED SERVERS:\n
        filesystem: 8 tools (file operations, read/write)\n
        github: 35 tools (issues, PRs, repos)\n
        ...",
      "input_schema": {
        "operation": "search_tools | execute_tool | ..."
      }
    }
  ]
}

✅ Benefits: Single tool definition, server list in description, dynamic discovery

Parallel to Claude Skills

Claude Skills and OmniMCP share the same architectural insight:

Key insight: Both systems inject instructions through prompt expansion rather than traditional function calling. The tool description becomes a dynamic directory that the LLM reads and reasons about, while actual execution details are loaded lazily.

Example of behavioral guidance:

Claude Skills:

<available_skills>
  skill-creator: "When user wants to create a new skill..."
  internal-comms: "When user wants to write internal communications..."
</available_skills>

OmniMCP hints:

{
  "elevenlabs": {
    "hints": [
      "When the user requests audio generation (speech or music), always execute in background mode",
      "Proactively offer to play audio using the ElevenLabs tool when contextually relevant"
    ]
  }
}

Both inject behavioral instructions that shape how the LLM uses the tools, not just what they do.

📄 License

MIT License - see LICENSE for details.

Related Research

OmniMCP builds on emerging research in scalable tool selection for LLM agents:

ScaleMCP: Dynamic and Auto-Synchronizing Model Context Protocol Tools

Lumer et al. (2025) introduce ScaleMCP, addressing similar challenges in MCP tool selection at scale. Their approach emphasizes:

• Dynamic tool retrieval - Giving agents autonomy to discover and add tools during multi-turn interactions
• Auto-synchronizing storage - Using MCP servers as the single source of truth via CRUD operations
• Tool Document Weighted Average (TDWA) - Novel embedding strategy that selectively emphasizes critical tool document components

Their evaluation across 5,000 financial metric servers demonstrates substantial improvements in tool retrieval and agent invocation performance, validating the importance of semantic search in MCP ecosystems.

Key insight: Both OmniMCP and ScaleMCP recognize that traditional monolithic tool repositories don't scale. The future requires dynamic, semantic-first approaches to tool discovery.

Anthropic's Advanced Tool Use

Anthropic's Tool Search feature (2025) introduces three capabilities that align with OmniMCP's architecture:

• Tool Search Tool - Discover thousands of tools without consuming context window
• Programmatic Tool Calling - Invoke tools in code execution environments to reduce context impact
• Tool Use Examples - Learn correct usage patterns beyond JSON schema definitions

Quote from Anthropic: "Tool results and definitions can sometimes consume 50,000+ tokens before an agent reads a request. Agents should discover and load tools on-demand, keeping only what's relevant for the current task."

This mirrors OmniMCP's core philosophy: expose minimal interface upfront (single semantic_router tool), discover tools semantically, load schemas progressively.

Convergent Evolution

These independent efforts converge on similar principles:

1. Semantic discovery over exhaustive enumeration
2. Progressive loading over upfront tool definitions
3. Agent autonomy to query and re-query tool repositories
4. Context efficiency as a first-class design constraint

OmniMCP implements these principles through semantic routing, lazy server loading, and content offloading—making large-scale MCP ecosystems practical today.

Development

git clone https://github.com/milkymap/omnimcp.git
cd omnimcp
uv sync
uv run pytest

Docker

Build

docker build -t omnimcp:latest -f Dockerfile .

Run

With local Qdrant storage:

docker run --rm -it \
  -v /path/to/qdrant_data:/data/qdrant \
  -v /path/to/tool_offloaded_data:/data/tool_offloaded_data \
  -v /path/to/mcp-servers.json:/app/config/mcp-servers.json:ro \
  --env-file .env.docker \
  -p 8000:8000 \
  omnimcp:latest serve

With remote Qdrant (Cloud or Docker):

docker run --rm -it \
  -v /path/to/tool_offloaded_data:/data/tool_offloaded_data \
  -v /path/to/mcp-servers.json:/app/config/mcp-servers.json:ro \
  --env-file .env.docker \
  -p 8000:8000 \
  omnimcp:latest serve

Environment file (.env.docker) - choose ONE Qdrant mode:

OPENAI_API_KEY=sk-proj-...
CONFIG_PATH=/app/config/mcp-servers.json
TOOL_OFFLOADED_DATA_PATH=/data/tool_offloaded_data
TRANSPORT=http
HOST=0.0.0.0
PORT=8000

# Option 1: Local Qdrant storage
QDRANT_DATA_PATH=/data/qdrant

# Option 2: Remote Qdrant (comment out QDRANT_DATA_PATH above)
# QDRANT_URL=https://your-cluster.qdrant.io
# QDRANT_API_KEY=your-api-key

Available commands:

# Show help
docker run --rm omnimcp:latest --help

# Index servers
docker run --rm \
  -v /path/to/mcp-servers.json:/app/config/mcp-servers.json:ro \
  --env-file .env.docker \
  omnimcp:latest index

# Serve (HTTP mode)
docker run --rm -d \
  -v /path/to/mcp-servers.json:/app/config/mcp-servers.json:ro \
  --env-file .env.docker \
  -p 8000:8000 \
  --name omnimcp \
  omnimcp:latest serve