Nested MCPs

Orchestrates an agent-driven retrieval and synthesis flow by coordinating a vector store MCP and a separate orchestrator MCP.

typescript

0

GitHub Stars

typescript

Language

3 months ago

First Indexed

2 months ago

Catalog Refreshed

Documentation & install

Readme and setup notes from the catalogue, plus a client-ready config you can copy for your MCP host.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "origin-digital-llc-nested-mcps": {
      "command": "uv",
      "args": [
        "run",
        "python",
        "src/mcp2_orchestrator/server.py"
      ],
      "env": {
        "MCP1_SERVER_PATH": "/absolute/path/to/mcp1",
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}

This two-layer MCP setup demonstrates how a higher-level orchestrator can act as a client to a lower-level, in-memory vector store, enabling multi-hop retrieval and synthesis through an agent-driven loop. It is useful for experimenting with nested MCP workflows where a central component coordinates retrieval, reasoning, and final answers across separate MCPs.

How to use

You will run an MCP server that exposes an ask tool. When you trigger the ask tool with a question, the orchestrator launches a reasoning loop that decomposes the task, retrieves relevant information from the vector store, and synthesizes a final answer. Independent tasks run in parallel to speed up responses.

How to install

Prerequisites: Python 3.10+ and a modern shell. You will also need a runtime environment capable of running two MCP components in sequence.

Additional sections

Setup includes three main steps: install dependencies, configure environment variables, and register the orchestration with your client environment. Follow the concrete commands below to start using the system.

Install dependencies uv sync
Configure environment ```cp .env.example .env``MCP1_SERVER_PATH` must be an absolute path — MCP 2 uses it to spawn MCP 1 as a subprocess.

3) Register with Claude Desktop
Add to your MCP configuration as shown below. This registers the orchestrator so Claude Desktop can discover and use it. MCP 1 is spawned internally by the orchestrator and does not require separate registration here.

{ "mcpServers": { "acme-orchestrator": { "command": "uv", "args": ["run", "python", "src/mcp2_orchestrator/server.py"], "cwd": "/absolute/path/to/acme-mcp" } } }

## Additional configuration notes

Environment variable for MCP 1 path is required by the orchestrator to spawn MCP 1 as a subprocess. The orchestrator exposes a single ask tool to Claude Desktop and internally handles task planning, retrieval, and synthesis.

## Tools and endpoints

MCP 1 implements internal tools for semantic search and listing documents. MCP 2 exposes a single ask tool to Claude Desktop that runs the agent loop and returns a final answer.

## Agent behavior overview

The agent maintains a per-request scratchpad containing the question, a list of tasks with statuses, and the final answer when ready. It uses four internal tools to manage the workflow: add\_task, complete\_task, search\_knowledge, and finish. Tasks with satisfied dependencies are dispatched concurrently, and the loop has a hard cap of 10 iterations.

## Test questions to try

These sample questions encourage multi-hop retrieval and synthesis across the Acme knowledge base. The answers come from the MCP workflow rather than training data.

## 

## Available tools

### ask

Expose a single entry point to Claude Desktop that triggers the agent loop, handles task planning, performs retrievals from MCP 1, and returns the synthesized final answer.