NavtejDhillon/barebones-mcp-server

Skeleton MCP Server

A production-ready skeleton for building MCP (Model Context Protocol) servers with Supabase integration, proper authentication, and modular architecture.

Features

• ✅ Modular architecture (separate handlers, tools, utils)
• ✅ Supabase authentication with OAuth flow
• ✅ SSE (Server-Sent Events) transport for MCP
• ✅ Proper error handling and logging
• ✅ Database schema validation
• ✅ RLS (Row Level Security) support
• ✅ Systemd service configuration
• ✅ Environment-based configuration

Project Structure

skeleton-mcp-server/
├── server.py              # Main server file
├── handlers/             # Tool handlers (business logic)
│   ├── __init__.py
│   └── example_handlers.py
├── tools/               # Tool definitions (MCP interface)
│   ├── __init__.py
│   └── example_tools.py
├── utils/              # Utility functions
│   ├── __init__.py
│   ├── auth.py        # Authentication utilities
│   └── database.py    # Database utilities
├── tests/             # Test files
├── docs/              # Documentation
│   └── SCHEMA_GUIDE.md
├── .env.example       # Environment variables template
├── requirements.txt   # Python dependencies
└── systemd/          # Systemd service files
    └── mcp-server.service

Quick Start

1. Clone the repository
2. Copy .env.example to .env and configure
3. Install dependencies: pip install -r requirements.txt
4. Run the server: python server.py

Key Learnings Incorporated

1. Database Schema Matching

• Always verify database column names match handler field names
• Common gotchas:
  • name vs company_name vs vendor_name
  • email vs main_email vs contact_email
  • tax_amount vs gst_amount
  • total vs total_amount vs line_total

2. Authentication Flow

• Support both OAuth and direct token validation
• Handle Claude's token caching behavior
• Proper CORS configuration for Claude.ai

3. SSE Implementation

• Correct headers for SSE streaming
• Proper error response formatting
• Handle MCP protocol methods correctly

4. Modular Architecture

• Separate concerns: tools (interface) vs handlers (logic)
• Easy to add new tools without modifying core server
• Centralized error handling

Adding New Tools

1. Define tool schema in tools/your_tools.py
2. Implement handler in handlers/your_handlers.py
3. Register in respective __init__.py files
4. Restart server

Environment Variables

See .env.example for all required variables:

• SUPABASE_URL: Your Supabase instance URL
• SUPABASE_SERVICE_KEY: Service role key (full access)
• SUPABASE_ANON_KEY: Anonymous key (public access)
• DATABASE_URL: Direct database connection (if needed)
• SERVER_PORT: Port to run server on (default: 8080)

Database Setup

1. Ensure your Supabase tables exist
2. Enable RLS policies for security
3. Document your schema in docs/SCHEMA_GUIDE.md

Deployment

See systemd/mcp-server.service for production deployment with systemd.

Common Issues & Solutions

1. "Column not found" errors: Check actual database schema vs handler fields
2. Authentication failures: Ensure CORS is configured for Claude.ai
3. SSE connection drops: Check response headers and keep-alive settings
4. Token validation fails: May need to handle cached tokens temporarily

License

MIT