Crie um servidor MCP mínimo usando C# e publique no NuGet

Neste início rápido, você cria um servidor MCP (Model Context Protocol) mínimo usando o SDK C# para MCP, conecta-se a ele usando o GitHub Copilot e publica-o no NuGet. Os servidores MCP são serviços que expõem recursos aos clientes por meio do MCP (Model Context Protocol).

Pré-requisitos

• SDK do .NET 10.0 (prévia 6 ou superior)
• Código do Visual Studio
• Extensão do GitHub Copilot para Visual Studio Code
• Conta do NuGet.org

Criar o projeto

1. Numa janela de terminal, instale o modelo MCP Server:

   dotnet new install Microsoft.McpServer.ProjectTemplates
   

   Observação

   O SDK .NET 10.0 (Preview 6 ou posterior) é necessário para instalar Microsoft.McpServer.ProjectTemplates.

2. Crie um novo aplicativo de servidor MCP com o dotnet new mcpserver comando:

   dotnet new mcpserver -n SampleMcpServer
   

   Por padrão, esse comando cria um pacote de ferramentas autônomo direcionado a todas as plataformas mais comuns nas quais o .NET é suportado. Para ver mais opções, use dotnet new mcpserver --help.

3. Navegue até o SampleMcpServer diretório:

   cd SampleMcpServer
   

4. Compile o projeto:

   dotnet build
   

5. Atualize o <PackageId> no arquivo .csproj para que seja exclusivo no NuGet.org, por exemplo <NuGet.org username>.SampleMcpServer.

Configurar o servidor MCP no Visual Studio Code

Configure o GitHub Copilot para Visual Studio Code para usar seu servidor MCP personalizado:

1. Se ainda não o fez, abra a pasta do projeto no Visual Studio Code.

2. Crie uma .vscode pasta na raiz do seu projeto.

3. Adicione um mcp.json arquivo na .vscode pasta com o seguinte conteúdo:

   {
     "servers": {
       "SampleMcpServer": {
         "type": "stdio",
         "command": "dotnet",
         "args": [
           "run",
           "--project",
           "<relative-path-to-project-file>"
         ]
       }
     }
   }
   

   Observação

   O VS Code executa servidores MCP a partir da raiz do espaço de trabalho. O <relative-path-to-project-file> espaço reservado deve apontar para o ficheiro de projeto .NET. Por exemplo, o valor para este aplicativo SampleMcpServer seria SampleMcpServer.csproj.

4. Salve o arquivo.

Testar o servidor MCP

O modelo de servidor MCP inclui uma ferramenta chamada get_random_number que você pode usar para teste e como ponto de partida para desenvolvimento.

1. Abra o GitHub Copilot no Visual Studio Code e alterne para o modo de agente.

2. Selecione o ícone Selecionar ferramentas para verificar se seu SampleMcpServer está disponível com a ferramenta de exemplo listada.

   

3. Insira um prompt para executar a ferramenta get_random_number :

   Give me a random number between 1 and 100.
   

4. O GitHub Copilot solicita permissão para executar a ferramenta get_random_number para seu prompt. Selecione Continuar ou use a seta para selecionar um comportamento mais específico:

   • A sessão atual sempre executa a operação na sessão atual do Modo de Agente Copiloto do GitHub.
   • O espaço de trabalho atual sempre executa o comando para o espaço de trabalho atual do Visual Studio Code.
   • Sempre permitir define a operação para sempre ser executada para qualquer sessão do Modo de Agente Copiloto do GitHub ou qualquer espaço de trabalho do Visual Studio Code.

5. Verifique se o servidor responde com um número aleatório:

   Your random number is 42.
   

Adicionar entradas e opções de configuração

Neste exemplo, você aprimora o servidor MCP para usar um valor de configuração definido em uma variável de ambiente. Essa pode ser uma configuração necessária para o funcionamento do servidor MCP, como uma chave de API, um ponto de extremidade ao qual se conectar ou um caminho de diretório local.

