MCP Server

Purl ships a remote Model Context Protocol server so AI clients like Claude, Cursor, and VS Code can search and save to your knowledge base directly. It uses the Streamable HTTP transport and the same API keys as the REST API.

Endpoint: https://purl.nublson.com/api/mcp

Looking for plain HTTP instead? See the REST API reference.

Overview

MCP lets an AI client call tools on your behalf. Once connected, your assistant can run semantic search over everything you've saved, save new links, list recent items, and fetch a single item — without leaving the chat. All calls are scoped to the account that owns the API key.

Getting Started

Generate an API key in Settings → Integrations, then pass it as a Bearer token in the Authorization header. Your client must support custom headers (most do).

http

Authorization: Bearer purl_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Keep your key secret — it grants full access to your saved content. A request with a missing or invalid key returns 401 Unauthorized.

App Setup

Point any MCP client at https://purl.nublson.com/api/mcp and add your Bearer token. Replace purl_… with your key.

Add to Cursor

Buttons use a placeholder key. After installing, replace purl_YOUR_KEY with a key from Settings → Integrations. “Add to Claude Code” and “Add to Codex” copy the install command to your clipboard.

Claude Code

bash

claude mcp add purl --transport http https://purl.nublson.com/api/mcp \
  --header "Authorization: Bearer purl_..."

Claude Desktop

Settings → Connectors → Add custom connector. Enter the URL https://purl.nublson.com/api/mcp and add an Authorization header with your Bearer token.

Cursor

Add to ~/.cursor/mcp.json:

json

{
  "mcpServers": {
    "purl": {
      "url": "https://purl.nublson.com/api/mcp",
      "headers": { "Authorization": "Bearer purl_..." }
    }
  }
}

VS Code / Copilot

Add to .vscode/mcp.json:

json

{
  "servers": {
    "purl": {
      "type": "http",
      "url": "https://purl.nublson.com/api/mcp",
      "headers": { "Authorization": "Bearer purl_..." }
    }
  }
}

Codex

bash

codex mcp add purl --url https://purl.nublson.com/api/mcp

Add your Bearer token via Codex's MCP header configuration.

MCP Inspector (testing)

bash

npx @modelcontextprotocol/inspector

Connect via Streamable HTTP to https://purl.nublson.com/api/mcp with an Authorization header to list and try the tools.

Available Tools

search_content

Semantic search across your saved content. Returns matching items with the relevant text. Requires an active Pro plan (or trial).

Parameter	Type	Description
query*	string	The search query describing the topic.
contentType	WEB \| YOUTUBE \| PDF \| AUDIO	Filter by content type.
dateFrom	string	ISO 8601 date for the start of the range.
dateTo	string	ISO 8601 date for the end of the range.
limit	number	Maximum items to return (1–20, default 10).

save_link

Save a URL to your library. Purl ingests the content (web, PDF, YouTube, audio) asynchronously after saving.

Parameter	Type	Description
url*	string	The URL to save.

list_saved_items

List your saved items (metadata only, newest first) with cursor pagination. The response includes a nextCursor for the following page.

Parameter	Type	Description
contentType	WEB \| YOUTUBE \| PDF \| AUDIO	Filter by content type.
limit	number	Maximum items to return (1–100, default 50).
cursor	string	Pagination cursor (ISO date) from a previous response.

get_link

Fetch a single saved item by its id.

Parameter	Type	Description
id*	string	The link id.