McpOrchestrator
Route one agent through one MCP server to many, with progressive tool discovery to shrink context.
Open source Open in the app JSON README (API)
About
Route one agent through one MCP server to many, with progressive tool discovery to shrink context.
Details
- Kind
- MCP servers
- Topic
- AI, RAG & memory
- Publisher
- byggarepop
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.5.2
- Stars
- 2
- Open pull requests
- 1
- Last push
- 2026-08-08T11:37:20Z
- Repository state
- ativo
- Language
- C#
- License
- MIT
- Added
- 2026-08-29 03:01:44
- Updated
- 2026-08-29 03:01:44
- Origin id
io.github.Byggarepop/dotnet-mcp-orchestrator
README
<!-- mcp-name: io.github.Byggarepop/dotnet-mcp-orchestrator -->
# McpOrchestrator — a .NET-native MCP orchestrator
[](https://www.nuget.org/packages/McpOrchestrator)
[](https://www.nuget.org/packages/McpOrchestrator)
[](https://github.com/Byggarepop/dotnet-mcp-orchestrator/blob/main/LICENSE)
**Every MCP server you connect costs context before the agent does anything — its tool manifests sit in the prompt on every turn.** McpOrchestrator puts one server between your agent and all the others and loads downstream tool manifests **on demand**, so the agent's always-on context stays flat no matter how many servers you add. The agent sees three meta-tools — `list_capabilities` → `discover_tools` → `route` — and the orchestrator is a **pure relay**: it forwards exactly what the agent sends, never interpreting it. It can also serve **[Agent Skills](https://agentskills.io)** with the same on-demand discipline.
## See it in 70 seconds
https://github.com/user-attachments/assets/741c1afa-4bef-4870-9b84-e2c245b8117e
## Measured impact
Against a real workplace MCP setup, measured with the Copilot CLI's `/usage`:
| | Tokens in context |
| --- | --- |
| MCP connected directly (manifests loaded upfront) | **17,900** |
| Same MCP behind McpOrchestrator | **1,400** |
| **Reduction** | **~13x** |
The savings scale with the number of servers. Measure your own setup first — one command, nothing installed, not a single file changed (needs the .NET SDK):
```bash
cd ~/my-project # a folder with a .mcp.json / .vscode/mcp.json / Cursor config
dotnet tool execute McpOrchestrator profile
```
## Quick start
From an existing MCP setup, `cd` to the folder holding your host config (`.mcp.json`, `.vscode/mcp.json`, or a Cursor config) and run:
```bash
dotnet tool execute McpOrchestrator --yes init # dnx McpOrchestrator --yes init works too
```
It lifts your stdio servers into a generated `orchestrator.config.json`, backs up the host config, and rewrites it to launch only the orchestrator. The generated catalog looks like this — one entry per downstream server:
```jsonc
{
"capabilities": [
{
"name": "files",
"summary": "Read and search files under the project root.", // auto-generated
"transport": "stdio",
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "C:/projects"]
}
// …one entry per server init found
]
}
```
The `summary` line is what the agent routes on — refine any that read poorly. Restart your MCP host and you're done: the agent discovers everything on its own through `list_capabilities` → `discover_tools` → `route`, and every later edit to this file [hot-reloads](https://github.com/Byggarepop/dotnet-mcp-orchestrator/blob/main/McpOrchestrator/README.md#hot-reload) without a restart.
## Add a skill
A skill is a folder with a `SKILL.md` — instructions the agent discovers and follows by itself when a task matches. Create one:
```
my-skills/
└── release-notes/
└── SKILL.md
```
```markdown
---
name: release-notes
description: Writes user-facing release notes from a git commit range. Use when asked for release notes or a changelog entry.
---
1. Collect the commits since the last release tag.
2. Group by user impact; drop internal-only changes.
3. One sentence per change, present tense.
```
Point the orchestrator at the folder in `orchestrator.config.json`:
```jsonc
"skills": {
"sources": [{ "id": "local", "type": "directory", "path": "C:/my-skills" }]
}
```
Save — it hot-reloads. The agent now sees the skill's name + one-line description via `list_skills` and loads the full instructions only when a task calls for it. Skills can also come from a shared git repo or an HTTP index, with allow/deny lists and integrity pinning — see [docs/skills.md](https://github.com/Byggarepop/dotnet-mcp-orchestrator/blob/main/docs/skills.md).
> Note: these skills are **for the agent only** — the model discovers and follows them through tools. They do not become host-native skills (no `/skills` listing or slash command in Claude Code, no IDE skill picker entry).
## Documentation
Everything else lives in **[McpOrchestrator/README.md](https://github.com/Byggarepop/dotnet-mcp-orchestrator/blob/main/McpOrchestrator/README.md)** and **[docs/](https://github.com/Byggarepop/dotnet-mcp-orchestrator/tree/main/docs)**:
- [How it works & the three tools](https://github.com/Byggarepop/dotnet-mcp-orchestrator/blob/main/McpOrchestrator/README.md#how-it-works) — architecture and token scaling
- [Profiling token economics](https://github.com/Byggarepop/dotnet-mcp-orchestrator/blob/main/McpOrchestrator/README.md#profiling-token-economics-profile) — the `profile` command in depth, trace mode, CI gating
- [CLI reference](https://github.com/Byggarepop/dotnet-mcp-orchestrator/blob/main/docs/cli.md) — every command and flag: the server, `init`, and `profile`, plus all environment variables
- [Manual setup](https://github.com/Byggarepop/dotnet-mcp-orchestrator/blob/main/docs/manual-setup.md) — the two config files `init` generates, written by hand
- [Configuration reference](https://github.com/Byggarepop/dotnet-mcp-orchestrator/blob/main/McpOrchestrator/README.md#configuration-reference) — every field, placeholders, [proactive capabilities](https://github.com/Byggarepop/dotnet-mcp-orchestrator/blob/main/McpOrchestrator/README.md#proactive-capabilities-promote), [hot reload](https://github.com/Byggarepop/dotnet-mcp-orchestrator/blob/main/McpOrchestrator/README.md#hot-reload), [central (team) configuration](https://github.com/Byggarepop/dotnet-mcp-orchestrator/blob/main/McpOrchestrator/README.md#central-configuration)
- [Agent Skills](https://github.com/Byggarepop/dotnet-mcp-orchestrator/blob/main/docs/skills.md) — sources (directory/git/HTTP), governance, delivery modes, how it works
- [Packaging & Native AOT](https://github.com/Byggarepop/dotnet-mcp-orchestrator/blob/main/McpOrchestrator/README.md#packaging-install-as-a-net-tool) — install as a .NET tool or a self-contained binary from [Releases](https://github.com/Byggarepop/dotnet-mcp-orchestrator/releases)
- [How it compares](https://github.com/Byggarepop/dotnet-mcp-orchestrator/blob/main/McpOrchestrator/README.md#how-it-compares) — vs. mcp-aggregator and gateways, and when *not* to use this
- [Troubleshooting](https://github.com/Byggarepop/dotnet-mcp-orchestrator/blob/main/McpOrchestrator/README.md#troubleshooting--pitfalls)
## License
[MIT](https://github.com/Byggarepop/dotnet-mcp-orchestrator/blob/main/LICENSE)