remote-mcp by scampcat - MCP Server

Remote MCP Server with Azure AD OAuth

A production-ready remote Model Context Protocol (MCP) server built with C# and ASP.NET Core, featuring OAuth 2.1 authentication with mandatory PKCE via Microsoft Azure AD and comprehensive MCP tools.

✨ Key Features

🔐 OAuth 2.1 Authentication: Full authorization server with Microsoft Azure AD integration and mandatory PKCE
🔑 Dynamic Client Registration: RFC 7591 compliant for MCP clients
🖐️ WebAuthn Biometric Support: Face ID, Touch ID, and security key authentication
🌐 Stateless Operation: Works with stateless MCP clients using memory cache
16 Tools across 4 categories (Math, Utility, Data, Reflection)
🔍 Self-Documenting with 5 powerful reflection tools
🌐 Network Ready - accepts connections from any IP with proper security
⚡ Production Grade - built with ASP.NET Core and enterprise patterns
🔌 Universal MCP Client Support - works with Claude Code, Cursor, VS Code
🛠️ Professional UI - Bootstrap-styled authentication and registration pages

📋 Tool Categories

Math Tools (4)

Add - Adds two numbers together
Subtract - Subtracts the second number from the first
Multiply - Multiplies two numbers together
Divide - Divides the first number by the second (with zero-division protection)

Utility Tools (3)

Echo - Echoes input messages back to the client
GetCurrentTime - Returns current server time in UTC
GenerateRandomNumber - Generates random numbers with configurable range

Data Tools (4)

FormatJson - Converts JSON strings to formatted, indented JSON
ToUpperCase - Converts text to uppercase
ToLowerCase - Converts text to lowercase
ReverseText - Reverses input text

Reflection Tools (5) ⭐

ListAllTools - Complete inventory of all available tools with metadata
GetToolInfo - Detailed analysis of specific tools including parameters
ListToolsByCategory - Filter tools by category (Math, Utility, Data, Reflection)
SearchTools - Intelligent keyword search across tool names and descriptions
GetServerMetadata - Server introspection including .NET version and capabilities

🚀 Quick Start

Prerequisites

.NET 9.0 SDK
Node.js (for mcp-remote proxy)
Claude Code

Installation

Clone the repository

git clone https://github.com/yourusername/remote-mcp.git
cd remote-mcp

Restore packages
```
dotnet restore
```
Build the project
```
dotnet build
```
Run the server
```
dotnet run
```
The server will start on http://0.0.0.0:3001 with enterprise authentication enabled.

🔐 Authentication Setup

Azure AD Configuration

Option 1: Automated Setup (Recommended)

# Sets up Azure AD app registration automatically
./setup-azure-ad.sh

# The script will:
# 1. Create/update Azure AD app registration
# 2. Configure redirect URIs
# 3. Update appsettings.json automatically
# 4. Optionally create a client secret (for confidential client mode)

Option 2: Manual Setup

Register an Azure AD Application:
- Go to Azure Portal > Azure Active Directory > App registrations
- Create new registration
- Add redirect URI: http://localhost:3001/oauth/callback
- Optionally create a client secret for confidential client mode

Configure Authentication: The application supports two authentication modes:

Public Client with PKCE (Default - no secret needed):

{
  "Authentication": {
    "ExternalIdP": {
      "ClientSecret": ""
    }
  }
}

Confidential Client (Recommended for production):

# Set client secret via environment variable (never hardcode!)
export Authentication__ExternalIdP__ClientSecret="your-secret-here"

# Or use Azure Key Vault for production
./setup-azure-secrets.sh

For Testing (Disable Authentication)

Set Mode to "Disabled" in appsettings.json to bypass authentication

See for detailed enterprise configuration options.

OAuth Flow

The server implements a complete OAuth 2.1 authorization server with mandatory PKCE:

Dynamic Client Registration: MCP clients register dynamically (RFC 7591)
Microsoft Authentication: Users authenticate with their Microsoft account
Token Issuance: Server issues its own JWT tokens after successful auth
Stateless Operation: Uses memory cache for MCP clients that don't maintain cookies

🌐 OAuth Endpoints

Discovery

/.well-known/oauth-authorization-server - OAuth metadata
/.well-known/oauth-protected-resource - Resource metadata

OAuth Flow

/register - Dynamic client registration
/authorize - Authorization endpoint
/oauth/callback - Microsoft callback handler
/token - Token exchange endpoint

Testing the Server

Health Check:

curl http://localhost:3001/health
# Expected: {"status":"healthy","timestamp":"2025-XX-XX..."}

Server Info:

curl http://localhost:3001/info
# Returns server metadata and available endpoints

MCP Protocol Test:

curl http://localhost:3001/
# Expected: MCP protocol error (this confirms MCP is active)

🔗 Claude Desktop/Claude.ai Integration

Using Claude Desktop

Install Claude Desktop
Use the /mcp command
Enter server URL: http://localhost:3001
Complete Microsoft authentication when prompted
MCP tools are now available

Manual Configuration

Add to MCP settings:

Option 2: Manual Configuration

Add to your Claude Code MCP configuration:

{
  "mcpServers": {
    "remote-math-server": {
      "command": "npx",
      "args": ["mcp-remote", "http://localhost:3001/"],
      "description": "Remote MCP server with math, utility, data, and reflection tools"
    }
  }
}

Verification

claude mcp list
# Should show: remote-math-server: npx mcp-remote http://localhost:3001/ - ✓ Connected

🧪 Testing Reflection Features

Try these commands in Claude Code:

Complete Tool Discovery:

"List all available tools"

Tool Analysis:

"Show me detailed information about the divide tool"

