Second Brain Vault

A remote MCP server on Cloudflare Workers that gives Claude (or any MCP client) read/write access to a personal file vault backed by Cloudflare R2.

Authentication is handled via GitHub OAuth, so Claude.ai connects natively without workarounds.

This server is part of Token Brain, a personal knowledge and agent infrastructure built around Claude.

Features

• File operations: read, write, delete text files (markdown, JSON, YAML, CSV, code)
• Browse: list files with metadata, search by filename, display the directory tree
• Binary support: generate presigned URLs for direct upload/download of any file type
• Health check: alive tool to verify the server and OAuth are operational
• Single-owner access: GitHub OAuth scope guard restricts access to one authorized user

Tools

Tool	Description
alive	Health check — confirms the server is running and authentication is valid
list_files	List files in the vault with size and modification date
tree	Display the vault's directory structure
search_files	Search files by name (case-insensitive)
read_file	Read the content of a text file
write_file	Create or overwrite a text file
delete_file	Delete a file (requires explicit confirmation)
get_upload_url	Generate a presigned URL for uploading a file (60s TTL)
get_download_url	Generate a presigned URL for downloading a file (60s TTL)

Prerequisites

• Node.js (v18+)
• A Cloudflare account (free plan works)
• A GitHub OAuth App for authentication

Quick Start

# Clone and install
git clone https://github.com/your-username/second-brain-vault.git
cd second-brain-vault
npm install

# Configure
cp .env.example .env
# Edit .env with your values (see Configuration below)

# Create Cloudflare resources
wrangler kv namespace create OAUTH_KV
# Copy the returned ID into wrangler.jsonc

wrangler r2 bucket create mcp-vault
# (or use your own bucket name — update wrangler.jsonc accordingly)

# Set production secrets
wrangler secret put GITHUB_CLIENT_ID
wrangler secret put GITHUB_CLIENT_SECRET
wrangler secret put COOKIE_ENCRYPTION_KEY
wrangler secret put R2_ACCESS_KEY_ID
wrangler secret put R2_SECRET_ACCESS_KEY
wrangler secret put CF_ACCOUNT_ID
wrangler secret put ALLOWED_GITHUB_ID
wrangler secret put ALLOWED_GITHUB_LOGIN

# Deploy
wrangler deploy

Your MCP endpoint will be available at https://your-worker.your-subdomain.workers.dev/mcp.

Configuration

Environment Variables

Variable	Description
GITHUB_CLIENT_ID	GitHub OAuth App client ID
GITHUB_CLIENT_SECRET	GitHub OAuth App client secret
COOKIE_ENCRYPTION_KEY	Random 64-char hex string for cookie encryption
R2_ACCESS_KEY_ID	Cloudflare R2 API key ID
R2_SECRET_ACCESS_KEY	Cloudflare R2 API secret key
CF_ACCOUNT_ID	Your Cloudflare account ID
ALLOWED_GITHUB_ID	Your GitHub user ID (integer)
ALLOWED_GITHUB_LOGIN	Your GitHub username

GitHub OAuth App Setup

1. Go to GitHub Developer Settings
2. Create a new OAuth App
3. Set the Authorization callback URL to https://your-worker.your-subdomain.workers.dev/callback
4. Copy the Client ID and Client Secret into your secrets

Connecting to Claude.ai

1. In Claude.ai, go to Settings > Integrations
2. Add a custom MCP server
3. Enter your Worker URL: https://your-worker.your-subdomain.workers.dev/mcp
4. Claude will redirect you to GitHub for authentication
5. Once authorized, the vault tools appear in your conversation

Architecture

The server runs on Cloudflare Workers and uses:

• R2 for file storage (S3-compatible object storage)
• KV for OAuth session management
• workers-oauth-provider for the OAuth 2.1 flow
• MCP SDK (@modelcontextprotocol/sdk) for tool registration and transport

For detailed architecture documentation, see ARCHITECTURE.md.

For the OAuth implementation guide, see GUIDE-MCP-WORKER-OAUTH.md.

Deployment

See DEPLOY.md for step-by-step deployment instructions.

License

MIT — see LICENSE.