Criar um servidor MCP mínimo usando C# e publicar no NuGet

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

Observação

O Microsoft.McpServer.ProjectTemplates pacote de modelo está atualmente em versão prévia.

Pré-requisitos

• SDK do .NET 10.0
• Visual Studio 2022 ou superior
• Copiloto do GitHub
• conta do NuGet.org

• SDK do .NET 10.0
• Visual Studio Code (opcional)
• Extensão do Kit de Desenvolvimento do C#
• Extensão do GitHub Copilot para Visual Studio Code
• conta do NuGet.org

• SDK do .NET 10.0
• Visual Studio Code (opcional)
• Visual Studio (opcional)
• GitHub Copilot / Extensão do GitHub Copilot para Visual Studio Code
• conta do NuGet.org

Criar o projeto

1. Em uma janela de terminal, instale o modelo do SERVIDOR MCP:

   dotnet new install Microsoft.McpServer.ProjectTemplates
   

   Observação

   O SDK do .NET 10.0 ou uma versão posterior é necessário para instalar Microsoft.McpServer.ProjectTemplates.

2. Abra o Visual Studio e selecione Criar um novo projeto na janela inicial (ou selecione Arquivo>Novo>Projeto/Solução de dentro do Visual Studio).

   

3. Na janela Criar um novo projeto , selecione C# na lista de idiomas e IA na lista Todos os tipos de projeto . Depois de aplicar os filtros de tipo de linguagem e projeto, selecione o modelo de Aplicativo do Servidor MCP e selecione Avançar.

   

4. Na janela Configurar seu novo projeto , insira MyMcpServer no campo Nome do Projeto . Em seguida, selecione Avançar.

   

5. Na janela Informações adicionais , você pode configurar as seguintes opções:

   • Estrutura: selecione a estrutura do .NET de destino.
   • Tipo de transporte do servidor MCP: escolha entre criar um servidor MCP local (stdio) ou um servidor MCP remoto (http).
   • Habilite a publicação nativa do AOT (Ahead-Of-Time): habilite seu servidor MCP para ser autônomo e compilado em código nativo. Para obter mais informações, consulte o guia de implantação do AOT nativo.
   • Habilite a publicação autocontida: habilite o servidor MCP a ser publicado como um executável autocontido. Para obter mais informações, consulte a seção de implantação independente do guia de publicação de aplicativos .NET.

   Escolha suas opções preferenciais ou mantenha as padrão e, em seguida, selecione Criar.

   

   O Visual Studio abre seu novo projeto.

6. Atualize o arquivo <PackageId> no .csproj para ser exclusivo no NuGet.org, por exemplo <NuGet.org username>.SampleMcpServer.

1. Em uma janela de terminal, instale o modelo do SERVIDOR MCP:

   dotnet new install Microsoft.McpServer.ProjectTemplates
   

   Observação

   O SDK do .NET 10.0 ou posterior é necessário para instalar Microsoft.McpServer.ProjectTemplates.

2. Abra o Visual Studio Code.

3. Vá para a visualização do Explorer e selecione Criar Projeto .NET. Como alternativa, você pode abrir a Paleta de Comandos usando Ctrl+Shift+P (Command+Shift+P no MacOS) e, em seguida, digitar ".NET" para localizar e selecionar o comando .NET: Novo Projeto .

   Essa ação abrirá uma lista suspensa de projetos do .NET.

   

4. Depois de selecionar o comando, use a barra Pesquisar na Paleta de Comandos ou role para baixo para localizar o modelo de Aplicativo do Servidor MCP .

   

5. Selecione o local onde você deseja que o novo projeto seja criado.

6. Dê um nome ao seu novo projeto, MyMCPServer. Pressione Enter.

7. Selecione o formato de arquivo da solução (.sln ou .slnx).

8. Selecione Opções de Modelo. Aqui, você pode configurar as seguintes opções:

   • Estrutura: selecione a estrutura do .NET de destino.
   • Tipo de transporte do servidor MCP: escolha entre criar um servidor MCP local (stdio) ou um servidor MCP remoto (http).
   • Ative a publicação do AOT (Ahead-Of-Time) nativo: ative o servidor MCP para que seja autocontido e compilado para código nativo. Para obter mais informações, consulte o guia de implantação do AOT nativo.
   • Habilite a publicação autocontida: Habilite seu servidor MCP para ser publicado como um executável autocontido. Para obter mais informações, consulte a seção de implantação independente do guia de publicação de aplicativos .NET.

   

   Escolha suas opções preferenciais ou mantenha as padrão e, em seguida, selecione Criar Projeto.

   O VS Code abre seu novo projeto.

9. Atualize o arquivo <PackageId> no .csproj para ser exclusivo no NuGet.org, por exemplo <NuGet.org username>.SampleMcpServer.

