MicroAgents.McpFederationGateway 0.1.0-preview

🌐 MCP Federation Gateway

The ultimate federated entry point for the Model Context Protocol (MCP) ecosystem.

McpFederationGateway is a high-performance, Native AOT-compiled .NET 10 service that acts as a reverse proxy and aggregator for multiple upstream MCP servers. It provides a unified interface for agents, reduces context consumption through smart aggregation, and bridges the gap between local (Stdio) and remote (SSE/HTTP) environments.

✨ Key Features

• 🔄 Federation & Aggregation: Combines multiple downstream MCP servers into a single, unified tool catalog.
• 🛣️ Intelligent Routing: Automatically dispatches tool calls and resource requests to the correct downstream server based on namespacing or meta-tool parameters.
• 🔌 Dual-Transport Bridge:
  • Host it locally via Stdio for integration with standard MCP clients (like Claude Desktop).
  • Expose it remotely via SSE/HTTP for enterprise or cloud-based agentic workflows.
• 🧠 Federated Mode (Configurable per-server):
  • When enabled for a server, hides its specific tools from the root tools/list to reduce LLM context consumption. Access is provided via the how_to_use and call meta-tools.
• 🛠️ Direct Mode (Default, configurable per-server):
  • Exposes all tools from downstream servers as-is, with prefixes (e.g., server_toolname) to prevent collisions.
• 🚀 Native AOT Performance: Compiled to native code for ultra-fast startup and minimal footprint.
• ⚙️ Hierarchical Configuration: Merges global user defaults with workspace-specific configurations.

🛠️ Meta-Tools

In Federated Mode, the gateway exposes two primary tools to interact with the entire ecosystem:

🚀 Running with DNX

The McpFederationGateway is designed to be executed using dnx, a lightweight runner for .NET-based MCP servers.

# To run the latest preview version from NuGet
dnx MicroAgents.McpFederationGateway --transport stdio

# To run a specific version
dnx MicroAgents.McpFederationGateway@0.1.0-preview --transport stdio

# Alternative: Install as a global .NET tool
dotnet tool install -g MicroAgents.McpFederationGateway --version 0.1.0-preview
McpFederationGateway --transport stdio

For development and local execution from source:

# Clone the repository
git clone https://github.com/MicroAgentsNet/McpFederationGateway.git
cd McpFederationGateway

# Run using dotnet run
dotnet run --project src/McpFederationGateway -- --transport stdio

Configuration

The gateway looks for configuration in ~/.microagents/config.json and local workspace roots.

Example config.json:

{
  "servers": [
    {
      "name": "weather",
      "transport": "stdio",
      "mode": "direct",
      "command": "npx",
      "arguments": ["-y", "@modelcontextprotocol/server-weather"]
    },
    {
      "name": "complex-agent",
      "transport": "http",
      "mode": "federated",
      "url": "https://mcp.example.com/sse"
    }
  ]
}

📐 Architecture

Built on the official MCP C# SDK, the gateway uses a decoupled DI-based architecture:

• AggregationService: Discovers and merges downstream capabilities.
• RouterService: Handles protocol-level dispatching and tool mapping.
• McpClientFactory: Manages the lifecycle of standard and SSE transports.
• ConfigurationService: Handles the hierarchical merging of user and root settings.

🤝 Community Pledge

We are committed to the long-term health and openness of the MicroAgents ecosystem.

• MIT license stays forever.
• Monetization: We may offer paid support, donations, sponsorships, or custom development. However, commercial features follow an "N-2" policy: features from two versions ago always become part of the community version.
• Community Code: Our open-source code will never depend on or include commercial code. If it does, those features will be promoted to the community tier.
• No Warranties: This software is provided "as-is" without warranty of any kind.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.