MCP Bookmark Server: How Burn 451 Connects Your Saves to Claude

There is exactly one dedicated MCP bookmark server on npm right now: burn-mcp-server. Version 2.1.0, 396 weekly downloads as of May 2026. If you searched "mcp bookmark server" or "mcp server for bookmarks," this is the page you were looking for.

This post covers three things: what an MCP bookmark server actually does, how burn-mcp-server works under the hood (technical walkthrough — save, list, search), and how to install it in Claude Desktop or Cursor in about five minutes. There's also a build-your-own skeleton for developers who want to connect a different bookmark API to MCP.

I built Burn 451 and I built this server. I'll be specific about the trade-offs.

What is an MCP bookmark server?

The Model Context Protocol is Anthropic's open standard for connecting AI agents to external tools. It works like a self-describing API: the server publishes a manifest of available tools at connection time, and the agent reads that manifest to discover what calls it can make. Claude Desktop, Cursor, and Windsurf all speak MCP natively.

An MCP bookmark server is a process that maps your bookmark data onto that protocol. Instead of copying article URLs into a chat window, you ask Claude "what did I save last week about TypeScript?" and the agent calls search_vaulton your behalf, returns the matching vault entries, and reasons over them in context. The articles you've been reading for months become first-class data for your agent.

This is a fundamentally different architecture than a browser extension or a web app. The agent is the interface. Your bookmark history is the knowledge base. The MCP server is the bridge.

For the broader picture of how MCP fits into read-later workflows, see read-later apps with MCP: the full landscape.

Why bookmarks and MCP are the natural pairing

Most read-later apps have the same problem: content goes in, but retrieval is poor. You remember saving something about distributed systems six months ago. You can't remember the title, the author, or the source. Full-text search in the app returns ten results. You read two and give up.

An LLM is exceptionally good at this retrieval problem. Given a fuzzy natural-language query and a set of article summaries, it can surface the right item even when the query doesn't match any exact string in the title. The bottleneck is getting your bookmarks into the agent's context — which is exactly what an MCP server solves.

The second reason the pairing works: bookmarks are structured data. Each save has a URL, title, AI summary, tags, and a timestamp. That structure maps cleanly onto tool schemas, which is how MCP clients communicate intent to servers. A tool like search_vault can accept a JSON schema with { query: string, tags?: string[], limit?: number } and the agent knows exactly what to pass.

Compare this to trying to expose an unstructured reading list over MCP — no schema, no summaries, no tags. The agent has nothing to work with. The AI-native bookmark manager design that makes Burn useful in the app is the same design that makes the MCP layer useful in Claude.

How burn-mcp-server works: technical walkthrough

burn-mcp-server is a Node.js process that runs over stdio transport. It exposes 26 tools to any connected MCP client. The three most commonly used are:

• •search_vault — keyword and semantic search across your permanent Vault bookmarks.
• •list_vault / list_sparks / list_flame — list bookmarks by stage. Vault = permanent saves; Sparks = recently read (30-day); Flame = inbox about to expire. Each result includes title, URL, AI summary, tags, and save date.
• •search_vault / search_sparks — full-text search over your Vault or Sparks. Accepts a natural-language query string; the server runs it against full-text search on title + summary + tags and returns ranked matches.

Auth: token exchange and session caching

The server authenticates with a long-lived MCP token you generate in the Burn app. On first connection it exchanges this token for a short-lived Supabase session and caches both the access token and refresh token at ~/.burn/mcp-session.json(permissions: 0o600). Subsequent launches restore from disk with zero network calls. Supabase's onAuthStateChange listener writes fresh tokens back to the cache when they auto-refresh. If the cache is corrupt or the refresh fails, the server falls back to a full exchange.

This pattern matters because MCP clients restart servers frequently — every time you reopen Claude Desktop, every time Cursor refreshes its tool list. A cold auth exchange on every launch would add visible latency. The session cache keeps connection time under 100ms for returning users.

Rate limiting: 30 calls per 60-second window

The server enforces a sliding 60-second window with a 30-call cap per MCP session, held in-memory. When an agent trips the limiter, the tool returns a human-readable message — "Rate limit exceeded (30 calls/min). Retry after 12s." — instead of a raw HTTP 429. Claude Code and Cursor handle this gracefully; the agent pauses and retries automatically.

The cap exists to stay within Supabase's request budget for the free plan, not to block real usage. A typical research session — five to fifteen searches, a handful of list calls — never comes close.

Tool-first design vs resource-first