1. Adicione outro método de ferramenta após o GetRandomNumber método em Tools/RandomNumberTools.cs. Atualize o código da ferramenta para usar uma variável de ambiente.

   [McpServerTool]
   [Description("Describes random weather in the provided city.")]
   public string GetCityWeather(
       [Description("Name of the city to return weather for")] string city)
   {
       // Read the environment variable during tool execution.
       // Alternatively, this could be read during startup and passed via IOptions dependency injection
       var weather = Environment.GetEnvironmentVariable("WEATHER_CHOICES");
       if (string.IsNullOrWhiteSpace(weather))
       {
           weather = "balmy,rainy,stormy";
       }
   
       var weatherChoices = weather.Split(",");
       var selectedWeatherIndex =  Random.Shared.Next(0, weatherChoices.Length);
   
       return $"The weather in {city} is {weatherChoices[selectedWeatherIndex]}.";
   }
   

2. Atualize o .vscode/mcp.json para definir a WEATHER_CHOICES variável de ambiente para teste.

   {
      "servers": {
        "SampleMcpServer": {
          "type": "stdio",
          "command": "dotnet",
          "args": [
            "run",
            "--project",
            "<relative-path-to-project-file>"
          ],
          "env": {
             "WEATHER_CHOICES": "sunny,humid,freezing"
          }
        }
      }
    }
   

3. Tente outro prompt com o Copilot no VS Code, como:

   What is the weather in Redmond, Washington?
   

   VS Code deve retornar uma descrição aleatória do tempo.

4. Atualize a .mcp/server.json para declarar a entrada da sua variável de ambiente. O server.json esquema de arquivo é definido pelo projeto de registro MCP e é usado por NuGet.org para gerar a configuração MCP do VS Code.

   • Use a environmentVariables propriedade para declarar variáveis de ambiente usadas pelo seu aplicativo que serão definidas pelo cliente usando o servidor MCP (por exemplo, VS Code).

   • Use a packageArguments propriedade para definir argumentos da CLI que serão passados para seu aplicativo. Para obter mais exemplos, consulte o projeto de Registro MCP.

   {
     "$schema": "https://static.modelcontextprotocol.io/schemas/2025-10-17/server.schema.json",
     "description": "<your description here>",
     "name": "io.github.<your GitHub username here>/<your repo name>",
     "version": "<your package version here>",
     "packages": [
       {
         "registryType": "nuget",
         "registryBaseUrl": "https://api.nuget.org",
         "identifier": "<your package ID here>",
         "version": "<your package version here>",
         "transport": {
           "type": "stdio"
         },
         "packageArguments": [],
         "environmentVariables": [
           {
             "name": "WEATHER_CHOICES",
             "value": "{weather_choices}",
             "variables": {
               "weather_choices": {
                 "description": "Comma separated list of weather descriptions to randomly select.",
                 "isRequired": true,
                 "isSecret": false
               }
             }
           }
         ]
       }
     ],
     "repository": {
       "url": "https://github.com/<your GitHub username here>/<your repo name>",
       "source": "github"
     }
   }
   

   A única informação usada por NuGet.org no server.json é o primeiro item de matriz packages com o valor registryType correspondente a nuget. As outras propriedades de nível superior, além da propriedade packages, estão atualmente sem uso e destinam-se ao próximo Registo MCP central. Pode manter os valores de espaço reservado até que o Registro MCP esteja efetivamente operacional e pronto para aceitar entradas do servidor MCP.

Você pode testar seu servidor MCP novamente antes de avançar.

Empacotar e publicar no NuGet

1. Pacote o projeto:

   dotnet pack -c Release
   

   Este comando produz um pacote de ferramentas e vários pacotes específicos de plataforma baseando-se na lista em <RuntimeIdentifiers>SampleMcpServer.csproj.

