Vercel MCP Memory

Custom Model Context Protocol (MCP) memory server deployed on Vercel with semantic search powered by OpenAI embeddings and PostgreSQL pgvector.

✨ Features

• 🧠 Semantic Search - Find memories by meaning, not just keywords
• 🔐 Secure API - Optional API key authentication for production
• ☁️ Cloud-Hosted - Deployed on Vercel Edge Functions (zero-infrastructure)
• 🔄 Cross-Device Sync - Access your memory from any device with Claude
• 🚀 OpenAI Embeddings - Using text-embedding-3-small model
• 🗄️ PostgreSQL + pgvector - Efficient vector similarity search
• ✅ Input Validation - Zod schemas for robust data validation
• 📝 Structured Logging - Production-ready error tracking
• 🌍 Multi-language - Supports Russian, English and more
• 🤖 Claude Code Integration - Automated PR reviews and AI assistant via GitHub Actions

🏗️ Architecture

Claude Desktop → HTTPS/JSON-RPC → Vercel Edge Function → Postgres (pgvector)
                                         ↓
                                   OpenAI Embeddings API

📋 Prerequisites

• Node.js 20.x
• Vercel account (free tier works)
• OpenAI API key (for embeddings, ~$0.10/1M tokens)
• PostgreSQL database with pgvector extension (Vercel Postgres or Neon)

🚀 Quick Start

1. Install Dependencies

cd vercel-mcp-memory
npm install

2. Set Up Vercel Postgres

# Install Vercel CLI
npm i -g vercel

# Login to Vercel
vercel login

# Link project
vercel link

# Create Postgres database (via Vercel Dashboard)
# 1. Go to https://vercel.com/dashboard
# 2. Navigate to Storage → Create Database → Postgres
# 3. Name: mcp-memory-db
# 4. Region: Select closest to you

3. Configure Environment Variables

Create .env.local file:

# Required: OpenAI API key for embeddings
OPENAI_API_KEY=sk-...

# Required: PostgreSQL connection (auto-configured by Vercel)
POSTGRES_URL=postgresql://...

# Optional: API keys for authentication (comma-separated)
# Leave empty for development without auth
MCP_API_KEYS=your-secret-key-1,your-secret-key-2

Generate secure API keys:

# Generate a secure API key
openssl rand -base64 32

4. Run Database Migration

Apply the SQL schema with pgvector extension:

# Option 1: Via Vercel Dashboard
# 1. Go to Storage → mcp-memory-db → SQL Editor
# 2. Copy contents of migrations/001_init.sql
# 3. Execute

# Option 2: Via psql (if you have local connection)
psql $POSTGRES_URL < migrations/001_init.sql

5. Deploy to Vercel

vercel --prod

Your MCP server will be available at: https://your-project.vercel.app

6. Configure Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or ~/.config/claude-desktop/claude_desktop_config.json (Linux):

With authentication (recommended for production):

{
  "mcpServers": {
    "vercel-memory": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://your-project.vercel.app/api/mcp/sse"
      ],
      "env": {
        "MCP_API_KEY": "your-secret-key-here"
      }
    }
  }
}

Without authentication (development only):

{
  "mcpServers": {
    "vercel-memory": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://your-project.vercel.app/api/mcp/sse"
      ]
    }
  }
}

Restart Claude Desktop.

🧪 Testing

Health Check

curl https://your-project.vercel.app/api/health

Should return:

{
  "status": "healthy",
  "service": "vercel-mcp-memory",
  "database": {
    "connected": true
  }
}

Test MCP Endpoint with Authentication

curl -X POST https://your-project.vercel.app/api/mcp/sse \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-secret-key" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/list",
    "id": 1
  }'

Test in Claude

User: Remember: I prefer Python for backend development
Claude: [Uses add_memory tool]

User: What programming languages do I prefer?
Claude: [Uses search_memory tool and finds "Python"]

📊 MCP Tools

add_memory

Store new memory with semantic embeddings.

{
  content: string,      // Required (1-10000 chars)
  category?: string,    // Optional (max 100 chars)
  metadata?: object     // Optional custom key-value pairs
}

search_memory

Semantic search across memories.

{
  query: string,        // Required: natural language query (1-1000 chars)
  category?: string,    // Filter by category
  limit?: number,       // Max results (default: 10, max: 50)
  threshold?: number    // Min similarity 0-1 (default: 0.5)
}

list_memories

List all memories chronologically.

{
  category?: string,    // Filter by category
  limit?: number,       // Max results (default: 50, max: 100)
  offset?: number       // Pagination offset (default: 0)
}

delete_memory

