# Lever MCP Server

An MCP (Model Context Protocol) server for [Lever](https://lever.ai) — a financial planning app. Connects Claude to a user's financial plan via a token in the server URL.

## Prerequisites

- Node.js 20+
- A Supabase project with the Lever schema
- `cloudflared` installed (see below)

## Setup

**1. Clone and install**

```bash
git clone <repo-url>
cd lever-mcp
npm install
```

**2. Configure environment**

```bash
cp .env.example .env
```

Edit `.env` and fill in your values:

```
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_ANON_KEY=your-anon-key-here
PORT=3000
```

> Use the **anon/public** key from Supabase (Settings → API), not the service_role key.

**3. Install cloudflared**

```bash
curl -fsSL https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64 \
  -o ~/cloudflared && chmod +x ~/cloudflared
```

> To make it available system-wide: `sudo mv ~/cloudflared /usr/local/bin/cloudflared`
> If you only moved it to `~/cloudflared`, update the `tunnel` script in `package.json` to use `~/cloudflared` instead of `cloudflared`.

## Running

Open two terminals in the project directory.

**Terminal 1 — start the MCP server:**

```bash
npm start
```

**Terminal 2 — start the Cloudflare tunnel:**

```bash
npm run tunnel
```

The tunnel output will include a public URL like:

```
https://some-words-here.trycloudflare.com
```

> This URL changes every time you restart the tunnel. For a permanent URL, set up a [named Cloudflare Tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/) with a free Cloudflare account.

## Connecting to Claude

Once both are running, add the MCP server to Claude using your tunnel URL and the user's UUID token:

```
https://some-words-here.trycloudflare.com/mcp?token=<user-uuid>
```

The token is the user's `id` from either the `anonymous_users` or `auth.users` table in Supabase.

**In Claude.ai** (Settings → Connectors → Add):
- Type: Remote MCP
- URL: the full URL above with your token

## Available Tools

| Tool | Description |
|---|---|
| `get_plan` | Fetches the user's most recent financial plan |
| `get_event_schema` | Lists supported event types or returns the parameter spec for a specific type |
| `update_plan` | Adds, removes, or updates an event in the user's plan |

### update_plan operations

```
op: "add_event"     — add a new event (use get_event_schema first to get parameter spec)
op: "remove_event"  — remove an event by its id
op: "update_field"  — change a single parameter value on an existing event
```