Lettuce Docs Tags Graph

Your first agent connection

#docs#getting-started#agents
~6 min read

Your first agent connection

This walks you through pairing Claude Desktop, Claude Code, or any other MCP client with your Lettuce vault in under a minute.

What you’ll have at the end

1. Start the server

In Lettuce, the server runs whenever the app is open — see its status under Settings → Agents → “Agent API server”.

Or from the CLI:

lettuce serve

You’ll see:

Lettuce serving /Users/you/Notes
  REST: http://127.0.0.1:51234/api/v1
  API key: ephemeral (not saved) — re-run with --show-key to print it
  schedules: polling every 60s (headless)

The API key is hidden by default (so it can’t leak into a logfile) — re-run with --show-key to print it, or copy it from the app (Settings → Agents → “Connect an agent…”). The MCP endpoint is at POST /mcp on the same port. By default the server binds to localhost only — nothing outside your machine can reach it.

The fast path: open Settings → Agents → “Connect an agent…”. It’s a wizard: pick your client (Claude Desktop, Claude Code, OpenAI Codex, or Gemini CLI), pick or mint a scoped key, and copy a ready-made config block. It also shows the raw connection details (MCP endpoint, REST API base, bearer token) for any other client, plus a This Mac / Another machine (over Tailscale) toggle that fills in the right endpoint (see below). If you use the wizard, you can skip steps 2 and 3.

2. Get a token

In Settings → Agents → “API keys”, click New API key. Give it a label (e.g. “Claude Desktop”) and a scope:

Or from the CLI:

lettuce keys add --label "Claude Desktop" --scope read

The token is a URL-safe base64 string of 32 random bytes (e.g. kJ8x2Vn-Qe7r...) — there’s no prefix. Copy it immediately; it’s only shown once. It’s stored in your Keychain and compared in constant time — the rest of the system never sees the raw string again.

3. Point your agent at Lettuce

Lettuce’s MCP server is a plain HTTP/JSON-RPC endpoint at http://127.0.0.1:51234/mcp, authenticated with Authorization: Bearer <your-token>. Below are the four most common clients. Swap in the token you copied above. (Clients that can’t talk to a loopback http:// endpoint directly use the mcp-remote bridge, shown for Claude Desktop — that pattern works for any of them as a fallback.)

Claude Desktop

Claude Desktop launches MCP servers over stdio, so it reaches Lettuce through the mcp-remote bridge (run on demand via npx; needs Node). Edit ~/Library/Application Support/Claude/claude_desktop_config.json (create it if it doesn’t exist):

{
  "mcpServers": {
    "lettuce": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://127.0.0.1:51234/mcp",
        "--allow-http",
        "--header",
        "Authorization:Bearer ${LETTUCE_TOKEN}"
      ],
      "env": { "LETTUCE_TOKEN": "kJ8x2Vn-Qe7rxxxxxxxxxxxx" }
    }
  }
}

--allow-http is required for the loopback http:// endpoint; the token goes in env (and the header is written Authorization:Bearer … with no space after the colon) to dodge a known config-escaping bug. Restart Claude Desktop — you should see Lettuce’s tools available in the chat UI.

Claude Code

Claude Code speaks HTTP MCP natively — no bridge needed:

claude mcp add --transport http lettuce http://127.0.0.1:51234/mcp \
  --header "Authorization: Bearer kJ8x2Vn-Qe7rxxxxxxxxxxxx"

In your next session, /mcp should show lettuce connected.

OpenAI Codex CLI

Add a server to ~/.codex/config.toml:

[mcp_servers.lettuce]
url = "http://127.0.0.1:51234/mcp"
http_headers = { Authorization = "Bearer kJ8x2Vn-Qe7rxxxxxxxxxxxx" }

Then run /mcp inside a Codex session to confirm the tools loaded. (If your Codex build can’t reach the loopback endpoint directly, use the mcp-remote bridge instead — set command = "npx" with the same args array shown for Claude Desktop.)

Gemini CLI

Add a server to ~/.gemini/settings.json (or run gemini mcp add lettuce http://127.0.0.1:51234/mcp -H "Authorization: Bearer <token>"):

{
  "mcpServers": {
    "lettuce": {
      "httpUrl": "http://127.0.0.1:51234/mcp",
      "headers": { "Authorization": "Bearer kJ8x2Vn-Qe7rxxxxxxxxxxxx" }
    }
  }
}

Connecting an agent on another machine (Tailscale)

Lettuce’s server binds to localhost only, so by default an agent has to run on the same Mac. To let an agent on a different computer (or your phone) reach it, expose the server over Tailscale — a free, private network that links your own devices, and nothing else.

With Tailscale running on your Mac:

tailscale serve --bg --https=8443 127.0.0.1:51234

This proxies the local server onto your private tailnet at https://<your-mac>.ts.net:8443/mcp. Point your agent at that URL instead of the 127.0.0.1 one — everything else (the Authorization: Bearer <token> header, the scopes, the propose-only behaviour) is identical.

The Connect an agent… wizard has a This Mac / Another machine (over Tailscale) toggle that fills in the right URL automatically, so you don’t have to hand-edit the config. Nothing is exposed to the public internet — only the devices signed into your own Tailscale account can reach it.

4. Try it

Once connected, ask your agent something only your vault can answer:

Find all my notes tagged #project and show me the ones touched in the last week.

It’ll use notes_by_tag (or search) and read_note to answer — reading your actual notes through Lettuce’s tools, not guessing.

5. (Optional) Drop an AGENTS.md into your vault

This is the single highest-leverage thing you can do for agent quality. Lettuce ships a scaffold:

lettuce agents init

It writes AGENTS.md to your vault root, tailored to your vault’s actual folders and tags, with vault conventions (where to put new notes, your tag taxonomy, how to format dates, when to ask vs. just do it). Agents pick it up on connection via get_vault_info. (If you’re scaffolding a full LLM wiki, lettuce wiki init --agents writes the same file alongside the rest of the wiki layout.)

Test the connection

In Claude:

List the first 5 notes in my vault.

If you see a tool call to list_notes followed by 5 notes, you’re set. If you get a permission error, double-check the token in your config file matches what you copied.

Next steps