Ansam MCP server
Commit Oct 25, 2026Manages, indexes, and proxies requests across large ecosystems of MCP servers using hybrid search and an LRU-cached proxy system.
Also known as MriBoyd/Ansam
- Stars
- 0
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Oct 25, 2026
- License
- MIT
What is Ansam MCP?
Ansam is an MCP server. Manages, indexes, and proxies requests across large ecosystems of MCP servers using hybrid search and an LRU-cached proxy system.
Summary generated from the project's README
About Ansam MCP server
Managing and searching through hundreds of MCP servers becomes possible with Ansam, which acts as a central gateway for large tool ecosystems. It allows AI models to find specific capabilities using natural language through a three-stage retrieval pipeline. This system uses Qdrant to combine semantic and lexical vectors with ColBERT reranking to ensure high-precision results when a user requests a specific function.
Developers can deploy this discovery server using stdio, SSE, or HTTP transports. The architecture includes an LRU-cached proxy system that maintains up to 50 active connections by default to prevent socket exhaustion. It also features circuit breakers to stop cascading failures and an AuthManager to handle token-based security for the proxied servers. To function, the setup requires Python 3.10+ and a running Qdrant vector database instance.
What you can do with it
- 1Find tools using natural languageAsk an AI client to locate specific capabilities like fetching weather or sending emails across a massive registry.
- 2Manage large-scale server connectionsHandle connections to hundreds of different MCP servers without exhausting system resources.
- 3Maintain system stability during failuresPrevent a single unresponsive server from causing a total system crash using circuit breakers.
Written from the project's README. Every use case is checked against a quote from it.
Automated checks
Ran Nov 15, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablemriboyd/ansam is public and reachablegithub.com/mriboyd/ansam ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-10-25github.com/mriboyd/ansam ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubAnsam
Ansam is a high-performance Model Context Protocol (MCP) Discovery Server designed to manage, index, and proxy requests across a massive ecosystem of 1000+ MCP servers. It provides AI models with a unified interface to search for specific tools using advanced hybrid retrieval and execute them safely via a dynamic, LRU-cached proxy system.
🚀 Key Features
- Dynamic Proxy Management: Seamlessly handle connections to hundreds of MCP servers. Uses an LRU Cache (default: 50 active connections) to optimize resource usage and prevent socket exhaustion.
- Advanced Hybrid Tool Search: A three-stage retrieval pipeline using Qdrant:
- Retrieval: Combines Dense (Semantic) and Sparse (Lexical) vectors with BM25.
- Reranking: In-database ColBERT late interaction for high-precision results.
- Fusion: Optimized weighted fusion of multiple scoring signals.
- Universal Tool Extraction: Built-in
MCPRegistryManagerto discover and extract tool definitions from stdio, SSE, and HTTP transports. - Production-Grade Reliability:
- Circuit Breakers: Prevent cascading failures when downstream servers are unresponsive.
- Rate Limiting: Granular global and per-server rate control.
- Authentication: Integrated
AuthManagerfor handling token-based security for proxied servers.
- Flexible Deployment: Supports stdio, SSE, and HTTP server transports for the discovery interface itself.
🏗️ Architecture Overview
Ansam acts as an intelligent gateway between an AI model and a vast collection of MCP tools:
- Discovery Layer: Scans known MCP servers and builds a comprehensive registry (
mcp_servers.json). - Indexing Layer: Processes the registry and populates a Qdrant vector database with semantic embeddings and lexical tokens.
- Search Layer: When a user asks for a tool, Ansam performs a hybrid search to find the most relevant tool across all registered servers.
- Execution Layer: When a tool is called, Ansam dynamically creates a proxy connection to the target server, executes the command, and returns the result, maintaining the connection in a "hot" cache for subsequent calls.
🛠️ Installation & Setup
Prerequisites
- Python 3.10+
- Qdrant Vector Database (Running on port 6333)
# Using Docker docker run -d --name qdrant -p 6333:6333 -p 6334:6334 qdrant/qdrant # Or using Docker Compose docker-compose up -d
1. Clone & Install Dependencies
git clone https://github.com/MriBoyd/Ansam.git
cd Ansam
# Create virtual environment and install dependencies
python3 -m venv .venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
pip install -r requirements.txt
pip install -e ".[dev]"
# Set up local configuration
cp .env.example .env
📖 Quick Start
1. Extract Tools (Optional)
If you have new servers to add, use the registry manager to extract their tool definitions:
python src/mcp_registry_manager.py --name my-server --transport stdio --command "python" --args "path/to/server.py" --output src/mcp_servers.json --merge
2. Index Tools
Populate the Qdrant database with the tools defined in your configuration:
python src/scripts/index_tools.py --file src/mcp_servers.json
3. Run the Discovery Server
Start the Ansam MCP server:
# Default: stdio transport
python src/mcp_server_production.py
# Or use SSE/HTTP transport
python src/mcp_server_production.py --sse --port 8000
🔍 Search Capabilities
Ansam exposes a search_tools tool that allows models to find capabilities using natural language.
Example Query: "I need a tool to fetch weather data and send an email."
Retrieval Pipeline:
- Dense:
sentence-transformers/all-MiniLM-L6-v2 - Sparse:
Splade_PP_en_v1 - Reranker:
colbert-ir/colbertv2.0
⚙️ Configuration
Key settings can be adjusted in src/config.py or via Environment Variables:
| Variable | Default | Description |
|---|---|---|
QDRANT_URL |
http://localhost:6333 |
URL of the Qdrant instance |
MAX_OPEN_CONNECTIONS |
32 |
Max concurrent proxy connections in LRU cache |
GLOBAL_RATE |
10.0 |
Global requests per second limit |
PER_SERVER_RATE |
2.0 |
Per-server requests per second limit |
CB_FAILURE_THRESHOLD |
5 |
Failures before circuit breaker opens |
DEVICE |
cuda/cpu |
Processing device for embeddings |
📂 Project Structure
src/mcp_server_production.py: Main entry point for the discovery server.src/mcp_registry_manager.py: Universal tool discovery and registry maintenance.src/hybrid_searcher.py: Core search engine logic.src/auth_manager.py: Authentication handler for proxied servers.src/circuit_breaker.py: Fault tolerance implementation.src/scripts/index_tools.py: Data ingestion script for Qdrant.src/mcp_servers.json: The source-of-truth configuration for all proxied servers.
🧪 Testing
Run the test suite to ensure system integrity:
# Unit tests
pytest tests/
# Benchmarks
python tests/benchmark_search.py
🤝 Contributing
Contributions are warmly welcomed! We are actively cultivating a beginner-friendly open-source community.
- Looking for a good place to start? Check our curated Good First Issues.
- Please read our CONTRIBUTING.md for local development setup, testing, and pull request guidelines.
- To see recent releases and changes, check the CHANGELOG.md.
📜 License
This project is licensed under the terms of the MIT License. See LICENSE for details.
Ansam MCP questions
How does Ansam manage connections to many MCP servers?
It uses an LRU Cache to optimize resource usage and prevent socket exhaustion when handling connections.