Keycard Hello Server

A production-ready MCP server demonstrating OAuth 2.0 authentication with Keycard's Security Token Service (STS). This project showcases best practices for building secure, type-safe, and modular MCP servers with enterprise-grade observability.

TypeScript Node.js MCP Protocol OAuth 2.0

🎯 What This Demonstrates

• 🔒 OAuth 2.0 Authentication - Secure authentication via Keycard STS
• ✨ Type Safety - Full TypeScript with Zod runtime validation
• 🏗️ Modular Architecture - Clean separation of concerns for easy extension
• 🚀 Production Ready - Error handling, validation, and comprehensive logging
• 📚 Educational - Well-documented code showing MCP best practices
• 🧪 Testing Framework - Jest with coverage, integration tests, and watch modes
• 📊 Observability - OpenTelemetry integration with traces and metrics

🚀 Quick Start

🏗️ Architecture

┌─────────────┐    ┌──────────────┐    ┌─────────────┐
│   Cursor    │───▶│  MCP Server  │───▶│ Keycard STS │
│    IDE      │    │ (localhost:  │    │             │
│             │    │     8888)    │    │             │
└─────────────┘    └──────────────┘    └─────────────┘
       │                   │                   │
   OAuth Flow          JWT Validation      Token Issuance

🔄 Authentication Flow

1. Cursor discovers OAuth endpoints from MCP server
2. User authenticates via Keycard STS (redirected to identity provider)
3. Keycard STS issues JWT access tokens
4. MCP Server validates tokens and grants access to tools

Prerequisites

• Node.js 18+ and npm
• Cursor IDE (or any MCP-compatible client)
• Keycard account with access to the Console
• Configured Keycard zone (for authentication)

1. Clone & Install

git clone https://github.com/keycardai/hello-mcp-server.git
cd hello-mcp-server
npm install

2. Configure Environment

Create a .env file:

# Required: Your Keycard STS issuer URL
KEYCARD_STS_ISSUER_URL=https://your-zone-id.keycard.cloud

# Optional: Server configuration
PORT=8888
HOST=localhost

💡 Finding your Zone ID:

1. Log into the Keycard Console
2. Navigate to Zone Settings
3. Copy the Zone ID (e.g., j434uokph8th1ia1npxiaykh7p)
4. Replace your-zone-id in your STS URL

Note: Use the zone ID, not the zone name or label.

3. Start the Server

# Development mode with auto-reload
npm run dev

# Production mode
npm run build && npm start

You should see:

🚀 Keycard Hello MCP Server started!
🔗 MCP Endpoint: http://localhost:8888/mcp
🔐 STS Issuer: https://your-zone-id.keycard.cloud
🛠️  Available Tools: keycard-logo, whoami

4. Configure Cursor IDE

Add to your Cursor MCP settings:

{
  "mcpServers": {
    "keycard-hello-mcp": {
      "url": "http://localhost:8888/mcp"
    }
  }
}

5. Test Authentication

1. Restart Cursor to pick up the new MCP server
2. Cursor will show "needs login" for the server
3. Click to authenticate → complete OAuth flow
4. Use the tools: keycard-logo, whoami

🛠️ Available Tools

keycard-logo

Displays the official Keycard ASCII art logo.

whoami

Provides detailed information about the authenticated user including:

• Client ID and authentication scopes
• JWT payload with user information
• Token expiration and timing details
• Custom claims and metadata

🔧 Configuration

Environment Variables

Variable	Description	Default	Required
KEYCARD_STS_ISSUER_URL	Keycard STS issuer URL (single-tenant mode)	-	✅*
ISSUER_BASE_DOMAIN	Base domain for STS (multi-tenant mode)	-	✅*
MCP_BASE_DOMAIN	Base domain for MCP server (multi-tenant mode)	-	✅*
PORT	Server port	8888
HOST	Server host	localhost
LOG_LEVEL	Logging level	INFO
ENABLE_OTEL	Enable OpenTelemetry	true
OTEL_SERVICE_NAME	Service name for telemetry	hello-mcp-server
OTEL_ENVIRONMENT	Environment for telemetry	development

*Either KEYCARD_STS_ISSUER_URL (single-tenant) OR ISSUER_BASE_DOMAIN + MCP_BASE_DOMAIN (multi-tenant) is required.

Multi-Tenant Configuration

For multi-tenant deployments (serving multiple organizations/zones), use these environment variables instead:

# Multi-tenant mode
ISSUER_BASE_DOMAIN=keycard.cloud
MCP_BASE_DOMAIN=mcp.example.com

# Other configuration
PORT=8888
ENABLE_OTEL=true

This enables dynamic issuer discovery based on subdomain routing, allowing one deployment to serve multiple Keycard zones.

Observability

The server includes comprehensive observability features:

• Structured Logging: Environment-aware logging with trace correlation
• Request Tracing: Full distributed tracing with OpenTelemetry
• Metrics Collection: Performance and usage metrics
• Health Checks: Available at /health

In development, logs are formatted for console readability. In production, logs are sent to configured OTLP endpoints.

🏗️ Architecture

src/
├── config.ts              # Configuration management
├── index.ts               # Application entry point
├── server.ts              # Express server setup
├── middleware/            # Express middlewares
│   ├── auth.ts           # Authentication middleware
│   └── logging.ts        # Request logging and tracing
├── observability/         # Telemetry and logging
│   ├── logger.ts         # Structured logger
│   └── telemetry.ts      # OpenTelemetry setup
├── tools/                 # MCP tools
│   ├── index.ts          # Tool registration
│   ├── logo.ts           # Keycard logo tool
│   └── whoami.ts         # User information tool
└── types/                 # Type definitions
    ├── auth.ts           # Authentication types
    └── index.ts          # Exported types

🧪 Testing

# Run all tests
npm test

# Run tests with coverage
npm run test:coverage

# Run integration tests
npm run test:integration

# Watch mode for development
npm run test:watch

📊 Code Quality

# Lint code
npm run lint

# Fix linting issues
npm run lint:fix

# Format code
npm run format

# Check all (lint + format)
npm run check

# Fix all issues
npm run check:fix

🔗 MCP Integration

Cursor IDE

1. Start the server: npm run dev
2. In Cursor, go to Settings > MCP Servers
3. Add server: http://localhost:8888/mcp

🚦 Health Checks

The server provides a health check endpoint at /health:

curl http://localhost:8888/health

Response:

{
  "status": "healthy",
  "timestamp": "2024-01-01T00:00:00.000Z",
  "service": "hello-mcp-server",
  "version": "1.0.0"
}

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests and quality checks
5. Submit a pull request

📄 License

Apache-2.0 License - see LICENSE file for details.