McpOrchestrator — a .NET-native MCP orchestrator

NuGet Downloads License: MIT

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 with the same on-demand discipline.

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):

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:

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:

{
  "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 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

---
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:

"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.

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 and docs/:

• How it works & the three tools — architecture and token scaling
• Profiling token economics — the profile command in depth, trace mode, CI gating
• CLI reference — every command and flag: the server, init, and profile, plus all environment variables
• Manual setup — the two config files init generates, written by hand
• Configuration reference — every field, placeholders, proactive capabilities, hot reload, central (team) configuration
• Agent Skills — sources (directory/git/HTTP), governance, delivery modes, how it works
• Packaging & Native AOT — install as a .NET tool or a self-contained binary from Releases
• How it compares — vs. mcp-aggregator and gateways, and when not to use this
• Troubleshooting

License

MIT