2. Publique os pacotes no NuGet:

   dotnet nuget push bin/Release/*.nupkg --api-key <your-api-key> --source https://api.nuget.org/v3/index.json
   

   Certifique-se de publicar todos os .nupkg arquivos para garantir que todas as plataformas suportadas possam executar o servidor MCP.

   Se quiser testar o fluxo de publicação antes de publicar no NuGet.org, você pode registrar uma conta no ambiente de integração da Galeria NuGet: https://int.nugettest.org. O push comando seria modificado para:

   dotnet nuget push bin/Release/*.nupkg --api-key <your-api-key> --source https://apiint.nugettest.org/v3/index.json
   

Para obter mais informações, consulte Publicar um pacote.

Descubra servidores MCP no NuGet.org

1. Procure o pacote do servidor MCP no NuGet.org (ou int.nugettest.org se você publicou no ambiente de integração) e selecione-o na lista.

   

2. Visualize os detalhes do pacote e copie o JSON da guia "Servidor MCP".

   

3. No arquivo mcp.json na .vscode pasta, adicione o JSON copiado, que tem esta aparência:

   {
     "inputs": [
       {
         "type": "promptString",
         "id": "weather_choices",
         "description": "Comma separated list of weather descriptions to randomly select.",
         "password": false
       }
     ],
     "servers": {
       "Contoso.SampleMcpServer": {
         "type": "stdio",
         "command": "dnx",
         "args": ["Contoso.SampleMcpServer@0.0.1-beta", "--yes"],
         "env": {
           "WEATHER_CHOICES": "${input:weather_choices}"
         }
       }
     }
   }
   

   Se você publicou no ambiente de integração da Galeria NuGet, precisará adicionar "--add-source", "https://apiint.nugettest.org/v3/index.json" no final da "args" matriz.

4. Salve o arquivo.

5. No GitHub Copilot, selecione o ícone Selecionar ferramentas para verificar se seu SampleMcpServer está disponível com as ferramentas listadas.

6. Insira um prompt para executar a nova ferramenta get_city_weather :

   What is the weather in Redmond?
   

7. Se você adicionou entradas ao seu servidor MCP (por exemplo, WEATHER_CHOICES), você será solicitado a fornecer valores.

8. Verifique se o servidor responde com o clima aleatório:

   The weather in Redmond is balmy.
   

Problemas comuns

O comando "dnx" necessário para executar SampleMcpServer não foi encontrado

Se o VS Code mostrar esse erro ao iniciar o servidor MCP, você precisará instalar uma versão compatível do SDK do .NET.

O dnx comando é fornecido como parte do SDK do .NET, começando com a versão 10. Instale o SDK do .NET 10 para resolver esse problema.

O GitHub Copilot não usa sua ferramenta (uma resposta é fornecida sem invocar sua ferramenta)

De um modo geral, um agente de IA como o GitHub Copilot é informado de que possui algumas ferramentas disponíveis pelo aplicativo cliente, como o VS Code. Algumas ferramentas, como a ferramenta de número aleatório de amostra, podem não ser aproveitadas pelo agente de IA porque tem funcionalidade semelhante incorporada.

Se a sua ferramenta não estiver a ser utilizada, verifique o seguinte:

1. Verifique se sua ferramenta aparece na lista de ferramentas que o VS Code habilitou. Veja a captura de tela em Testar o servidor MCP para saber como verificar isso.
2. Faça referência explícita ao nome da ferramenta em seu prompt. No VS Code, você pode fazer referência à sua ferramenta pelo nome. Por exemplo, Using #get_random_weather, what is the weather in Redmond?.
3. Verifique se o servidor MCP é capaz de iniciar. Você pode verificar isso clicando no botão "Iniciar" visível acima da configuração do servidor MCP nas configurações do usuário ou do espaço de trabalho do VS Code.

Conteúdo relacionado

• Introdução ao .NET AI e ao Model Context Protocol
• Exemplos de protocolo de contexto de modelo .NET
• Crie um cliente MCP mínimo
• Publicar um pacote
• Encontre e avalie pacotes NuGet para seu projeto
• O que há de novo no .NET 10