> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bookmarkjar.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP (Model Context Protocol)

> Learn how to use MCP (Model Context Protocol) to find, insert or follow-up on bookmarks

## 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

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

## Quickstart (HTTP)

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

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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):

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "name": "bookmarks.insert",
  "arguments": { "urls": ["https://example.com/a", "https://example.com/b"] }
}
```

## JSON‑RPC Shapes

* `initialize` request:

```json theme={null}
{ "jsonrpc": "2.0", "id": 1, "method": "initialize", "params": { "client": { "name": "my-ide" } } }
```

* `tools/list` request:

```json theme={null}
{ "jsonrpc": "2.0", "id": 2, "method": "tools/list" }
```

* `tools/call` request (generic):

```json theme={null}
{ "jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": { "name": "bookmarks.search", "arguments": { } } }
```

Success envelope:

```json theme={null}
{ "jsonrpc": "2.0", "id": 3, "result": { } }
```

Error envelope:

```json theme={null}
{ "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.