Semantic MCP

Semantic router for MCP ecosystems - Discover, manage, and execute tools across multiple MCP servers with progressive disclosure.

Overview

semantic-mcp is a FastMCP-based MCP server that provides semantic discovery and lifecycle management for other MCP servers. It connects to a discovery service for semantic search and manages server lifecycles locally via ZMQ-based IPC.

LLM Client (Claude/Cline)
    │ MCP Protocol
    ▼
┌─────────────────────────────┐
│       semantic-mcp          │
│    (FastMCP MCP Server)     │
├─────────────────────────────┤
│  Discovery → mcp-index API  │
│  Execution → ZMQ + Sessions │
└─────────────────────────────┘
    │               │
    ▼               ▼
mcp-index       MCP Servers
(Elasticsearch) (stdio/http)

Related Projects

• mcp-index - Elasticsearch-based semantic discovery service for MCP servers. Required backend for semantic-mcp to enable semantic search and server registry.

Installation

Option 1: uvx (Recommended)

uvx semantic-mcp serve --transport stdio

Option 2: pip/uv

# Install from PyPI
pip install semantic-mcp

# Or with uv
uv pip install semantic-mcp

# Run
semantic-mcp serve --transport stdio

Option 3: Docker

docker pull milkymap/semantic-mcp:0.2

docker run -d \
  -p 8001:8001 \
  -e DISCOVERY_URL=http://your-discovery-service \
  -e DISCOVERY_API_KEY=your-key \
  milkymap/semantic-mcp:0.2 serve --transport streamable-http --port 8001

Option 4: From source

git clone https://github.com/milkymap/semantic-mcp
cd semantic-mcp
uv sync
uv run semantic-mcp serve

Configuration

Environment Variables

MCP Client Integration

Claude Code / Cline (uvx)

Add to your .mcp.json or MCP config:

{
  "mcpServers": {
    "semantic-mcp": {
      "command": "uvx",
      "args": ["semantic-mcp", "serve", "--transport", "stdio"],
      "env": {
        "DISCOVERY_URL": "https://your-discovery-service",
        "DISCOVERY_API_KEY": "your-api-key"
      }
    }
  }
}

Claude Desktop (Docker)

{
  "mcpServers": {
    "semantic-mcp": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "DISCOVERY_URL", "-e", "DISCOVERY_API_KEY",
        "--add-host=host.docker.internal:host-gateway",
        "milkymap/semantic-mcp:0.2", "serve", "--transport", "stdio"
      ],
      "env": {
        "DISCOVERY_URL": "http://host.docker.internal:8000",
        "DISCOVERY_API_KEY": "your-key"
      }
    }
  }
}

Remote HTTP Server

Start the server:

semantic-mcp serve --transport streamable-http --host 0.0.0.0 --port 8001

Client configuration:

{
  "mcpServers": {
    "semantic-mcp": {
      "url": "http://your-server:8001/mcp"
    }
  }
}

Available Operations

semantic-mcp exposes a single semantic_router tool with these operations:

Discovery (lightweight)

Exploration (full details)

Lifecycle

Execution

Workflow

1. DISCOVER    search_tools("your need")         → Find relevant tools
       ↓
2. EXPLORE     get_server_info(server)           → Check capabilities
               get_server_tools(server)          → List available tools
       ↓
3. UNDERSTAND  get_tool_details(server, tool)    → Get full schema (REQUIRED)
       ↓
4. START       manage_server(server, "start")    → Start the MCP server
       ↓
5. EXECUTE     execute_tool(server, tool, args)  → Run the tool
       ↓
6. CLEANUP     manage_server(server, "shutdown") → Stop when done (optional)

Important rules:

• Always call get_tool_details before execute_tool to understand the schema
• Always call manage_server(start) before executing tools
• Use in_background=true for long-running operations, then poll_task_result
• Large responses are automatically offloaded; use get_content(ref_id) to retrieve

Architecture

Development

# Install with dev dependencies
uv sync --group dev

# Run tests
uv run pytest tests/ -v

License

MIT