1. 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 autossuficiente direcionado a todas as plataformas mais comuns nas quais o .NET tem suporte. Para ver mais opções, use dotnet new mcpserver --help.

   O uso do dotnet new mcpserver --help comando oferece várias opções de modelo que você pode adicionar ao criar um novo servidor MCP:

   • Estrutura: selecione a estrutura do .NET de destino.
   • Tipo de transporte do servidor MCP: escolha entre criar um servidor MCP local (stdio) ou um servidor MCP remoto (http).
   • Habilitar publicação AOT nativa (Ahead-Of-Time): torne o servidor MCP autocontido e compilado para código nativo. Para obter mais informações, consulte o guia de implantação do AOT nativo.
   • Habilite a publicação autocontida: Habilite o servidor MCP a ser publicado como um executável autocontido. Para obter mais informações, consulte a seção de implantação independente do guia de publicação de aplicativos .NET.

   

2. Navegue até o SampleMcpServer diretório:

   cd SampleMcpServer
   

3. Compile o projeto:

   dotnet build
   

4. Atualize o arquivo <PackageId> no .csproj para ser exclusivo no NuGet.org, por exemplo <NuGet.org username>.SampleMcpServer.

Visitar o projeto do servidor MCP

A criação do projeto do servidor MCP por meio do modelo fornece os seguintes arquivos principais:

• Program.cs: um arquivo que define o aplicativo como um servidor MCP e registra serviços MCP, como tipo de transporte e ferramentas MCP.
  • Escolhendo a opção de transporte stdio (padrão) ao criar o projeto, esse arquivo será configurado para definir o servidor MCP como local (ou seja, .withStdioServerTransport()).
  • Escolher a opção de transporte http configurará esse arquivo para incluir definições específicas do transporte remoto (ou seja, .withHttpServerTransport(), ). MapMcp()
• RandomNumberTools.cs: uma classe que define uma ferramenta de servidor MCP de exemplo que retorna um número aleatório entre valores mínimos/máximos especificados pelo usuário.
• [Somente transporte HTTP][MCPServerName].http: um arquivo que define o endereço de host padrão para um servidor HTTP MCP e JSON-RPC comunicação.
• server.json: Um arquivo que define como e onde o servidor MCP é publicado.

Configurar o servidor MCP

Configure o GitHub Copilot para Visual Studio para usar o servidor MCP personalizado.

1. No Visual Studio, selecione o ícone do GitHub Copilot no canto superior direito e selecione Abrir Janela de Chat.

2. Na janela do GitHub Copilot Chat, clique no ícone Selecionar Ferramentas , seguido do ícone de adição no canto superior direito.

   

3. Na janela Adicionar Servidor MCP Personalizado , insira as seguintes informações:

   • Destino: escolha o escopo de onde o servidor MCP está configurado:
     • Solução – O servidor MCP está disponível somente na solução ativa.
     • Global – O servidor MCP está disponível em todas as soluções.
   • ID do servidor: o nome/identificador exclusivo para o servidor MCP.
   • Tipo: o tipo de transporte do servidor MCP (stdio ou HTTP).
   • Comando (somente transporte via stdio): o comando para executar o servidor MCP via STDIO (ou seja, dotnet run --project [relative path to .csproj file])
   • URL (somente transporte HTTP): o endereço do servidor HTTP MCP
   • Variáveis de ambiente (opcional)

   

4. Clique em Salvar. Um .mcp.json arquivo será adicionado ao destino especificado.

Stdio Transport .mcp.json

Adicione o caminho relativo ao arquivo .csproj no campo "args".

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

Transporte HTTP .mcp.json

{
 "inputs": [],
  "servers": {
    "MyMCPServer": {
      "url": "http://localhost:6278",
      "type": "http",
      "headers": {}
    }
  }
}

Configure o GitHub Copilot para Visual Studio Code para usar o servidor MCP personalizado, por meio da Paleta de Comandos do VS Code ou manualmente.

Configuração da Paleta de Comandos

1. Abra a paleta de comandos usando Ctrl+Shift+P (Command+Shift+P no macOS). Pesquise "mcp" para localizar o MCP: Add Server comando.

2. Selecione o tipo de servidor MCP a ser adicionado (normalmente o tipo de transporte selecionado na criação do projeto).

   

3. Se estiver adicionando um servidor STDIO MCP, insira um comando e argumentos opcionais. Para este exemplo, use dotnet run --project.

   Se estiver adicionando um servidor HTTP MCP, insira o localhost ou o endereço da Web.

4. Insira uma ID de servidor exclusiva (exemplo: "MyMCPServer").

5. Selecione um destino de configuração:

   • Global: disponibilize o servidor MCP em todos os workspaces. O arquivo mcp.json gerado aparecerá na configuração global do usuário.

   • Workspace: disponibilize o servidor MCP somente de dentro do workspace atual. O arquivo gerado mcp.json será exibido na pasta .vscode dentro do seu workspace.

   

