Loft

Lift local document folders into a cloud-hosted MCP server. Loft syncs your files (Markdown, PDF, text) to a Turso database with vector embeddings, then serves them as an MCP endpoint that Claude, Cursor, and other AI tools can search.

Local files → CLI (chunk + embed) → Turso DB → Vercel MCP server → Claude / Cursor

Setup

Follow these steps in order. The whole process takes about 10 minutes.

Step 1: Install prerequisites

You need the following installed on your machine:

• Bun — runtime and package manager

  curl -fsSL https://bun.sh/install | bash

• Poppler — for PDF text extraction (skip if you don't need PDF support)

  brew install poppler

Step 2: Create a Turso database

1. Sign up at turso.tech (free tier: 9 GB storage, 500 databases)
2. Install the Turso CLI:

   brew install tursodatabase/tap/turso
   turso auth login

3. Create a database:

   turso db create loft

4. Get your database URL:

   turso db show loft --url

   This will print something like libsql://loft-yourname.turso.io — save this.
5. Create an auth token:

   turso db tokens create loft

   Save the token that's printed.

Step 3: Get an OpenAI API key

1. Go to platform.openai.com/api-keys
2. Create a new API key
3. Save the key (starts with sk-)

This is used for generating text embeddings (text-embedding-3-small). Cost is ~$0.02 per 1M tokens.

Step 4: (Optional) Get an Anthropic API key

Only needed if you want Vision OCR for images embedded in PDFs.

1. Go to console.anthropic.com/settings/keys
2. Create a new API key
3. Save the key (starts with sk-ant-)

Step 5: Clone and install

git clone <repo-url> && cd loft
bun install

# Link the CLI globally so `loft` is available everywhere
cd packages/cli && bun link

Step 6: Run setup

This saves your credentials to ~/.loft/config.json and creates the database tables.

loft setup

You'll be prompted for:

• Turso database URL — the libsql://... URL from Step 2
• Turso auth token — the token from Step 2
• OpenAI API key — from Step 3
• Anthropic API key — from Step 4 (press Enter to skip)

Step 7: Create a project and sync

# Create a project pointing at your docs folder(s)
loft init my-project ./docs

# Sync files to the cloud (chunks + embeds)
loft sync my-project

# Generate an API key for accessing via MCP
loft key my-project

Step 8: Deploy the MCP server to Vercel

1. Push this repo to your own GitHub account

2. Go to vercel.com/new and import the repo

3. Set the Root Directory to packages/server

4. Add these environment variables in the Vercel dashboard:

   Variable	Value
   TURSO_URL	libsql://loft-yourname.turso.io (from Step 2)
   TURSO_AUTH_TOKEN	Your Turso auth token (from Step 2)
   OPENAI_API_KEY	Your OpenAI API key (from Step 3)

5. Deploy. Your MCP endpoint will be at https://<your-app>.vercel.app/mcp.

Step 9: Save your Vercel URL locally

So that loft key can generate complete connection strings:

# Edit ~/.loft/config.json and add:
# "vercelUrl": "your-app.vercel.app"

Step 10: Connect to Claude

Claude.ai / Claude Mobile

Add as an MCP server URL directly:

https://your-app.vercel.app/mcp?key=lft_xxx

Claude Desktop / Cursor

Add to your config file (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "my-project": {
      "command": "npx",
      "args": ["-y", "loft-proxy"],
      "env": {
        "LOFT_URL": "https://your-app.vercel.app/mcp?key=lft_xxx"
      }
    }
  }
}

The loft key command prints both connection formats when you generate a key.

---

CLI Reference

Command	Description
loft setup	Configure Turso + OpenAI credentials and run migrations
loft init <name> <folder> [folders...]	Create a project linked to local folders
loft init <name> <folder> --add	Add folders to an existing project
loft sync <name>	Sync files to the cloud (incremental, hash-based)
loft status <name>	Show project stats and sync status
loft projects	List all projects
loft key <name> [--name label]	Generate an API key
loft keys <name>	List API keys for a project
loft delete <name>	Permanently delete a project and all its data

MCP Tools

The server exposes 5 tools to AI clients:

Tool	Description
retrieve	Direct lookup for specific documents or passages
discover	Explore the knowledge base with hybrid search (vector + BM25)
gather	Deep research using multiple search strategies
stats	Get document and chunk counts
expand_document	Get full text of a document by ID

Supported File Types

• Markdown (.md)
• PDF (.pdf) — requires Poppler for text extraction
• Plain text (.txt)

Cost

Loft runs almost entirely on free tiers:

• Turso: 9 GB storage, 500 databases (free)
• Vercel: serverless functions (free hobby tier)
• OpenAI: ~$0.02 per 1M tokens for embeddings (text-embedding-3-small)