bborbe/sample_mcp_server

Sample MCP Server

A comprehensive demonstration of Model Context Protocol (MCP) server implementations using the mcp-go library. This repository showcases different transport methods, authentication mechanisms, and typed tool implementations.

Overview

This project demonstrates various MCP server configurations:

• Multiple Transport Methods: stdio, HTTP, and Server-Sent Events (SSE)
• Production Features: Health checks, metrics, logging, and error handling
• Authentication: OAuth 2.0 integration with Google
• Typed Tools: Complex JSON schema validation with nested objects and arrays
• Client Examples: SSE client for testing server implementations

Architecture

Core Components

The MCP server is built around a single greeting tool that demonstrates complex typed argument handling:

• String validation: Required name parameter
• Numeric constraints: Age with min/max validation (0-150)
• Boolean defaults: VIP status flag
• Array handling: List of spoken languages
• Nested objects: Metadata with location and timezone

Server Implementations

Running Servers

1. CLI Server (stdio)

go run ./cmd/cli/main.go

Perfect for MCP clients that communicate over stdin/stdout.

2. HTTP Server

go run ./cmd/http-server/main.go

Starts on :8080 with endpoint http://localhost:8080/mcp

3. Production HTTP Server

go run ./cmd/http-server-mux/main.go -listen=:8080

Includes health checks (/healthz), readiness (/readiness), and metrics (/metrics).

4. OAuth HTTP Server

export OAUTH_CLIENT_ID="your-google-client-id"
export OAUTH_SECRET="your-google-client-secret"
export JWT_SECRET="your-jwt-secret-key"

go run ./cmd/oauth-server/main.go

5. SSE Server

go run ./cmd/sse-server/main.go

Server-Sent Events transport on http://localhost:8080/sse

6. Production SSE Server

go run ./cmd/sse-server-mux/main.go -listen=:8080

Testing with SSE Client

# Test default server
go run ./cmd/sse-client/main.go

# Test custom server
go run ./cmd/sse-client/main.go -url=http://localhost:8080/mcp

Usage Examples

Basic Greeting Tool

{
  "name": "greeting",
  "arguments": {
    "name": "Alice",
    "age": 30,
    "is_vip": true,
    "languages": ["English", "Spanish"],
    "metadata": {
      "location": "New York",
      "timezone": "EST"
    }
  }
}

OAuth Authentication Setup

1. Create Google OAuth Application:

   • Go to Google Cloud Console
   • Create OAuth 2.0 credentials
   • Set authorized redirect URI: http://localhost:8080/callback

2. Environment Variables:

   export OAUTH_CLIENT_ID="your-google-client-id"
   export OAUTH_SECRET="your-google-client-secret"
   export JWT_SECRET="your-jwt-signing-key"
   

3. OAuth Flow:

   • Server provides OAuth discovery endpoints
   • Handles Google OAuth authorization flow
   • Requires Authorization header for MCP requests

Integrating with Claude

# Add HTTP server to Claude
claude mcp add sample http://localhost:8080/mcp/http

# Add OAuth server to Claude
claude mcp add -s project --transport http sample http://localhost:8080/mcp/http

# Check it is working
claude
> /mcp

# Use the greeting tool
claude
> Use the greeting tool to greet Alice, age 30, VIP status true

Transport Comparison