MCP Server Examples Analysis

Overview

The repository includes two example MCP (Model Context Protocol) server implementations that demonstrate different approaches to building MCP-compliant servers. These servers showcase the protocol's capabilities for tools, resources, and prompts while running on modern edge computing platforms.

Server Implementations

1. Hono MCP Server (examples/servers/hono-mcp/)

Project Configuration (package.json)

Name: "vengabus" - A playful party-themed MCP server
Platform: Cloudflare Workers with Hono framework
Dependencies:

  • hono: Web framework for edge computing
  • @hono/mcp: Hono-specific MCP transport implementation
  • @modelcontextprotocol/sdk: Core MCP protocol implementation
  • zod: Runtime type validation and schema definition

Server Implementation (src/index.ts)

Framework Setup (Lines 7-22):

const app = new Hono()
const mcpServer = new McpServer({
  name: 'vengabus-mcp-server',
  version: '1.0.0',
})

CORS Configuration (Lines 9-16):

  • Universal Origin: Allows connections from any domain
  • MCP Headers: Supports MCP-specific headers for session management
  • Protocol Version: Enables MCP protocol version negotiation

Tool Implementations

1. Party Capacity Calculator (Lines 24-42):

  • Purpose: Calculates total capacity across multiple party buses
  • Input Schema: Uses Zod for type-safe parameter validation
    • busCount: Number of buses (number)
    • peoplePerBus: Capacity per bus (number)
  • Output: Formatted text with party-themed messaging
  • Business Logic: Simple multiplication with engaging presentation

2. Schedule Checker (Lines 44-79):

  • Purpose: Provides party bus schedule information
  • Input Schema: No parameters required (empty schema)
  • Async Simulation: Includes random delay to simulate real-world API calls
  • Output: Rich text with route information, timing, and status updates
  • Response Format: Multi-line text with emojis and party-themed content

Resource Implementations

1. Fleet Configuration (Lines 82-116):

  • URI: config://vengabus
  • Type: Static JSON configuration
  • Content: Fleet settings including:
    • Audio features (bass boost, strobe lights)
    • Performance parameters (max BPM)
    • Available routes and destinations
  • MIME Type: application/json

2. Party Manual (Lines 118-135):

  • URI: docs://party-manual.md
  • Type: Static Markdown documentation
  • Content: User guide with features, routes, and current status
  • MIME Type: text/markdown

3. Dynamic Statistics (Lines 138-181):

  • URI Template: party://stats/{metric}
  • Type: Dynamic resource with parameter substitution
  • Supported Metrics: BPM, passengers, energy levels
  • Dynamic Content: Random values simulating real-time metrics
  • Template Processing: Extracts metric parameter from URI pattern

Prompt Implementations

1. Party Invitation (Lines 184-205):

  • Purpose: Generates personalized party invitations
  • Parameters:
    • name: Required person's name
    • destination: Optional destination
  • Output: User message template for AI systems
  • Use Case: Template for AI to create engaging invitations

2. Party Announcement (Lines 207-228):

  • Purpose: Creates announcements for various events
  • Parameters:
    • event: Type of event (deployment, release, milestone)
    • details: Optional additional information
  • Output: User message template for announcement generation
  • Use Case: Template for AI to create themed announcements

Transport Integration (Lines 230-236)

app.post('/mcp', async (c) => {
  const transport = new StreamableHTTPTransport()
  await mcpServer.connect(transport)
  return transport.handleRequest(c)
})
  • HTTP Endpoint: /mcp for MCP protocol communication
  • Transport: Uses Hono-specific streamable HTTP transport
  • Integration: Seamless connection between Hono and MCP SDK

2. Cloudflare Agents MCP Server (examples/servers/cf-agents/)

Project Configuration (package.json)

Name: "remote-mcp-server-authless" - Calculator-themed server with OAuth
Platform: Cloudflare Workers with Agents framework
Dependencies:

  • @modelcontextprotocol/sdk: Core MCP implementation
  • agents: Cloudflare Agents framework for MCP
  • @cloudflare/workers-oauth-provider: OAuth authentication
  • hono: Web framework for HTTP handling
  • zod: Schema validation

Server Architecture (src/index.ts)

Agent Class Structure (Lines 8-146):

export class MyMCP extends McpAgent {
  server = new McpServer({
    name: 'Authless Calculator',
    version: '1.0.0',
  })
}

Framework Integration: Uses Cloudflare Agents framework pattern
Initialization: Async setup in init() method

Tool Implementations

1. Simple Addition (Lines 16-18):

  • Purpose: Basic addition operation
  • Parameters: Two numbers (a, b)
  • Implementation: Direct addition with string result
  • Use Case: Simple calculation demonstration

