MCP-OS · Model Context Protocol Orchestration System

What is MCP-OS?

MCP-OS is a Model Context Protocol orchestration system that manages MCPs like an operating system manages processes—loading them on demand and unloading when idle. Its current phase, MCP-Retriever, uses vector retrieval to reduce prompt bloat by injecting only the top‑k MCP descriptions into the context window, saving up to ~70% of prompt tokens. It is designed for developers building LLM agents that need to dynamically select relevant MCPs.

How to use MCP-OS?

Clone the repository, install dependencies (npm install), build the vector index from an MCP list (npm run build:index --src ./mcp_list.json --out ./index), then start the retriever server (npm run start:retriever), which listens on 127.0.0.1:5500 over HTTP+SSE. Wire it into your LLM/agent by configuring mcpServers (e.g., in Claude Desktop) or by calling the REST endpoint POST /match with a task description.

Key features of MCP-OS

• Vector retrieval of top‑k MCPs from a local index.
• Slim prompt template that reduces prompt tokens by ~70%.
• Pluggable vector store backends (FAISS, Qdrant, Milvus, etc.).
• Default embedding backend using OpenAI embeddings.
• REST endpoint (/match) for task‑to‑MCP matching.
• Roadmap includes health‑check daemon, runtime manager, and policy sandbox.

Use cases of MCP-OS

• Reduce context‑window waste by dynamically selecting only relevant MCPs.
• Automatically match a user task to the appropriate MCP server from a large pool.
• Keep MCP connections clean by relying on a retriever instead of loading all servers.
• Enable LLMs to focus on planning and analysis rather than wading through MCP descriptions.

FAQ from MCP-OS

I get poor retrieval quality—how do I tune it?

Increase topK for higher recall, switch to a stronger embedding model, or refine task‑text normalization rules.

How do I plug in my own vector store?

Implement the VectorStore interface (e.g., src/store/yourStore.ts) and swap the backend.

What runtime dependencies does MCP-OS require?

Node.js and npm. It defaults to OpenAI embeddings but supports other backends with additional configuration.

Where does the MCP metadata live?

In a local JSON file (mcp_list.json) that you provide when building the index. The index is stored on disk.

Does MCP-OS support authentication or transport beyond HTTP+SSE?

The current retriever server uses HTTP+SSE. Planned milestones include runtime management and policy sandbox for fine‑grained auth and rate limiting.