Category Filtering:

"What tools are in the Math category?"

Intelligent Search:

"Search for tools related to text processing"

System Information:

"What's the server metadata?"

🏗 Architecture

Core Components

Transport Layer: Streamable HTTP with CORS support
Tool Discovery: Attribute-based auto-registration using [McpServerToolType] and [McpServerTool]
Reflection System: .NET reflection APIs for runtime introspection
Error Handling: Comprehensive validation and graceful error responses
Security: Scoped assembly reflection with attribute-based filtering

Key Patterns

Tool Implementation:

[McpServerToolType]
public static class YourTools
{
    [McpServerTool, Description("What your tool does")]
    public static ReturnType YourMethod(
        [Description("Parameter description")] ParameterType param)
    {
        // Implementation with proper error handling
        return result;
    }
}

Reflection Safety:

// ✅ Safe: Scoped to current assembly only
Assembly.GetExecutingAssembly()

// ✅ Safe: Attribute-based filtering  
.Where(t => t.GetCustomAttribute<McpServerToolTypeAttribute>() != null)

// ✅ Safe: JSON-serializable responses
return new { found = true, data = structuredObject };

🚀 Production Deployment

Network Configuration

The server binds to 0.0.0.0:3001 for network access. Configure your firewall to allow port 3001:

# macOS/Linux - allow port 3001
sudo ufw allow 3001

# Find your server's IP for remote connections
hostname -I

Docker Deployment

FROM mcr.microsoft.com/dotnet/aspnet:9.0
WORKDIR /app
COPY bin/Release/net9.0/publish/ .
EXPOSE 3001
ENTRYPOINT ["dotnet", "remote-mcp.dll"]

Environment Variables

# Production settings
export ASPNETCORE_ENVIRONMENT=Production
export ASPNETCORE_URLS=http://0.0.0.0:3001

🔧 Development

Project Structure

remote-mcp/
├── Program.cs              # Server configuration and startup
├── Authentication/         # Enterprise authentication system
│   ├── Controllers/       # Auth API endpoints
│   ├── Domain/            # DDD domain entities and services
│   ├── Middleware/        # Auth middleware (OAuth 2.1, rate limiting)
│   ├── OAuth/             # OAuth implementation
│   ├── Services/          # Auth services (token, multi-tenant, etc.)
│   └── WebAuthn/          # WebAuthn/Passkey support
├── Configuration/          # App configuration and settings
├── Data/                   # Data access layer
├── Services/               # Core services (MCP lifecycle, etc.)
├── Tools/                  # SOLID-compliant MCP tools
│   ├── MathTools.cs       # Math operations (Add, Subtract, Multiply, Divide)
│   ├── UtilityTools.cs    # Utility functions (Echo, Time, Random)
│   ├── DataTools.cs       # Data manipulation (JSON, Case, Reverse)
│   ├── ReflectionTools.cs # Introspection (5 reflection capabilities)
│   └── AuthenticationTools.cs # OAuth flow testing tools
├── Properties/             # Launch settings and profiles
├── documentation/          # Additional docs and guides
├── remote-mcp.csproj       # Project configuration
├── appsettings.json        # Server configuration
├── setup-azure-ad.sh       # Azure AD setup script
├── setup-azure-secrets.sh  # Secret management script
├── implode.sh             # Cleanup script
├── .mcp.json              # MCP client integration
├── CLAUDE.md              # Development guide
├── LICENSE                # MIT License
└── README.md              # This file

SOLID Principles Compliance

Single Responsibility: Each tool class has one focused purpose
Open/Closed: Add new tool categories without modifying existing code
Clean Separation: Server configuration separate from business logic
Maintainable: Easy to locate, test, and extend specific tool categories

Adding New Tools

Create a new tool file in the Tools/ directory:

// Tools/MyCustomTools.cs
using ModelContextProtocol.Server;
using System.ComponentModel;

[McpServerToolType]
public static class MyCustomTools
{
    [McpServerTool, Description("Description of what your tool does")]
    public static string MyTool([Description("Parameter description")] string input)
    {
        // Your logic here
        return $"Processed: {input}";
    }
}

Automatic Discovery: The tool will be automatically discovered via assembly scanning
Verification: Use the reflection tools (ListAllTools()) to verify registration
Organization: Follow the established patterns in existing tool files

Debugging

Health endpoint: http://localhost:3001/health
Server info: http://localhost:3001/info
MCP Inspector: npx @modelcontextprotocol/inspector@latest http://localhost:3001/
Reflection tools: Use ListAllTools() to verify your tools are registered

📖 Documentation

- Development commands and architecture
- Configuration, deployment, and customization guide
- Step-by-step implementation guide

🔒 Security Considerations

Safe Practices ✅

Scoped reflection to executing assembly only
Attribute-based filtering prevents unintended exposure
No dynamic code execution
Comprehensive input validation
CORS configured for development (restrict for production)

Production Security

Add authentication middleware
Implement rate limiting
Use HTTPS in production
Restrict CORS origins
Configure firewall rules
Monitor for abuse

🤝 Contributing

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Development Guidelines

Follow the established MCP architectural patterns
Add comprehensive descriptions to all tools
Include proper error handling
Update documentation for new features
Test with reflection tools to verify integration

📄 License

This project is licensed under the MIT License - see the file for details.

🙏 Acknowledgments

Built with ModelContextProtocol.AspNetCore
Inspired by Anthropic's MCP specification

📊 Stats

16 Tools across 4 categories
5 Reflection Tools for self-documentation
Production Ready with ASP.NET Core
Network Enabled for distributed access
Comprehensive Testing with health checks and MCP Inspector support