2. Multi-Operation Calculator (Lines 21-55):

  • Purpose: Comprehensive calculator with multiple operations
  • Parameters:
    • operation: Enum of supported operations (add, subtract, multiply, divide)
    • a, b: Numeric operands
  • Error Handling: Division by zero protection
  • Switch Logic: Operation-specific calculations
  • Result Format: Consistent string output

Resource Implementations

1. Calculation History (Lines 58-75):

  • URI: calc://history
  • Content: JSON array of past calculations
  • Data Structure: Timestamp, operation, operands, results
  • Use Case: Audit trail and usage tracking

2. Calculator Settings (Lines 77-93):

  • URI: calc://settings
  • Content: Configuration parameters
  • Settings: Precision, negative number support, maximum values
  • Use Case: Runtime configuration access

3. Dynamic Statistics (Lines 96-111):

  • URI: calc://stats
  • Content: Real-time usage statistics
  • Dynamic Data: Random total calculations, current timestamp
  • Use Case: Monitoring and analytics

Prompt Implementations

1. Math Problem Generator (Lines 114-132):

  • Purpose: Creates educational math problems
  • Parameters:
    • difficulty: Problem complexity level
    • topic: Optional subject area
  • Output: User message for AI problem generation
  • Use Case: Educational content creation

2. Calculation Explanation (Lines 134-144):

  • Purpose: Provides step-by-step calculation explanations
  • Parameters: operation type to explain
  • Output: User message for AI explanation generation
  • Use Case: Educational tool for learning math concepts

OAuth Integration (Lines 156-171)

Authorization Handler:

  • Endpoint: /authorize
  • User Simulation: Uses example email for demo purposes
  • OAuth Flow: Complete authorization with metadata
  • Redirect: Proper OAuth callback handling

Multi-Transport Support (Lines 173-203)

Public Endpoints (Lines 177-182):

  • SSE Endpoint: /public/sse for Server-Sent Events
  • HTTP Endpoint: /public/mcp for HTTP transport
  • No Authentication: Public access for testing

Protected Endpoints (Lines 186-201):

  • OAuth Integration: Protected /sse and /mcp endpoints
  • Dynamic Client Registration: Supports RFC 7591
  • Token Management: OAuth token endpoint
  • Fallback Handling: 404 for unknown routes

Key Design Patterns

1. Theme-Driven Development

Both servers use consistent themes (party bus vs. calculator) throughout their implementations, making them engaging examples while demonstrating MCP features.

2. Schema-First Design

Both servers use Zod schemas for type safety and automatic validation, ensuring robust parameter handling and clear API contracts.

3. Resource URI Patterns

  • Custom Schemes: config://, docs://, party://, calc://
  • Template Support: Dynamic URI templates with parameter substitution
  • MIME Type Compliance: Proper content type declarations

4. Transport Flexibility

Both servers support multiple transport mechanisms:

  • HTTP POST for request/response patterns
  • Server-Sent Events for streaming communication
  • Proper CORS configuration for browser compatibility

5. Error Handling

  • Input Validation: Schema-based parameter validation
  • Business Logic Errors: Domain-specific error handling (e.g., division by zero)
  • Graceful Degradation: Meaningful error messages

6. Authentication Patterns

  • Public Access: Hono server with no authentication
  • OAuth Integration: Cloudflare server with full OAuth support
  • Dual Endpoints: Public and protected versions of the same functionality

Production Considerations

1. Deployment

  • Edge Computing: Both designed for Cloudflare Workers
  • Serverless: No persistent state, stateless operations
  • Global Distribution: Automatic worldwide deployment

2. Scalability

  • Stateless Design: No shared state between requests
  • Lightweight Operations: Fast computation without external dependencies
  • Edge Optimization: Minimal cold start overhead

3. Security

  • Input Validation: Zod schemas prevent injection attacks
  • CORS Configuration: Controlled cross-origin access
  • OAuth Support: Enterprise-grade authentication (CF Agents)

4. Monitoring

  • Structured Logging: JSON-based log output
  • Error Tracking: Proper error propagation
  • Performance Metrics: Built-in Cloudflare analytics

Educational Value

1. MCP Protocol Demonstration

Both servers showcase all major MCP features:

  • Tools: Interactive functions with parameters
  • Resources: Static and dynamic content access
  • Prompts: AI integration templates
  • Transport: Multiple communication methods

2. Framework Comparison

  • Hono Approach: Direct MCP SDK integration
  • Agents Approach: Framework-abstracted MCP implementation
  • Trade-offs: Simplicity vs. feature richness

3. Authentication Patterns

  • Public Servers: Simple, no-auth development
  • Enterprise Servers: OAuth-protected production use
  • Hybrid Approach: Public and protected endpoints

These example servers provide comprehensive reference implementations for developers building MCP-compliant services, demonstrating both simple and complex integration patterns while maintaining engaging, theme-driven functionality that makes the examples memorable and easy to understand.