Multi-Server MCP Aggregation Pattern

Aggregate tools across multiple MCP child servers with prefixing, collision avoidance, and routing rules that stay deterministic.

architecture

Quality

👁️0 views

docs

>Payload Data

Editable Format

# Multi-Server MCP Aggregation Pattern

Imported from curated first-party documentation sources.

## What this covers
Use this pattern when an MCP host must broker tools from multiple child servers without sacrificing clarity or control.

## Use this when
- Combining tools from several MCP backends
- Avoiding tool-name collisions across providers
- Keeping origin and routing visible during execution

## Expected outcomes
- Server-prefixed names make tool origins obvious
- Collisions are avoided without brittle manual renaming
- Operators can extend the tool surface without losing determinism

## Source synthesis
- EVOKORE-MCP/docs/AGENT33_IMPROVEMENT_INSTRUCTIONS.md (https://github.com/mattmre/EVOKORE-MCP/blob/main/docs/AGENT33_IMPROVEMENT_INSTRUCTIONS.md)
- EVOKORE-MCP/docs/TOOLS_AND_DISCOVERY.md (https://github.com/mattmre/EVOKORE-MCP/blob/main/docs/TOOLS_AND_DISCOVERY.md)

## Dedupe notes
Uses the improvement-transfer doc as the primary source, with the discovery doc covering prefixing and compatibility details.

## Source excerpts

### EVOKORE-MCP/docs/AGENT33_IMPROVEMENT_INSTRUCTIONS.md
> **Purpose**: Feed this file into Claude Code CLI when working on the Agent33 repo. It contains patterns, architectures, and capabilities proven in EVOKORE-MCP that Agent33 should adopt.

---

## 1. Multi-Server MCP Aggregation Pattern

**What Agent33 lacks**: Agent33's MCP server (Phase 43) is a single-endpoint bridge. It doesn't aggregate multiple child MCP servers behind a unified namespace.

**What to build**: A proxy layer that spawns and manages multiple child MCP servers from a single config file, presenting them as one unified tool surface.

### Implementation spec:

```
mcp.config.json
{
  "servers": {
    "github": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"], "env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" } },
    "fs": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "./"] },
    "elevenlabs": { "command": "uvx", "args": ["elevenlabs-mcp"], "env": { "ELEVENLABS_API_KEY": "${ELEVENLABS_API_KEY}" } }
  }
}
```

**Key patterns from EVOKORE**:
- **Tool name prefixing**: Every proxied tool gets renamed `{serverId}_{originalName}` to prevent namespace collisions (e.g., `github_create_issue`, `fs_read_file`). First-registration-wins for duplicates.
- **Environment interpolation**: `${VAR}` syntax in `env` blocks resolved
...

### EVOKORE-MCP/docs/TOOLS_AND_DISCOVERY.md
This page explains how EVOKORE presents tools, how proxy names are built, and how `discover_tools` changes the visible tool surface.

## Two tool populations

### Native EVOKORE tools

These tools are defined by EVOKORE itself:

- `docs_architect`
- `skill_creator`
- `resolve_workflow`
- `search_skills`
- `get_skill_help`
- `discover_tools`

Properties:

- always available
- always visible
- not subject to proxy prefixing

### Proxied child-server tools

These come from child servers in `mcp.config.json`.

Current configured sources:

- `github`
- `fs`
- optional `elevenlabs`

Properties:

- fetched from child servers at startup
- renamed with server prefixes
- governed by `permissions.yml`
- routed through `ProxyManager`

## Prefixing and compatibility

EVOKORE rewrites proxied tool names to:

```text
${serverId}_${tool.name}
```

Why this exists:

- prevents tool-name collisions across child servers
- makes origin obvious during execution and review
- keeps exact-name routing deterministic

Examples:

| Upstream tool | EVOKORE-exposed tool |
|---|---|
| `read_file` from `fs` | `fs_read_file` |
| `create_issue` from `github` | `github_create_issue` |

### Duplicate-prefixed name policy

If two child registrations would create the same final prefixed name:

- the first registrati
...

Source

https://github.com/mattmre/EVOKORE-MCP/blob/main/docs/AGENT33_IMPROVEMENT_INSTRUCTIONS.md

SIMILAR_PROMPTS

SCANNING_SIMILARITY...