# Nexus Mcp Extension

> Nexus-MCP solves Tool Space Interference in LLMs. It uses a single gateway to aggregate multiple MCP servers and employs a deterministic 4-phase workflow (Discovery, Mapping, Schema Verification, Bridged Execution) to prevent context saturation and tool hallucinations, maintaining reasoning accuracy with massive tool ecosystems.

- **Type:** MCP server
- **Install:** `agentstack add mcp-tanaikech-nexus-mcp-extension`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [tanaikech](https://agentstack.voostack.com/s/tanaikech)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [tanaikech](https://github.com/tanaikech)
- **Source:** https://github.com/tanaikech/nexus-mcp-extension
- **Website:** https://medium.com/google-cloud/nexus-mcp-a-unified-gateway-for-scalable-and-deterministic-mcp-server-aggregation-3211f0adc603

## Install

```sh
agentstack add mcp-tanaikech-nexus-mcp-extension
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Nexus-MCP: A Unified Gateway for Scalable and Deterministic MCP Server Aggregation

[](LICENCE)

**Nexus-MCP** is a meta-server designed to solve "Tool Space Interference" (TSI) in Large Language Models (LLMs). By aggregating multiple MCP servers into a single gateway, it prevents context window saturation and tool hallucinations using a defensive, deterministic 4-phase workflow.

---

## 🏗 Architecture and Workflow

Nexus-MCP acts as an intelligent router between the LLM agent and your ecosystem of tools.

It enforces a strictly deterministic loop to maintain reasoning accuracy:
1.  **Discovery:** Aggregates tools from all connected servers.
2.  **Mapping:** Identifies the specific `[SERVER_ID]` and `[TOOL_ID]`.
3.  **Schema Verification:** Retrieves technical schemas *only* for the selected tool.
4.  **Bridged Execution:** Routes the command to the correct downstream server.

---

## 🛠 Prerequisites

*   **Node.js**: (Latest LTS recommended)
*   **Gemini CLI**: Installed and authenticated.
    ```bash
    npm install -g @google/gemini-cli
    ```
*   *(Optional)* **Google Antigravity** for advanced agentic workflows.

---

## 📦 Installation

Nexus-MCP is distributed as an extension for the Gemini CLI.

```bash
gemini extensions install https://github.com/tanaikech/nexus-mcp-extension
```

---

## ⚙️ Configuration

Nexus-MCP does not have tools of its own; it manages *other* MCP servers. You must define these downstream servers in a configuration file.

### 1. Create the Configuration File
Create a file named `mcp_config.json` (e.g., in your home directory).
*   **Tip:** You can find the paths to your installed extensions by running `gemini extensions list`.

**Example `mcp_config.json`:**

```json
{
  "mcpServers": {
    "google-workspace": {
      "command": "node",
      "args": [
        "/home/username/.gemini/extensions/google-workspace/dist/index.js"
      ]
    },
    "tools-for-mcp-server": {
      "command": "node",
      "args": [
        "/home/username/.gemini/extensions/tools-for-mcp-server-extension/mcp-server/src/index.js"
      ],
      "timeout": 300000
    }
  }
}
```

### 2. Set the Environment Variable
Point Nexus-MCP to your configuration file. This variable is required for both Gemini CLI and Antigravity.

**Linux/macOS:**

```bash
export MCP_SERVER_LIST="/home/username/mcp_config.json"
```

**Windows (PowerShell):**

```powershell
$env:MCP_SERVER_LIST="C:\Users\username\mcp_config.json"
```

### 3. Disable Downstream Extensions

**Crucial Step:** To prevent "Tool Space Interference," disable the individual extensions in Gemini CLI so they are *only* accessed through Nexus-MCP.

```bash
gemini extensions disable google-workspace
gemini extensions disable tools-for-mcp-server
```

---

## 🚀 Usage & Validation

### Part 1: Using with Gemini CLI

Launch the Gemini CLI. You can confirm the connection status by running `/mcp`.

#### 1. Server Introspection

Check which tools are currently aggregated by Nexus.

> **User:** "Run a tool get-server-information."

*Result: The agent sees the aggregated total of tools (e.g., 206 tools) via the single gateway.*

#### 2. Specific Tool Execution (Weather Example)

> **User:** "What is the weather forecast for Tokyo at noon today?"

*Result: The agent searches the aggregated list, identifies the weather tool in `tools-for-mcp-server`, and executes it successfully.*

#### 3. Routing Control

If multiple servers offer similar functionality (e.g., Calendar), you can force a specific route.

> **User:** "Show me today's schedule. Use google-workspace."

#### 4. Complex Multi-Step Workflow

Nexus-MCP excels at chaining tools across different servers (e.g., generating content, creating a Google Doc, and converting it).

> **User:** "Write a comprehensive article about developing Google Apps Script (GAS)... Create a new Google Document, insert the content, and provide the shareable URL."

---

### Part 2: Using with Google Antigravity

Nexus-MCP integrates seamlessly into Google Antigravity for visual agentic workflows.

#### 1. Set System Rules

1.  Open Antigravity > **Customizations** > **Rules**.
2.  Copy the content of `GEMINI.md` (included in this repository) and paste it here.
    *   *This teaches the agent the 4-Phase Algorithm (Discovery -> Mapping -> Schema -> Execution).*

#### 2. Configure MCP Server
1.  Go to **MCP servers** > **Manage MCP servers** > **View raw config**.
2.  Add Nexus-MCP manually:
    ```json
    {
      "mcpServers": {
        "nexus-mcp": {
          "command": "node",
          "args": [
            "/path/to/nexus-mcp-extension/mcp-server/src/nexus-mcp.js"
          ]
        }
      }
    }
    ```

#### 3. Execution Example

> **User:** "Write an article... convert the Google Document to a PDF file, and send an email to `user@example.com`..."

**Implementation Plan:**

Antigravity analyzes the request and builds a visual plan, mapping tasks to specific tools within the Nexus gateway.

**Walkthrough:**

The agent executes the plan sequentially—generating text, creating the doc, converting to PDF, and sending the email.

**Outcome:**

The email is received with the correct attachment, proving the successful orchestration of multiple tools.

---

# Licence

[MIT](LICENCE)

# Author

[Tanaike](https://tanaikech.github.io/about/)

[Donate](https://tanaikech.github.io/donate/)

# Update History

- v0.0.1 (December 25, 2025)

  1. Initial release.

[TOP](#top)

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [tanaikech](https://github.com/tanaikech)
- **Source:** [tanaikech/nexus-mcp-extension](https://github.com/tanaikech/nexus-mcp-extension)
- **License:** MIT
- **Homepage:** https://medium.com/google-cloud/nexus-mcp-a-unified-gateway-for-scalable-and-deterministic-mcp-server-aggregation-3211f0adc603

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-tanaikech-nexus-mcp-extension
- Seller: https://agentstack.voostack.com/s/tanaikech
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.