svrnty-mcp-gateway/AGENT-PRIMER.md

AGENT-PRIMER: OpenHarbor.MCP.Gateway Automated Setup

Purpose: Guide AI agents to automatically analyze a target system and configure OpenHarbor.MCP.Gateway integration.

Target Audience: AI assistants (Claude, ChatGPT, etc.) helping developers set up MCP gateway/proxy infrastructure.

---

Overview

OpenHarbor.MCP.Gateway is a standalone .NET library that provides proxy and routing infrastructure for MCP traffic, enabling centralized management between MCP clients and servers.

What you'll automate:

1. System analysis (detect .NET version, network requirements)
2. Configuration generation (appsettings.json, routing rules, Program.cs)
3. Sample routing strategies based on deployment scenario
4. Environment setup and validation

---

Step 1: System Analysis

Tasks for AI Agent:

1.1 Detect .NET Environment

dotnet --version  # Required: .NET 8.0+
dotnet --list-sdks

1.2 Analyze Deployment Scenario

Ask user to identify scenario:

• Scenario A: Single gateway routing to multiple backend servers
• Scenario B: Load balancing across server instances
• Scenario C: A/B testing different server versions
• Scenario D: Multi-tenant routing based on client identity

1.3 Identify Backend Servers

# Detect existing MCP servers
find . -name "*McpServer*" -type d

Output: JSON summary

{
  "dotnetVersion": "8.0.100",
  "scenario": "LoadBalancing",
  "backendServers": [
    {
      "name": "codex-server-1",
      "transport": "Stdio",
      "path": "/path/to/server1"
    },
    {
      "name": "codex-server-2",
      "transport": "Http",
      "url": "https://api.example.com/mcp"
    }
  ]
}

---

Step 2: Generate Configuration

2.1 appsettings.json Configuration

{
  "Mcp": {
    "Gateway": {
      "Name": "MyMcpGateway",
      "Version": "1.0.0",
      "ListenAddress": "http://localhost:8080"
    },
    "Servers": [
      {
        "Id": "server-1",
        "Name": "Primary Server",
        "Transport": {
          "Type": "Http",
          "Command": "dotnet",
          "Args": ["run", "--project", "/path/to/server"]
        },
        "Enabled": true
      }
    ],
    "Routing": {
      "Strategy": "RoundRobin",
      "HealthCheckInterval": "00:00:30"
    },
    "Security": {
      "EnableAuthentication": false,
      "RateLimit": {
        "RequestsPerMinute": 100
      }
    }
  }
}

2.2 Program.cs Integration

using OpenHarbor.MCP.Gateway.AspNetCore;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddMcpGateway(builder.Configuration.GetSection("Mcp"));

var app = builder.Build();

app.MapMcpGateway();
app.MapHealthChecks("/health");

app.Run();

---

Step 3: Generate Routing Strategy

3.1 Round-Robin Load Balancing

public class RoundRobinRouter : IRoutingStrategy
{
    private int _index = 0;

    public string SelectServer(
        RoutingContext context,
        IEnumerable<ServerInfo> servers)
    {
        var list = servers.Where(s => s.IsHealthy).ToList();
        var index = Interlocked.Increment(ref _index) % list.Count;
        return list[index].Id;
    }
}

3.2 Tool-Based Routing

public class ToolBasedRouter : IRoutingStrategy
{
    public string SelectServer(
        RoutingContext context,
        IEnumerable<ServerInfo> servers)
    {
        return context.ToolName switch
        {
            var t when t.StartsWith("search_") => "search-server",
            var t when t.StartsWith("db_") => "database-server",
            _ => servers.First().Id
        };
    }
}

---

Step 4: Validation

# Build gateway
dotnet build

# Run tests
dotnet test

# Start gateway
dotnet run

# Check health
curl http://localhost:8080/health

---

Step 5: AI Agent Workflow

1. Analyze → Detect scenario and backend servers
2. Confirm → Show configuration, ask approval
3. Generate → Create files from Steps 2-3
4. Validate → Run Step 4 tests
5. Report → "Gateway configured. Ready to route MCP traffic."

---

Document Version: 1.0.0 Last Updated: 2025-10-19 Target: OpenHarbor.MCP.Gateway