Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@MCPNexus find tools for managing GitHub issues"
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.
The discovery and routing layer that keeps MCP servers out of your context window until you actually need them.
The Model Context Protocol lets an LLM talk to any number of servers — GitHub, Slack, Postgres, your internal tools. The catch: most clients load every tool definition from every configured server at startup. Six servers can mean 70+ tool schemas and thousands of tokens spent before the conversation even starts, most of which the model never touches in a given session.
Related MCP server: MCP Coordinator
MCP Nexus sits in front of your MCP servers as a thin discovery layer. Instead of loading everything up front, the LLM asks for what it needs — by server or by tool — and MCP Nexus resolves the request and connects on demand. You keep your existing MCP servers unmodified; MCP Nexus only changes how (and when) their tools reach the model's context.
Two modes cover the two ways teams actually want this to work:
Discovery Mode | Dynamic Mode | |
Granularity | Whole server | Individual tool |
Tools always in context | 4 ( | 1 ( |
Best for | "Connect me to GitHub" style workflows | Cherry-picking one tool from many servers |
After resolution | LLM talks to the server directly — MCP Nexus exits the data path | MCP Nexus lazy-connects and stays in the loop per tool call |
v1.0.0 adds Lazy Schema Loading: Discovery Mode can hand back a stub tool list (names only, no schemas) and fetch a single tool's full schema only when it's about to be called — about 92% fewer tokens than loading everything.
Step 1 LLM -> mcpd_find("github issues")
MCP Nexus searches the registry
returns: { id: "github", tools: ["create_issue", "search_repos", ...] }
Step 2 LLM -> mcpd_connect("github")
MCP Nexus starts the GitHub MCP server
returns: 20 tools now available as github__create_issue, etc.
Step 3 LLM -> github__create_issue({ title: "...", body: "..." })
MCP Nexus proxies to the GitHub MCP server, returns the resultScenario | Tools in context | ~Tokens |
All 6 servers loaded directly | 78 | ~4,778 |
Discovery Mode (before connect) | 4 | ~305 |
Discovery Mode (after connect — 1 server) | 4 + 20 | ~1,578 |
No proxy, no changes to the target MCP server required:
mcpd_find("github") → choose a server
mcpd_connect("github", lazy_mode=true) → get a stub list (20 tools, no schemas, ~132 tokens)
mcpd_get_schema("github", "create_issue") → fetch one full schema (~80 tokens)
github__create_issue(...) → direct call, as always
Savings: ~92% vs. a full load (292 vs. 2,064 tokens for a typical 2-tool session). Pass --sync-on-start so the registry has schemas cached ahead of time via nexus-sync.
Step 1 LLM -> find_tools("create issue, post slack message")
MCP Nexus searches the tool index across all servers
returns: create_issue (github), post_message (slack)
both tools added to tools/list
Step 2 LLM -> create_issue({ title: "Bug #42" })
MCP Nexus lazy-connects to the GitHub MCP server
executes create_issue, returns the result
Step 3 LLM -> post_message({ channel: "#eng", text: "Done" })
MCP Nexus lazy-connects to the Slack MCP server
executes post_message, returns the resultScenario | Tools in context | ~Tokens |
All 6 servers loaded directly | 78 | ~4,778 |
Dynamic Mode (before find) | 1 | ~100 |
Dynamic Mode (2 found tools) | 3 | ~300 |
# Core — keyword search, stdio transport
pip install mcpnexus
# With HTTP and SSE transport (remote MCP servers)
pip install mcpnexus[http]
# With semantic search (sentence-transformers)
pip install mcpnexus[embeddings]
# Full installation
pip install mcpnexus[all]
# Development
pip install mcpnexus[dev]The registry is a lightweight JSON catalog of your MCP servers and their tool summaries. Build it from your MCP client's config (e.g. Cursor: ~/.cursor/mcp.json, Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json):
nexus-sync --config /path/to/your/mcp-config.json --output registry/mcpd-registry.jsonDiscovery Mode (4 tools, connect to one server at a time):
{
"mcpServers": {
"nexus-server": {
"command": "nexus-server",
"args": ["--registry", "/path/to/mcpd-registry.json", "--sync-on-start"]
}
}
}Dynamic Mode (1 tool, cherry-pick tools across all servers):
{
"mcpServers": {
"nexus-gateway": {
"command": "nexus-gateway",
"args": ["--registry", "/path/to/mcpd-registry.json"]
}
}
}Or invoke the Python module directly (avoids PATH issues):
{
"mcpServers": {
"nexus-gateway": {
"command": "python",
"args": ["-m", "mcpnexus.dynamic.server", "--registry", "/path/to/mcpd-registry.json"]
}
}
}nexus-benchmark --registry registry/mcpd-registry.json(Generate your registry first with nexus-sync.)
┌─────────────────────────────────────────────────────────────┐
│ LLM / AI Client │
└──────────────────────┬──────────────────────────────────────┘
│ MCP (stdio / JSON-RPC 2.0)
┌────────────┴─────────────┐
│ │
┌──────▼──────┐ ┌───────▼──────┐
│ Discovery │ │ Dynamic │
│ Mode │ │ Mode │
│ │ │ │
│ mcpd_find │ │ find_tools │
│ mcpd_list │ │ │
│ mcpd_connect│ │ LazyPool │
│ mcpd_get_schema│ │ │
└──────┬──────┘ └───────┬──────┘
│ │
└────────────┬─────────────┘
│
┌────────────▼─────────────┐
│ Shared Core │
│ │
│ Registry (mcpd-registry) │
│ KeywordSearchEngine │
│ ToolSearchEngine │
│ HybridSearch (TF-IDF + │
│ sentence-transformers) │
│ NexusConnector │
│ ├─ stdio transport │
│ ├─ streamable-http │
│ └─ SSE transport │
└───────────────────────────┘A discovery layer, not a permanent proxy. In Discovery Mode, once mcpd_connect resolves, the LLM gets direct tool access to the connected server. In Dynamic Mode, server connections stay lazy — a server process starts only when one of its tools is actually called.
Offline-first registry. Tool summaries (name, description, tags) are captured at sync time. Searches run against the cached registry with zero network traffic; full tool schemas load only on connection.
Search degrades gracefully. Keyword search (TF-IDF with synonyms) is the default — always available, no extra dependencies. Semantic search is optional (pip install mcpnexus[embeddings]): when installed, sentence-transformers embeddings blend with keyword results, which helps for loosely-phrased natural-language queries like "a tool for reading web pages" → Playwright. The keyword synonym table also understands multilingual input (e.g. Polish query terms resolve to the right English tool concepts). Keyword-first keeps installs frictionless when you don't need semantic search.
The registry file (mcpd-registry.json) is a JSON catalog of MCP servers:
{
"mcpd_version": "1.0",
"metadata": {
"name": "My MCP Registry",
"description": "Personal registry of MCP servers"
},
"servers": [
{
"id": "github",
"name": "GitHub MCP Server",
"description": "Official GitHub MCP server (remote). Repositories, issues, pull requests, and code search",
"version": "remote-2025-11",
"transport": {
"type": "streamable-http",
"url": "https://api.githubcopilot.com/mcp/",
"headers": { "Authorization": "Bearer ${GITHUB_MCP_PAT}" }
},
"tags": ["github", "git", "code", "issues"],
"tools_summary": [
{
"name": "issue_write",
"description": "Create or update an issue or pull request",
"tags": ["issues", "create"]
}
],
"estimated_tools_count": 90,
"enabled": true,
"last_synced": "2026-06-11T00:00:00Z"
}
]
}Full schema: registry/schemas/mcpd-schema.json
mcpnexus/
├── mcpnexus/ # Python package
│ ├── __init__.py # Public API and version
│ ├── models.py # Shared dataclasses
│ ├── registry.py # Registry loader (mcpd-registry.json)
│ ├── connector.py # MCP connector — stdio, HTTP, SSE transports
│ ├── sync.py # Registry builder (sync from mcp.json)
│ ├── benchmark.py # Token savings measurement
│ ├── search/
│ │ ├── keyword_search.py # Server-level TF-IDF search
│ │ ├── tool_search.py # Tool-level TF-IDF search
│ │ ├── embeddings.py # Sentence-transformer embedding engine
│ │ └── hybrid.py # Hybrid keyword + semantic search
│ ├── discovery/
│ │ └── server.py # Discovery Mode MCP server
│ └── dynamic/
│ ├── server.py # Dynamic Mode MCP server
│ ├── tool_index.py # O(1) tool lookup index
│ └── lazy_pool.py # On-demand connection pool
├── registry/
│ ├── mcpd-registry.example.json # Example registry
│ └── schemas/
│ └── mcpd-schema.json # JSON Schema for registry validation
├── docs/
│ ├── specification.md # Protocol specification
│ ├── architecture.md # Architecture deep-dive
│ ├── registry-format.md # Registry format reference
│ └── dynamic-mcp.md # Dynamic Mode guide
├── examples/
│ ├── cursor-config-discovery.json
│ ├── cursor-config-dynamic.json
│ └── README.md
├── tests/ # 491 tests, 100% coverage
└── pyproject.tomlgit clone https://github.com/KrzysztofAugiewicz/MCPNexus.git
cd MCPNexus
pip install -e ".[dev]"
# Run tests
pytest
# Run tests with coverage
pytest --cov=mcpnexus --cov-report=term-missing
# Run end-to-end integration test
python test_e2e.py
# Benchmark token savings (generate registry first with nexus-sync)
nexus-benchmark --registry registry/mcpd-registry.jsonCommand | Description |
| Start the Discovery Mode MCP server |
| Start the Dynamic Mode MCP server |
| Build or update the registry from an mcp.json config |
| Measure token savings for a given registry |
All commands accept --help for the full option reference.
Transport | Install extra | Use case |
stdio | (core) | Local process-based MCP servers |
Streamable HTTP |
| Remote HTTP MCP servers |
SSE |
| Legacy remote servers (Server-Sent Events) |
Transport type is resolved automatically from the registry entry's transport.type field.
Protocol Specification — Tool schemas, message formats, handshake sequence
Architecture — Data flow, shared core, design decisions
Registry Format — Full registry schema reference
Dynamic Mode Guide — Dynamic Mode deep-dive
Releases are published automatically when a GitHub Release is created. Prerequisites:
Add PYPI_API_TOKEN to repository secrets (create at pypi.org/manage/account/token)
Create a release with a tag (e.g. v1.0.1)
The publish workflow builds and uploads to PyPI.
Contributions are welcome. Please read CONTRIBUTING.md before opening a pull request. For bug reports and feature requests, use GitHub Issues.
Krzysztof Augiewicz — Lead Architect & Creator — LinkedIn · GitHub
Kacper Pisarczyk — Core Contributor, Discovery & Registry Systems — LinkedIn
Sebastian Pawłowski — Advisory & QA Support (testing, hardware/software provisioning) — LinkedIn
Mateusz Wiszniowski — Core Contributor
Full details in AUTHORS.md.
Connect directly to an MCP server by ID and load its tools. After this, the server's tools are available for direct use - MCP Nexus is no longer involved in tool calls. Use lazy_mode=True (default) to get stub tools first, then mcpd_get_schema for full schemas.
| Name | Required | Description | Default |
|---|---|---|---|
| lazy_mode | No | If true (default), return stub tools without schemas. Use mcpd_get_schema to fetch schemas on demand. Saves ~90%% tokens. | |
| server_id | Yes | ID of the MCP server to connect to (from mcpd_find or mcpd_list) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (openWorldHint=true), description explains that after connection, MCP Nexus is no longer involved and lazy_mode behavior. Adds meaningful context about side effects and state change.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences that front-load the main purpose and then add essential usage guidance. No redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Provides key behavioral context but lacks detail on response format, error handling, or connection persistence. For a tool with no output schema, more completeness would help an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with detailed parameter descriptions. The tool description reinforces the usage flow but does not add new parameter-level insight beyond what the schema already provides, meeting baseline expectations.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool connects to an MCP server by ID and loads its tools. Distinguishes from siblings by explaining the role in the workflow (connect first, then get_schema for schemas).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Describes when to use this tool (to make server tools available) and provides a recommended flow with lazy_mode and mcpd_get_schema. Lacks explicit 'when not to use' but context is clear given sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search MCP Nexus for MCP servers that have the tools you need. Returns server IDs, relevance scores, and matched tool names. Use this FIRST to discover which MCP server to connect to.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | What tools do you need? E.g. 'create github issue', 'send slack message' | |
| max_results | No | Maximum number of results (default: 3) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true, and the description confirms a read operation by describing it as a search. It adds useful context about the return format (server IDs, relevance scores, matched tool names) and its role as a discovery tool. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is exceptionally concise with two sentences that convey purpose, output, and usage guidance. Every word is necessary, and it is front-loaded with the action and key details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no output schema, the description adequately specifies the return values (server IDs, relevance scores, matched tool names). It is complete for a search/discovery tool, and the sibling tools provide a clear context for its use in a workflow.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 100% description coverage, so the description does not need to repeat parameter meanings. However, it adds value by providing an example for the 'query' parameter ('E.g. 'create github issue', 'send slack message''), which helps the agent understand the expected input.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Search', the resource 'MCP Nexus for MCP servers', and what it returns ('server IDs, relevance scores, and matched tool names'). It also distinguishes from siblings by advising 'Use this FIRST' as the discovery step before connecting or getting schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context to use this tool as the initial discovery step ('Use this FIRST to discover which MCP server to connect to'). It implies a specific workflow with sibling tools (mcpd_get_schema, mcpd_connect), though it does not explicitly state when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get full inputSchema for ONE tool from a server. Use after mcpd_connect(lazy_mode=true) to avoid loading all schemas at once. Returns the schema needed to call the tool.
| Name | Required | Description | Default |
|---|---|---|---|
| server_id | Yes | Server ID (e.g. github) | |
| tool_name | Yes | Tool name (e.g. create_issue) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true and openWorldHint=false. The description adds useful behavioral context by explaining the lazy loading pattern and that the tool returns the schema needed to call the tool. It does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long and front-loaded: the first sentence states the core purpose, the second adds usage context. Every sentence is essential and there is no wasted text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with 2 parameters and no output schema, the description provides sufficient context: it explains the purpose, usage in the lazy workflow, and what is returned ('the schema needed to call the tool'). It is complete without needing additional details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the input schema already fully documents both parameters. The description adds no additional meaning beyond what is in the schema. Baseline is 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'Get full inputSchema for ONE tool from a server', using a specific verb and clear resource. It differentiates from sibling tools (mcpd_find, mcpd_list, mcpd_connect) by specifying that it retrieves a single schema, not a list or connection.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit usage guidance: 'Use after mcpd_connect(lazy_mode=true) to avoid loading all schemas at once.' It clearly indicates when to use this tool, though it does not explicitly mention when not to use it or provide direct alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all MCP servers available in MCP Nexus with their names, descriptions, tags, and tool counts.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the read-only nature is covered. The description adds that the tool returns specific fields (names, descriptions, tags, tool counts), which is useful context. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no extraneous information. Every word serves a purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with no parameters and no output schema, the description provides all necessary context: what it lists and the fields returned.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are zero parameters, so schema coverage is 100%. The description adds no parameter info because none exist. Baseline for 0 params is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List' and resource 'MCP servers' and specifies the returned fields (names, descriptions, tags, tool counts). It distinguishes from siblings like mcpd_get_schema which targets a single server's schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for obtaining an overview of all servers. It does not explicitly state when not to use it or provide alternatives, but the sibling tool names hint at different purposes (e.g., mcpd_get_schema for details on a specific server).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v1.0.2mcpd_connectmcpd_findmcpd_get_schemamcpd_listScored across 4 tools
Each tool has a clear, distinct purpose: listing all servers, searching for servers, connecting to a server, and retrieving a tool schema. No overlaps.
All tools start with 'mcpd_' and use snake_case, but the verb patterns vary: some have noun suffixes (get_schema) while others are bare verbs (find, list, connect). Mostly consistent.
With 4 tools, the server is well-scoped for its role as a registry/hub. Each tool earns its place, covering discovery, connection, and schema retrieval.
The tools cover the core workflow of discovering and connecting to servers. A minor gap is the lack of a disconnect or management tool, but the description indicates that after connect, MCP Nexus is no longer involved.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
The OpenRouter for tools. One MCP connection gives any AI agent 254 hosted tools, pay per call.
Search, vet & assemble MCP servers from your agent: verified tools, risk labels, and trust scores.
The Remote MCP server acts as a standardized bridge between LLM applications (like Claude, ChatGPT, and Cursor) and external services, enabling AI agents to access external tools and resources. Its primary capability is providing a centralized search tool to discover other MCP servers and their respective tools. Unlike local implementations, it runs remotely with OAuth authentication and permission controls for security.
MCP server for progressive tool usage at any scale (see https://klavis.ai)
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/KrzysztofAugiewicz/MCPNexus'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