6. Depois de concluir as etapas anteriores, um .mcp.json arquivo será criado no local especificado pelo destino de configuração.

Stdio Transport mcp.json

Adicione o caminho relativo ao arquivo .csproj no campo "args".

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

Transporte HTTP mcp.json

{
  "servers": {
    "MyMCPServer": {
      "url": "http://localhost:6278",
      "type": "http"
    }
  },
  "inputs": []
}

Configuração manual

1. Crie uma .vscode pasta na raiz do projeto.

2. 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 da pasta raiz do workspace. O <relative-path-to-project-file> espaço reservado deve indicar o arquivo de projeto do .NET. Por exemplo, o valor deste aplicativo SampleMcpServer seria SampleMcpServer.csproj.

3. Salve o arquivo.

Testar o servidor MCP

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

1. Abra o chat do GitHub Copilot no Visual Studio e alterne para o modo Agente .

2. Selecione o ícone Selecionar ferramentas para verificar se o MyMCPServer 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 GitHub Copilot Agent Mode.
   • A solução atual sempre executa o comando para a solução VS atual.
   • Sempre permitir define a operação para executar em qualquer sessão do Modo de Agente do GitHub Copilot.

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

   Your random number is 42.
   

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

1. Abra o chat do GitHub Copilot no VS Code e alterne para o modo Agente .

2. Selecione o ícone Selecionar ferramentas para verificar se o MyMCPServer 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 GitHub Copilot Agent Mode.
   • O workspace atual sempre executa o comando para o workspace atual do VS Code.
   • Sempre permitir que a operação sempre seja executada para qualquer sessão do Modo de Agente do GitHub Copilot.

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 conjunto de valores de configuração em uma variável de ambiente. Isso pode ser uma configuração necessária para o funcionamento do servidor MCP, como uma chave de API, um ponto de extremidade para se conectar ou um caminho de diretório local.

1. Adicione outro método de ferramenta após o método GetRandomNumber 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 variável de ambiente WEATHER_CHOICES para teste.

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

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

   What is the weather in Redmond, Washington?
   

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

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

   • Use a environmentVariables propriedade para declarar variáveis de ambiente usadas pelo 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 do 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"
     }
   }
   

   As únicas informações usadas por NuGet.org no server.json são o primeiro item da matriz packages cujo registryType valor corresponde ao nuget. As outras propriedades de nível superior, além da propriedade packages, não estão sendo utilizadas no momento e destinam-se ao próximo registro central do MCP. Você pode deixar os valores de espaço reservado até que o Registro MCP esteja pronto e ativo para aceitar entradas de servidor MCP.

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

Empacotar e publicar no NuGet

1. Empacote o projeto:

   dotnet pack -c Release
   

   Esse comando produz um pacote de ferramentas e vários pacotes específicos da plataforma com base na <RuntimeIdentifiers> lista em 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
   

   Publique todos os .nupkg arquivos para garantir que todas as plataformas compatíveis possam executar o servidor MCP.

   Se você quiser testar o fluxo de publicação antes de publicar no NuGet.org, poderá registrar uma conta no ambiente de integração da Galeria do 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.

Descobrir servidores MCP no NuGet.org

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

   

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

   

3. No arquivo mcp.json na pasta .vscode, adicione o JSON copiado, que tem a seguinte 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 do NuGet, precisará adicionar "--add-source", "https://apiint.nugettest.org/v3/index.json" no final da matriz "args".

4. Salve o arquivo.

5. No GitHub Copilot, selecione o ícone Selecionar ferramentas para verificar se o 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 servidor MCP (por exemplo, WEATHER_CHOICES), será solicitado que você forneça 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 é enviado 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 modo geral, um agente de IA como o GitHub Copilot é informado de que tem algumas ferramentas disponíveis pelo aplicativo cliente, como o VS Code. Algumas ferramentas, como a ferramenta de número aleatório de exemplo, podem não ser utilizadas pelo agente de IA porque ele tem funcionalidade semelhante integrada.

Se a ferramenta não estiver sendo usada, verifique o seguinte:

1. Verifique se a ferramenta aparece na lista de ferramentas que o VS Code habilitou. Confira a captura de tela em Testar o servidor MCP para saber como verificar isso.
2. Referencie explicitamente o nome da ferramenta em seu prompt. No VS Code, você pode referenciar sua ferramenta pelo nome. Por exemplo, Using #get_random_weather, what is the weather in Redmond?.
3. Verifique se o servidor MCP está habilitado para 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 workspace do VS Code.

Conteúdo relacionado

• Introdução à IA do .NET e ao Protocolo de Contexto do Modelo
• Exemplos de Protocolo de Contexto de Modelo do .NET
• Criar um cliente MCP mínimo
• Publicar um pacote
• Localizar e avaliar pacotes NuGet para seu projeto
• Novidades no .NET 10