How do I use semantic-mcp?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@semantic-mcp find tools for image analysis" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

semantic-mcp

by milkymap

Overview Schema Related Servers Score Discussions

Python

Hybrid

Semantic MCP

PyPI version Docker

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 MCP server: one-mcp

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

Variable	Description	Default
`DISCOVERY_URL`	Discovery service API URL	`http://localhost:8000`
`DISCOVERY_API_KEY`	API key for discovery authentication	None
`DISCOVERY_ENCRYPTION_KEY`	Key to decrypt sensitive env vars in server configs	None
`TOOL_OFFLOADED_DATA_PATH`	Path for large result offloading	`/tmp/mcp_offloaded`
`MAX_RESULT_TOKENS`	Max tokens before content offloading	`4096`
`BACKGROUND_QUEUE_SIZE`	Max background tasks in queue	`100`
`OPENAI_API_KEY`	OpenAI API key (for image descriptions)	None

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)

Operation	Description
`search_tools`	Search for tools using natural language
`search_servers`	Search for servers using natural language
`list_servers`	List all registered servers
`get_server_tools`	List tools on a server
`get_statistics`	Get server/tool counts

Exploration (full details)

Operation	Description
`get_server_info`	Get detailed server information
`get_tool_details`	Get full tool schema and description

Lifecycle

Operation	Description
`manage_server`	Start or shutdown a server
`list_running_servers`	List currently running servers

Execution

Operation	Description
`execute_tool`	Execute a tool on a running server
`poll_task_result`	Check background task status
`cancel_task`	Cancel a running background task
`list_tasks`	List all background tasks
`get_content`	Retrieve offloaded content by reference ID

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

Component	Description
RuntimeEngine	Core runtime managing ZMQ communication and server lifecycle
DiscoveryClient	HTTP client for discovery service API
ContentManager	Large result offloading (text chunking, images)
BackgroundTasks	Priority queue for async tool execution
FastMCP	MCP server framework exposing tools to LLMs

Development

# Install with dev dependencies
uv sync --group dev

# Run tests
uv run pytest tests/ -v

License

MIT

This server cannot be installed

license - permissive license

quality - not tested

maintenance

How are these scores calculated?

Maintenance

–Maintainers

–Response time

–Release cycle

–Releases (12mo)

Commit activity

Resources

GitHub Repository

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Latest Blog Posts

Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly
Lightport: Open-Sourcing Glama's AI Gateway
By punkpeye on April 27, 2026.
OpenAI
open source

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/milkymap/semantic-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server