MCP (Model Context Protocol)

Overview

The Bookmarkjar ® MCP server exposes your bookmarks as tools that any MCP‑capable client can call.

Endpoint: POST /api/tools/mcp (JSON‑RPC 2.0 over HTTP)
Tools: bookmarks.search, bookmarks.insert
Auth: session cookies (same‑origin) or x-api-key header

Use an API key for editor/HTTP clients. Create one in Dashboard → Profile → API Keys. Include it as x-api-key: YOUR_API_KEY.

Quickstart (HTTP)

All requests go to https://bookmarkjar.com/api/tools/mcp.

curl -X POST "https://bookmarkjar.com/api/tools/mcp" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": { "client": { "name": "curl" } }
  }'

List available tools:

curl -X POST "https://bookmarkjar.com/api/tools/mcp" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/list"
  }'

Call search:

curl -X POST "https://bookmarkjar.com/api/tools/mcp" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "bookmarks.search",
      "arguments": { "search": "drizzle postgres", "limit": 5, "tags": ["db"] }
    }
  }'

Call insert:

curl -X POST "https://bookmarkjar.com/api/tools/mcp" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "jsonrpc": "2.0",
    "id": 4,
    "method": "tools/call",
    "params": {
      "name": "bookmarks.insert",
      "arguments": { "urls": [
        "https://vercel.com/blog/vercel-ai-sdk",
        "https://drizzle.team/docs/orm"
      ] }
    }
  }'

Responses follow JSON‑RPC 2.0. Tool results are returned as result.content[] items with type: "text" and a JSON string payload.

Authentication

API Key: add x-api-key: YOUR_API_KEY header. Keys inherit your user/org permissions.
Session: browser requests on the same origin can rely on cookies (logged‑in session).
Common errors: 401 (missing/invalid auth), 400 (invalid JSON‑RPC or params).

IDE Setup

Claude Code (VS Code)

Add the MCP server via Settings (JSON):

{
  "claude.mcpServers": {
    "bookmarkjar": {
      "type": "http",
      "url": "https://bookmarkjar.com/api/tools/mcp",
      "headers": { "x-api-key": "YOUR_API_KEY" }
    }
  }
}

Reload VS Code. In Claude panel, use tools bookmarks.search or bookmarks.insert in chats.

Cursor

Open Settings (JSON) and add an MCP server entry. Cursor supports HTTP MCP servers similarly:

{
  "mcpServers": {
    "bookmarkjar": {
      "type": "http",
      "url": "https://bookmarkjar.com/api/tools/mcp",
      "headers": { "x-api-key": "YOUR_API_KEY" }
    }
  }
}

Restart Cursor for changes to apply. Use the MCP tool picker to call Bookmarkjar tools.

Window (Windsurf/Window IDEs)

Most MCP‑aware editors accept a similar mcpServers JSON block. Add an HTTP server with headers:

{
  "mcpServers": {
    "bookmarkjar": {
      "type": "http",
      "url": "https://bookmarkjar.com/api/tools/mcp",
      "headers": { "x-api-key": "YOUR_API_KEY" }
    }
  }
}

If your IDE has a UI for MCP, choose “Add HTTP server” and paste the URL and header.

Tools Reference

bookmarks.search

Purpose: full‑text and filtered search across your bookmarks.
Arguments:
- search (string): keywords or phrase. Optional.
- tags (string[] | string): tags to filter. Optional.
- domain (string): limit to a domain. Optional.
- type (string): one of link | image | color | text. Optional.
- visibility (string): private | organization | public. Optional.
- page (number): page index, default 1.
- limit (number): page size, default 5.

Example tool call params:

{
  "name": "bookmarks.search",
  "arguments": { "search": "agents", "tags": ["ai", "infra"], "limit": 5 }
}

bookmarks.insert

Purpose: create bookmarks by URL.
Arguments:
- urls (string | string[]): one or more URLs. Required.

Example tool call params:

{
  "name": "bookmarks.insert",
  "arguments": { "urls": ["https://example.com/a", "https://example.com/b"] }
}

JSON‑RPC Shapes

initialize request:

{ "jsonrpc": "2.0", "id": 1, "method": "initialize", "params": { "client": { "name": "my-ide" } } }

tools/list request:

{ "jsonrpc": "2.0", "id": 2, "method": "tools/list" }

tools/call request (generic):

{ "jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": { "name": "bookmarks.search", "arguments": { } } }

Success envelope:

{ "jsonrpc": "2.0", "id": 3, "result": { } }

Error envelope:

{ "jsonrpc": "2.0", "id": 3, "error": { "code": -32602, "message": "Invalid params", "data": "...zod error..." } }

Troubleshooting

401 Unauthorized: missing/invalid x-api-key or no active session.
400 Invalid Request/Params: ensure JSON‑RPC shape and tool arguments match examples.
Unknown tool/method: use tools/list to verify names.

That’s it — once added to your editor, ask the assistant to “search my bookmarks for X” or “insert this URL” and it will call the MCP tools.

Getting started

Bookmarks

Advanced Topics

More

Overview

Quickstart (HTTP)

Authentication

IDE Setup

Claude Code (VS Code)

Cursor

Window (Windsurf/Window IDEs)

Tools Reference

bookmarks.search

bookmarks.insert

JSON‑RPC Shapes

Troubleshooting

​Overview

​Quickstart (HTTP)

​Authentication

​IDE Setup

​Claude Code (VS Code)

​Cursor

​Window (Windsurf/Window IDEs)

​Tools Reference

​bookmarks.search

​bookmarks.insert

​JSON‑RPC Shapes

​Troubleshooting

Overview

Quickstart (HTTP)

Authentication

IDE Setup

Claude Code (VS Code)

Cursor

Window (Windsurf/Window IDEs)

Tools Reference

bookmarks.search

bookmarks.insert

JSON‑RPC Shapes

Troubleshooting