Installation

Get started with MCP Gateway in minutes.

Prerequisites

• .NET 10 SDK - Download here
• Code editor - Visual Studio 2025, Visual Studio 2022 v17.13+, VS Code, or Rider
• Basic C# knowledge

Install via NuGet

Using .NET CLI

dotnet add package Mcp.Gateway.Tools

Using Package Manager Console

Install-Package Mcp.Gateway.Tools

Using Visual Studio

1. Right-click project → Manage NuGet Packages
2. Search for Mcp.Gateway.Tools
3. Click Install

Create New Project

Quick Start (Recommended)

# Create new web project
dotnet new web -n MyMcpServer
cd MyMcpServer

# Install MCP Gateway
dotnet add package Mcp.Gateway.Tools

# Run
dotnet run

From Template

# Install MCP Gateway template (coming soon!)
dotnet new install Mcp.Gateway.Templates

# Create from template
dotnet new mcp-server -n MyMcpServer

Verify Installation

Create a simple server to verify everything works:

// Program.cs
using Mcp.Gateway.Tools;

var builder = WebApplication.CreateBuilder(args);

// Register MCP Gateway
builder.AddToolsService();

var app = builder.Build();

// Configure endpoints
app.UseWebSockets();
app.MapStreamableHttpEndpoint("/mcp");

app.Run();

// Define your first tool
public class GreetingTools
{
    [McpTool("greet")]
    public JsonRpcMessage Greet(TypedJsonRpc<GreetParams> request)
    {
        var name = request.GetParams().Name;
        return ToolResponse.Success(
            request.Id,
            new { message = $"Hello, {name}!" });
    }
}

public record GreetParams(string Name);

Run the server:

dotnet run

Test with curl:

curl -X POST http://localhost:5000/mcp \
  -H "Content-Type: application/json" \
  -H "MCP-Protocol-Version: 2025-11-25" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "greet",
      "arguments": { "Name": "World" }
    },
    "id": 1
  }'

Expected response:

{
  "jsonrpc": "2.0",
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"message\":\"Hello, World!\"}"
      }
    ]
  },
  "id": 1
}

Configuration

appsettings.json

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Mcp.Gateway": "Debug"
    }
  },
  "Urls": "http://localhost:5000",
  "AllowedHosts": "*"
}

launchSettings.json

{
  "profiles": {
    "http": {
      "commandName": "Project",
      "dotnetRunMessages": true,
      "launchBrowser": false,
      "applicationUrl": "http://localhost:5000",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    },
    "stdio": {
      "commandName": "Project",
      "dotnetRunMessages": false,
      "launchBrowser": false,
      "commandLineArgs": "--stdio",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Production"
      }
    }
  }
}

Troubleshooting

Port Already in Use

Change the port in appsettings.json:

{
  "Urls": "http://localhost:5001"
}

Tools Not Discovered

Ensure your tool class is:

• Public class
• Public methods with [McpTool] attribute
• In the same assembly as Program.cs

Package Not Found

Clear NuGet cache:

dotnet nuget locals all --clear
dotnet restore

Protocol Version Compatibility

MCP Gateway reports protocol version 2025-11-25 by default, but some clients don’t support this yet.

Why This Matters

GitHub Copilot (as of Dec 2025) expects 2025-06-18 and will fail to connect if server reports 2025-11-25.

Solution: Environment Variable

Set MCP_PROTOCOL_VERSION to advertise an older version:

PowerShell:

$env:MCP_PROTOCOL_VERSION = "2025-06-18"
dotnet run

Bash:

export MCP_PROTOCOL_VERSION="2025-06-18"
dotnet run

launchSettings.json:

{
  "profiles": {
    "stdio": {
      "commandName": "Project",
      "commandLineArgs": "--stdio",
      "environmentVariables": {
        "MCP_PROTOCOL_VERSION": "2025-06-18"
      }
    }
  }
}

Important: This only changes what version is reported in the initialize response. The server still accepts all versions: 2025-11-25, 2025-06-18, 2025-03-26.

Supported Versions

Tip: Use 2025-06-18 for maximum compatibility with current MCP clients.

Next Steps

Now that you have MCP Gateway installed:

1. Create your first tool - Learn tool development
2. Lifecycle Hooks - Monitor tool invocations
3. Calculator Example - Complete working server

See Also

• Getting Started Overview - Overview and quick start
• Your First Tool - Build a complete tool step-by-step
• Examples - Calculator, DateTime, Metrics

IDE Extensions

Visual Studio 2022

• REST Client - Test endpoints directly in VS

VS Code

• C# Dev Kit - Official C# extension
• REST Client - Test HTTP endpoints
• Thunder Client - Alternative API testing

Rider

Built-in MCP support (coming soon!)

System Requirements