Delete specific memory by UUID.

{
  id: string           // UUID of memory (validated)
}

memory_stats

Get statistics about stored memories.

{}  // No parameters

📁 Project Structure

vercel-mcp-memory/
├── app/
│   ├── api/
│   │   ├── health/route.ts          # Health check endpoint
│   │   └── mcp/sse/route.ts         # MCP JSON-RPC endpoint
│   ├── layout.tsx                   # Next.js layout
│   └── page.tsx                     # Landing page
├── lib/
│   ├── auth.ts                      # API authentication
│   ├── db.ts                        # Postgres + pgvector queries
│   ├── embeddings.ts                # OpenAI embeddings client
│   ├── logger.ts                    # Structured logging
│   ├── mcp-handlers.ts              # Centralized tool handlers
│   ├── mcp-server.ts                # MCP SDK integration
│   ├── types.ts                     # TypeScript definitions
│   └── validation.ts                # Zod input validation
├── migrations/
│   └── 001_init.sql                 # Database schema
├── scripts/
│   ├── insert-test-data.ts          # Test data seeding
│   └── migrate-old-data.ts          # Legacy data migration
├── .env.example                     # Environment variables template
├── .eslintrc.json                   # ESLint configuration
├── .gitignore                       # Git ignore rules
├── SECURITY.md                      # Security guidelines
├── next.config.js                   # Next.js configuration
├── package.json                     # Dependencies
├── tsconfig.json                    # TypeScript configuration
└── vercel.json                      # Vercel deployment config

🔧 Development

# Run locally
npm run dev

# Build for production
npm run build

# Lint code
npm run lint

# Migrate old data
npm run migrate

🔐 Security

See SECURITY.md for security best practices.

Important:

• Never commit .env.local or .env.production files
• Rotate API keys regularly
• Enable MCP_API_KEYS authentication in production
• Monitor API usage to prevent quota exhaustion
• Review SECURITY.md before deploying

💰 Cost Estimation

Vercel Free Tier (sufficient for personal use):

• ✅ Functions: 100 GB-hours/month
• ✅ Postgres: 256 MB storage
• ✅ Bandwidth: 100 GB

After free tier:

• Postgres: ~$0.20/GB/month
• OpenAI Embeddings: $0.10/1M tokens ($0.02/month for typical usage)
• Functions: ~$40/100 GB-hours

Expected cost: $0-5/month for moderate personal use.

🐛 Troubleshooting

Claude can't connect

1. Check health endpoint: curl https://your-project.vercel.app/api/health
2. Verify API key matches in both Vercel env and Claude config
3. Check Vercel deployment: vercel ls
4. Verify Claude config path is correct
5. Restart Claude Desktop

Authentication errors

1. Verify MCP_API_KEYS is set in Vercel environment variables
2. Check API key format (no extra spaces or newlines)
3. Ensure Claude config includes MCP_API_KEY in env section
4. Try without authentication first (remove MCP_API_KEYS from Vercel env)

Database errors

1. Verify pgvector extension is enabled:

   SELECT * FROM pg_extension WHERE extname = 'vector';

2. Check table exists:

   \dt memories

3. View connection logs in Vercel Dashboard → Functions → Logs

Embedding errors

1. Verify OpenAI API key is set: vercel env ls
2. Check API key has sufficient credits
3. Monitor usage: https://platform.openai.com/usage

📖 Resources

• Vercel Documentation
• MCP Specification
• OpenAI Embeddings
• pgvector

🤖 Claude Code Integration

This repository uses Claude Code via GitHub Actions for automated code reviews and AI assistance.

Automated PR Reviews

Every pull request automatically receives a comprehensive code review from Claude, focusing on:

• Code quality and best practices
• Potential bugs and security issues
• Performance considerations
• Test coverage

Interactive AI Assistant

Mention @claude in any issue or PR comment to get help:

@claude Please review the security implications of these auth changes.
@claude Help me fix the TypeScript errors in lib/db.ts.
@claude Update CLAUDE.md to reflect the new architecture.

For detailed setup and troubleshooting, see .github/CLAUDE_CODE_SETUP.md.

📝 License

MIT

🤝 Contributing

Contributions are welcome! Please read our Contributing Guidelines and Code of Conduct first.

Quick steps:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

For questions or support, see SUPPORT.md.

🙏 Acknowledgments

Built with:

• Vercel - Hosting and Postgres
• Next.js - React framework
• OpenAI - Embeddings API
• MCP SDK - Protocol implementation
• pgvector - Vector similarity search

---

Made with ❤️ using Vercel, Next.js, and Claude Code