MCP supports both "tools" (callable functions with JSON schemas) and "resources" (URIs the agent can read). burn-mcp-server is tool-first because every MCP client I tested reasons better about tool schemas than URI patterns. Resources are available as welcome-mat hints (burn://vault/bookmarks, burn://vault/categories) but the main interface is tools. The full reasoning behind this decision is in the building Burn's MCP server: 3 patterns that actually work.

How to install burn-mcp-server in Claude Desktop

Prerequisites: Node.js 18+ and an active Burn 451 account. The process takes about five minutes.

Step 1: Get your MCP token. Open the Burn app → Settings → MCP Server → Generate Token. Copy the token. It starts with burn_mcp_.

Step 2: Edit your Claude Desktop config. The config file lives at:

• •macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• •Windows: %APPDATA%\Claude\claude_desktop_config.json

Add the following entry under mcpServers:

{
  "mcpServers": {
    "burn": {
      "command": "npx",
      "args": ["burn-mcp-server"],
      "env": {
        "BURN_MCP_TOKEN": "burn_mcp_your_token_here"
      }
    }
  }
}

Step 3: Restart Claude Desktop. The tools — including search_vault, list_vault, and list_sparks— will appear in the tool selector. Ask Claude "search my bookmarks for articles about Rust async" to verify the connection.

Installing in Cursor

Cursor uses an identical MCP config format. Open Cursor Settings → MCP → Add Server, or edit ~/.cursor/mcp.json directly with the same JSON block above (replace claude_desktop_config.json's mcpServers format with Cursor's — the shape is the same). Reload the MCP server list. The tools appear in Composer when you @burn or ask Cursor to search your saves.

"I tried building my own bookmark MCP and gave up — Burn already does it."

That quote is from a Hacker News comment in the MCP server showcase thread from February 2026. The commenter was an indie hacker who had wired up a Readwise Reader API key to a custom MCP server, hit the auth token refresh wall, and abandoned it after two days. The pattern is common enough to be worth addressing directly.

The hard parts of building a bookmark MCP server are not the tool definitions — those are 30 lines of TypeScript. The hard parts are: (1) auth that survives Claude Desktop restarts without prompting, (2) a rate limiter that returns agent-readable errors instead of raw HTTP codes, and (3) a tool schema that the agent can actually reason about rather than just call mechanically. burn-mcp-server has solved all three. If your bookmarks live in Burn, the server is a five-minute install.

If your bookmarks live somewhere else, the next section is for you.

Build your own: bookmark MCP server skeleton

If you have a different bookmark API and want to wrap it in MCP, here's the minimal TypeScript skeleton using the official @modelcontextprotocol/sdk:

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
import { z } from "zod"

const server = new McpServer({
  name: "my-bookmark-server",
  version: "1.0.0",
})

// Tool 1: save a URL
server.tool(
  "bookmark_save",
  "Save a URL to your bookmark collection",
  { url: z.string().url(), note: z.string().optional() },
  async ({ url, note }) => {
    // call your bookmark API here
    const result = await yourApi.save(url, note)
    return { content: [{ type: "text", text: JSON.stringify(result) }] }
  }
)

// Tool 2: list bookmarks
server.tool(
  "bookmark_list",
  "List saved bookmarks with pagination",
  { limit: z.number().default(20), offset: z.number().default(0) },
  async ({ limit, offset }) => {
    const items = await yourApi.list({ limit, offset })
    return { content: [{ type: "text", text: JSON.stringify(items) }] }
  }
)

// Tool 3: search
server.tool(
  "bookmark_search",
  "Search bookmarks by natural language query",
  { query: z.string() },
  async ({ query }) => {
    const results = await yourApi.search(query)
    return { content: [{ type: "text", text: JSON.stringify(results) }] }
  }
)

// Start server over stdio
const transport = new StdioServerTransport()
await server.connect(transport)

The critical decisions in this skeleton:

• •stdio transport, not HTTP. All current MCP clients — Claude Desktop, Cursor, Windsurf — launch servers as child processes and communicate over stdio. HTTP transport exists in the spec but no major client uses it for local tools yet.
• •Zod schemas, not raw JSON Schema. The MCP SDK accepts Zod schemas directly and converts them internally. Using Zod gives you runtime validation plus the schema inference the agent needs.
• •One responsibility per tool. Don't build a "do everything" tool with a mode parameter. Agents choose tools by name and description; three clearly-named tools outperform one polymorphic tool every time.
• •Return JSON strings, not objects. The MCP content array expects { type: "text", text: string }. Agents can parse JSON from a text response; they cannot receive a raw object.

Add auth and a rate limiter and you have a production-viable server. The auth pattern from burn-mcp-server (session cache at ~/.myapp/mcp-session.json) applies to any OAuth2 or token-based API.

For the full architecture rationale, read building Burn's MCP server: 3 patterns that actually work.

Alternatives and competing tools

As of May 2026, there is no other dedicated bookmark MCP server on npm. The alternatives are:

Generic MCP file/web servers— tools like the official MCP filesystem server can read bookmark export files (HTML, CSV, JSON). This works but requires manual export and doesn't give the agent live access to your reading queue.

Custom Readwise Reader wrapper— Readwise has a public API. You can build an MCP server around it using the skeleton above. The same is true for Raindrop.io (REST API) and Instapaper (API v1 with OAuth). None of these are published as MCP packages, so you'd be maintaining your own server.

Karakeep (self-hosted) — Karakeep has a REST API if you self-host. An MCP wrapper is theoretically possible but no one has published one. For the broader read-later app comparison, see Burn 451 vs Readwise — which read-later tool is right for you.

The gap exists because most bookmark managers haven't prioritized agent-facing infrastructure. burn-mcp-server exists because Burn was designed from the start with the assumption that your vault would eventually be queried by an AI, not just browsed by a human.

Practical examples: what Claude can do with your bookmarks

Once burn-mcp-server is connected, here are the queries that work well in practice:

• •"What did I save last month about TypeScript performance?" — Claude calls search_vault with your query, returns ranked results with summaries.
• •"Give me a summary of my recent AI/ML saves" — Claude lists your sparks, filters by tag, and synthesizes across summaries.
• •"Find articles I saved about MCP" — Claude calls search_vault, returning ranked matches with AI summaries.
• •"I'm writing a post about distributed consensus — what relevant articles do I have?" — Claude searches your vault by topic and surfaces related saves even if they don't use the exact phrase.

The last example is the most powerful and the hardest to replicate without MCP. Full-text search in a bookmark app requires you to remember the right words. An LLM with access to your summaries can match on meaning, not just string overlap.

For a dedicated guide on running an MCP server alongside a read-later app, see MCP read-later server: setup and use cases. For the broader context of how read-later apps are integrating with AI agents, see best AI bookmark manager 2026.

Frequently asked questions