MCP Server Reference Implementations

This repository provides reference implementations for hosted MCP (Model Context Protocol) servers built on open source technologies. These implementations serve as a foundation for continued development and demonstrate different architectural patterns for building production-ready MCP servers.

What is MCP?

The Model Context Protocol (MCP) is an open standard that enables users as well as AI agents to securely connect to data sources and tools. MCP servers expose resources, tools, and prompts that AI models can use to enhance their capabilities.

Repository Overview

This repository contains two complete reference implementations designed for remote hosted MCP servers that can be deployed to the cloud and accessed over HTTP:

📁 basic/

A minimal MCP server implementation that demonstrates the core concepts and basic functionality.

Features:

• Simple Next.js 15 application with App Router
• MCP server endpoints using mcp-handler library
• Example tool implementation
• Ready for immediate deployment
• Minimal dependencies and configuration

Perfect for:

• Learning MCP fundamentals
• Quick prototyping
• Simple tool implementations
• Educational purposes

📁 with-authorization/

A comprehensive MCP server implementation with full authentication and authorization capabilities.

Features:

• Complete authentication system with user sign-up/sign-in
• Fine-grained authorization using SpiceDB
• OAuth 2.0 compliance for MCP authorization specification
• Session management with better-auth
• Example permission model
• Examples for managing user permissions

Perfect for:

• Foundation for production hosted MCP servers

Open Source Foundation

This project is built entirely on open source solutions to ensure transparency, security, and extensibility:

Core Technologies

• Next.js 15 - Modern React framework with App Router
• TypeScript - Type safety and developer experience
• Node.js - Runtime environment

MCP Implementation

• @modelcontextprotocol/sdk - Official TypeScript SDK for MCP
• mcp-handler - Simplified MCP server creation library
• Zod - Runtime type validation for tool parameters

Authentication & Authorization (with-authorization only)

• better-auth - Modern authentication library with PostgreSQL backend
• SpiceDB - Google Zanzibar-inspired authorization system
• PostgreSQL - Reliable database for user data

UI & Styling (with-authorization only)

• TailwindCSS - Utility-first CSS framework
• shadcn/ui - High-quality accessible UI components
• Radix UI - Primitive components for accessibility
• Lucide React - Beautiful icon library

External Services

Required for with-authorization

• PostgreSQL - Database for user authentication data
• SpiceDB - Authorization service for permission management
  • Can run locally for development
  • AuthZed Cloud recommended for production

Getting Started

1. Choose your implementation:

   • For learning or simple tools: Start with basic/
   • For building production applications: Use with-authorization/

2. Follow the setup guide:

   • Each directory contains detailed setup instructions
   • Environment configuration examples included
   • Development and deployment guides provided

3. Deploy easily:

   • One-click Vercel deployment buttons included
   • Environment variable guides for cloud deployment
   • Starter configurations

Architecture Benefits

• Maintainable: Clean TypeScript code with comprehensive documentation
• Extensible: Open source foundation allows for custom modifications
• Standards Compliant: Full MCP specification compliance including authorization

Contributing

This reference implementation serves as a foundation for the community to build upon. Contributions that improve security, performance, documentation, or add new features are welcome.

Resources

• Model Context Protocol Specification
• MCP Authorization Specification
• Next.js Documentation
• SpiceDB Documentation
• Better Auth Documentation

License

See LICENSE for details.