MCP Scratchpad Server

A Model Context Protocol (MCP) server that provides AI assistants with persistent scratchpad capabilities using PostgreSQL and OpenAI vector embeddings.

Description

This server implements the Model Context Protocol to give AI assistants the ability to store, search, update, and delete scratchpad entries using semantic vector search. Each AI context maintains completely isolated scratchpad spaces for security and privacy.

Features

• Persistent Scratchpad: Store text content with vector embeddings for semantic search
• Vector Search: Find similar entries using OpenAI embeddings and PostgreSQL pgvector
• Context Isolation: Each AI context has separate, secure scratchpad spaces
• CRUD Operations: Create, read, update, and delete scratchpad entries
• MCP Compliance: Standard Model Context Protocol implementation
• Flexible Configuration: Support for different OpenAI models and endpoints

Prerequisites

• Rust 1.75+
• PostgreSQL with pgvector extension
• OpenAI API key

Build

1. Clone the repository:

git clone <repository-url>
cd mcp-scratchpad

2. Build the project:

cargo build --release

The executable will be created at target/release/mcp-scratchpad.

Configuration

Environment Variables

Variable	Description	Default
DATABASE_URL	PostgreSQL connection string	postgresql://localhost/mcp_scratchpad
OPENAI_API_KEY	OpenAI API key (required)	-
BIND_ADDRESS	Server bind address	127.0.0.1:3001
EMBEDDING_MODEL	OpenAI embedding model	text-embedding-3-small
EMBEDDING_SIZE	Vector dimension size	1024
OPENAI_BASE_URL	Custom OpenAI endpoint (optional)	-

Database Setup

1. Install PostgreSQL with pgvector extension
2. Create database:

createdb mcp_scratchpad

The server will automatically initialize the database and run migrations on first use.

Manual Migration

You can run migrations manually before starting the server:

./target/release/mcp-scratchpad migrate

This is useful for:

• Pre-deployment database setup
• Controlled migration timing
• Troubleshooting database issues

Migration System

The server includes a robust migration system that:

• Automatically initializes fresh databases
• Applies schema updates when upgrading versions
• Tracks migration history in a schema_version table
• Supports both automatic and manual migration modes

Database schema changes are applied incrementally and safely.

Run

1. Set required environment variables:

export DATABASE_URL=postgresql://localhost/mcp_scratchpad
export OPENAI_API_KEY=your-api-key-here

2. Start the server:

./target/release/mcp-scratchpad

The server will be available at http://localhost:3001.

Health Checks

The server provides health check endpoints for monitoring:

• GET /health - Overall system health and migration status
• GET /ready - Readiness check (returns 200 only when fully ready)
• GET /live - Liveness check (returns 200 if service is running)

These endpoints are useful for container orchestration and load balancers.

Quick Start with Docker

export OPENAI_API_KEY=your-api-key-here
docker-compose up -d

Tools

The server provides four MCP tools:

• store_scratchpad - Store content with vector embedding
• search_scratchpad - Search scratchpad entries by similarity
• update_scratchpad - Update existing scratchpad entry by ID
• delete_scratchpad - Remove scratchpad entry by ID

Integration

Use the provided mcp-manifest.json for MCP client configuration, or configure your client to connect to the server endpoints directly.

License

ISC License