Getting Started

Build your first MCP server with MCP Gateway in minutes.

What You’ll Learn

By following this guide, you’ll learn how to:

  • ✅ Install MCP Gateway via NuGet
  • ✅ Create your first MCP server
  • ✅ Define tools with typed parameters
  • ✅ Test with curl and GitHub Copilot
  • ✅ Handle errors and validate input
  • ✅ Deploy to production

Time required: ~15 minutes

Prerequisites

Before you begin, make sure you have:

  • .NET 10 SDK - Download here
  • Code editor - Visual Studio 2025, Visual Studio 2022 v17.13+, VS Code, or Rider
  • Basic C# knowledge - Familiarity with C# syntax
  • Command line - Basic terminal/PowerShell knowledge

Quick Start

1. Install MCP Gateway

Create a new project and install the package:

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

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

2. Create Your First Tool

Update Program.cs:

using Mcp.Gateway.Tools;

var builder = WebApplication.CreateBuilder(args);

// Register MCP Gateway
builder.AddToolsService();

var app = builder.Build();

// stdio mode for GitHub Copilot
if (args.Contains("--stdio"))
{
    await ToolInvoker.RunStdioModeAsync(app.Services);
    return;
}

// HTTP mode for testing
app.UseWebSockets();
app.UseProtocolVersionValidation();
app.MapStreamableHttpEndpoint("/mcp");

app.Run();

// Define your first tool
public class GreetingTools
{
    [McpTool("greet", Description = "Greets a user by name")]
    public TypedJsonRpc<GreetResponse> Greet(TypedJsonRpc<GreetParams> request)
    {
        var args = request.GetParams()
            ?? throw new ToolInvalidParamsException("Name is required");

        var greeting = $"Hello, {args.Name}! Welcome to MCP Gateway!";
        
        return TypedJsonRpc<GreetResponse>.Success(
            request.Id,
            new GreetResponse(greeting));
    }
}

public record GreetParams(string Name);
public record GreetResponse(string Message);

3. Run Your Server

dotnet run

Server runs at: http://localhost:5000/mcp

4. 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! Welcome to MCP Gateway!\"}"
      }
    ],
    "structuredContent": {
      "message": "Hello, World! Welcome to MCP Gateway!"
    }
  },
  "id": 1
}

What’s Next?

Step-by-Step Guides

📦

Installation

Detailed installation guide, configuration, and troubleshooting
🔧

Your First Tool

Build a complete tool step-by-step with validation and error handling

Explore Features

📊

Lifecycle Hooks

Monitor tool invocations with metrics and logging
🔐

Authorization

Implement role-based access control
📦

Resource Subscriptions

Real-time notifications for resource updates

Browse Examples

🧮

Calculator Server

Basic arithmetic operations with error handling
📈

Metrics Server

Production-ready metrics and monitoring
🔒

Authorization Server

Role-based access control with JWT

Key Concepts

Tools

Tools are the core of MCP servers. They allow AI assistants to:

  • Execute custom logic
  • Access external APIs
  • Manipulate data
  • Perform calculations

Learn more: Tools API Reference

TypedJsonRpc

Type-safe parameter handling with automatic deserialization:

public JsonRpcMessage Greet(TypedJsonRpc<GreetParams> request)
{
    var args = request.GetParams();  // Strongly typed!
    // args.Name is a string
}

Error Handling

Use ToolInvalidParamsException for invalid input:

if (string.IsNullOrWhiteSpace(args.Name))
{
    throw new ToolInvalidParamsException("Name cannot be empty");
}

GitHub Copilot Integration

Configure GitHub Copilot to use your server:

1. Create .mcp.json

In your home directory or workspace:

{
  "mcpServers": {
    "my_server": {
      "command": "dotnet",
      "args": [
        "run",
        "--project",
        "C:\\path\\to\\MyMcpServer",
        "--",
        "--stdio"
      ]
    }
  }
}

Important: Use absolute paths!

2. Use in Copilot Chat

@my_server greet Alice
@my_server help me with...

Common Questions

How do I add more tools?

Just add more methods with [McpTool] attribute:

[McpTool("add_numbers")]
public TypedJsonRpc<AddResponse> Add(TypedJsonRpc<AddParams> request)
{
    var args = request.GetParams()!;
    return TypedJsonRpc<AddResponse>.Success(
        request.Id, 
        new AddResponse(args.A + args.B));
}

public record AddParams(double A, double B);
public record AddResponse(double Result);

How do I handle async operations?

Use async methods:

[McpTool("fetch_data")]
public async Task<TypedJsonRpc<DataResponse>> FetchData(TypedJsonRpc<DataRequest> request)
{
    var data = await _httpClient.GetStringAsync("...");
    return TypedJsonRpc<DataResponse>.Success(
        request.Id, 
        new DataResponse(data));
}

How do I add logging?

Use dependency injection to inject ILogger<T>:

// Option 1: Constructor injection (class must be registered in DI)
public class MyTools
{
    private readonly ILogger<MyTools> _logger;
    
    public MyTools(ILogger<MyTools> logger)
    {
        _logger = logger;
    }
    
    [McpTool("my_tool")]
    public JsonRpcMessage MyTool(JsonRpcMessage request)
    {
        _logger.LogInformation("Tool invoked");
        // ...
    }
}

// Register in DI:
builder.Services.AddScoped<MyTools>();

// Option 2: Method parameter injection (no registration needed)
public class MyTools
{
    [McpTool("my_tool")]
    public JsonRpcMessage MyTool(
        JsonRpcMessage request, 
        ILogger<MyTools> logger)  // ← Automatically injected!
    {
        logger.LogInformation("Tool invoked");
        // ...
    }
}

Parameter resolution order:

  1. JsonRpcMessage - The request (always first parameter)
  2. Additional parameters - Resolved from DI container

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

Need Help?

Next Steps

Ready to dive deeper? Here’s what to explore next:

  1. Installation Guide - Detailed setup and configuration
  2. Build Your First Tool - Complete step-by-step tutorial
  3. Lifecycle Hooks - Monitor tool invocations
  4. Calculator Example - Basic arithmetic operations
  5. API Reference - Deep dive into the API