Nexttag.Ai.Mcp 1.0.0

Nexttag.Ai.Mcp

Conecta a servidores MCP (stdio ou HTTP) e expõe as tools deles como AITool prontos para o Nexttag.Ai.Agents.

Instalar

dotnet add package Nexttag.Ai.Mcp

Requer .NET 10. Depende de: ModelContextProtocol 1.4.0.

Registrar (Program.cs)

McpToolset é criado de forma assíncrona — use como singleton de sessão ou await using por execução:

// Program.cs — singleton de longa vida (conexões mantidas)
builder.Services.AddSingleton(sp =>
    McpToolset.ConnectAsync(
        sp.GetRequiredService<IEnumerable<McpServerConfig>>(),
        onError: (cfg, ex) => sp.GetRequiredService<ILogger<Program>>()
            .LogWarning(ex, "MCP {Servidor} indisponivel", cfg.Name))
    .GetAwaiter().GetResult());

Configurar

{
  "Mcp": {
    "Servers": [
      {
        "Name": "github",
        "Transport": "Http",
        "Url": "https://mcp.exemplo.com/github",
        "Headers": { "Authorization": "Bearer ghp_..." }
      },
      {
        "Name": "filesystem",
        "Transport": "Stdio",
        "Command": "npx",
        "Args": ["-y", "@modelcontextprotocol/server-filesystem", "/dados"]
      }
    ]
  }
}

Sem configuração obrigatória de variáveis de ambiente — as credenciais entram por Headers (HTTP) ou Env (stdio).

Usar

using Nexttag.Ai.Mcp;
using Nexttag.Ai.Agents;

// Conecta nos servidores e agrega as tools
await using var mcp = await McpToolset.ConnectAsync(
[
    new McpServerConfig
    {
        Name      = "github",
        Transport = McpTransport.Http,
        Url       = "https://mcp.exemplo.com/github",
        Headers   = new Dictionary<string, string> { ["Authorization"] = "Bearer ghp_..." }
    },
    new McpServerConfig
    {
        Name      = "filesystem",
        Transport = McpTransport.Stdio,
        Command   = "npx",
        Args      = ["-y", "@modelcontextprotocol/server-filesystem", "/dados"],
        Env       = new Dictionary<string, string> { ["HOME"] = "/tmp" }
    },
],
onError: (cfg, ex) => logger.LogWarning(ex, "MCP {Servidor} falhou", cfg.Name));

// Soma as tools MCP com as tools do host e executa o agente
IReadOnlyList<AITool> tools = [.. minhasTools, .. mcp.Tools];

var runner  = new AgentRunner(chatClient);
var context = new AgentRunContext();
AgentRunResult r = await runner.RunAsync(systemPrompt, task, tools, context);

Receitas

Combinar MCP com AgentToolset:

await using var mcp = await McpToolset.ConnectAsync(configs);

var tools = new AgentToolset(http, context)
    .ComWebFetch()
    .ComCalculadora()
    .Mais(mcp.Tools)
    .Build();

await using por requisição (sessão curta):

// Em vez de singleton — útil quando as tools mudam por tenant/usuário
await using var mcp = await McpToolset.ConnectAsync(ConfigsDoTenant(tenantId),
    onError: (cfg, ex) => logger.LogWarning(ex, "MCP {s} indisponivel", cfg.Name));

await runner.RunStreamingAsync(systemPrompt, task, mcp.Tools, context);

Servidor stdio com variáveis de ambiente:

new McpServerConfig
{
    Name      = "meu-servidor",
    Transport = McpTransport.Stdio,
    Command   = "dotnet",
    Args      = ["run", "--project", "/srv/meu-mcp"],
    Env       = new Dictionary<string, string>
    {
        ["DATABASE_URL"] = connectionString,
        ["API_KEY"]      = apiKey,
    }
}

Notas

• Use await using — McpToolset implementa IAsyncDisposable e fecha todas as conexões ao sair do escopo.
• Servidor que falha na conexão é ignorado (chama onError); os outros continuam funcionando.
• Transporte Http usa streamable HTTP (SSE); Stdio lança o processo filho e fala via stdin/stdout.
• Para McpTransport.Stdio: Command é obrigatório. Para McpTransport.Http: Url é obrigatório.
• O número de tools disponíveis depende do que cada servidor MCP declara — use mcp.Tools.Count para inspecionar.