TTG Scratchpad MCP Server

Production-ready MCP server for agent workspace/scratchpad functionality with MongoDB persistence and user isolation.

Features

• Persistent Workspaces: Tasks and files stored in MongoDB Atlas
• User Isolation: Each user has their own isolated workspace (via X-User-ID header)
• File Management: Create, read, update, delete files in workspace
• Progress Tracking: Real-time progress updates visible in chat widget
• Activity Logging: Full audit trail of workspace operations
• Bearer Authentication: Secure API access via MCP_API_KEYS

Tools

Workspace Management

• scratchpad_start - Start a new task workspace
• scratchpad_update - Update progress during task
• scratchpad_complete - Mark task as complete
• scratchpad_demo - Demo widget with sample data

File Management

• scratchpad_write_file - Save file to workspace
• scratchpad_read_file - Read file from workspace
• scratchpad_list_files - List all workspace files
• scratchpad_delete_file - Delete file from workspace

Local Development

Prerequisites

• Python 3.11+
• MongoDB Atlas cluster (ttg-workspaces)

Setup

# Create virtual environment
python -m venv venv
.\venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Copy and configure environment
copy .env.template .env
# Edit .env with your MongoDB URI and API key

Run Locally

cd C:\Users\Adam\Desktop\ttgeco\scratchpad-mcp
.\venv\Scripts\activate
python server.py

Server runs on http://localhost:8001/mcp

Test Without Database

The server runs in demo/stateless mode if MONGODB_URI is not set. Useful for UI testing.

Deployment (Render)

1. Push to GitHub

git add .
git commit -m "Add MongoDB persistence and file management"
git push origin main

2. Configure Render Environment Variables

In Render dashboard, add these environment variables:

Do NOT set PORT - Render provides it automatically.

3. Verify Deployment

After deploy, test the /mcp endpoint:

curl -X POST https://scratchpad-mcp-18ab.onrender.com/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN"

LibreChat Configuration

librechat.yaml

mcpServers:
  scratchpad:
    type: streamable-http
    url: "https://scratchpad-mcp-18ab.onrender.com/mcp"
    headers:
      Authorization: "Bearer ${SCRATCHPAD_MCP_TOKEN}"
      X-User-ID: "{{LIBRECHAT_USER_ID}}"
    timeout: 60000
    initTimeout: 30000
    serverInstructions: true

LibreChat .env

SCRATCHPAD_MCP_TOKEN=your-token-here

Database Schema

Collections

workspaces

{
  "_id": "ObjectId",
  "user_id": "string",
  "conversation_id": "string (optional)",
  "task": "string",
  "status": "idle|active|complete",
  "progress": {"current": 0, "total": 10},
  "working_on": "string",
  "created_at": "datetime",
  "updated_at": "datetime"
}

files

{
  "_id": "ObjectId",
  "user_id": "string",
  "workspace_id": "ObjectId",
  "name": "string",
  "path": "string",
  "type": "file|folder",
  "content": "string",
  "updated": true,
  "created_at": "datetime",
  "updated_at": "datetime"
}

activity_logs

{
  "_id": "ObjectId",
  "user_id": "string",
  "workspace_id": "ObjectId",
  "action": "string",
  "icon": "write|read|complete|delete",
  "timestamp": "datetime"
}

Security

• Bearer token authentication via MCP_API_KEYS
• User isolation via X-User-ID header (provided by LibreChat)
• All database queries scoped by user_id
• Input validation on file paths and content

Troubleshooting

"No HTTP request context available"

Tool called outside of request context. Ensure using FastMCP 0.5.0+.

"X-User-ID header required"

LibreChat not sending user ID. Check librechat.yaml headers config.

"MONGODB_URI environment variable required"

Set MONGODB_URI in Render dashboard or local .env.

Connection timeout

Check MongoDB Atlas network access - ensure Render IP is whitelisted or use 0.0.0.0/0 for all access.