MCP Integration

Hister exposes a Model Context Protocol (MCP) endpoint that lets AI assistants search your personal index directly. Once connected, the assistant can call a search tool to retrieve relevant pages from your browsing history and local files as part of any conversation.

Endpoint

POST /mcp

The endpoint follows the MCP Streamable HTTP transport. Every interaction is a POST request with a JSON-RPC 2.0 body; the server responds with a JSON object.

Authentication

The default Hister configuration does not require authentication. Authentication required only if the server requires an access_token or if it is configured as a multi-user server. The MCP endpoint uses the same authentication as the rest of the Hister API.

Static access token

Pass the value of app.access_token from your config file:

Authorization: Bearer <your-access-token>

Alternatively, use the X-Access-Token header with the same value.

Multi-user mode

Generate a personal token on the profile page (/profile) or via:

hister update-user <username> --regen-token

Then pass it the same way:

Authorization: Bearer <your-user-token>

Origin header

All requests from external clients must include:

Origin: hister://

Without this header the server’s CSRF protection will reject the request.

Available Tools

search

Search your personal browsing history and indexed documents.

Argument	Type	Required	Default	Description
query	string	yes		Search query (see Query Language)
limit	integer	no	10	Maximum results to return (max 50)
semantic	boolean	no	false	Enable AI semantic search alongside keyword matching
fields	array of string	no	[]	Extra fields to include in each result (see below)

By default the response includes title, URL, date added, and a short text snippet per result. Pass fields to include additional data:

Field value	Description
text	Full stored article text instead of a short snippet
html	Raw HTML
language	Detected language code (e.g. en, de)
label	User-defined label
domain	Domain name
score	Relevance score
type	Document type: web or local

Example: to summarize articles on a topic without re-fetching any URLs:

{ "query": "kubernetes networking", "limit": 5, "fields": ["text"] }

Client Configuration

Claude Desktop

Add a hister entry to your Claude Desktop configuration file.

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

{
  "mcpServers": {
    "hister": {
      "url": "http://127.0.0.1:4433/mcp",
      "headers": {
        "Authorization": "Bearer <your-access-token>",
        "Origin": "hister://"
      }
    }
  }
}

Restart Claude Desktop after saving the file. The search tool will appear in the tools panel when starting a new conversation.

Cursor

Open Settings and locate the MCP servers section, or edit ~/.cursor/mcp.json directly:

{
  "mcpServers": {
    "hister": {
      "url": "http://127.0.0.1:4433/mcp",
      "headers": {
        "Authorization": "Bearer <your-access-token>",
        "Origin": "hister://"
      }
    }
  }
}

Remote or self-hosted server

Replace http://127.0.0.1:4433 with your server’s base_url. If you run Hister behind a reverse proxy under a subpath (e.g. https://example.com/hister), the endpoint is https://example.com/hister/mcp.

Manual Testing with curl

You can verify the endpoint is working before configuring any client.

Authorization header is only required if any kind of authentication is enabled in Hister’s config.

Handshake:

curl -s -X POST http://127.0.0.1:4433/mcp 
  -H "Content-Type: application/json" 
  -H "Authorization: Bearer <your-access-token>" 
  -H "Origin: hister://" 
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"curl","version":"0"}}}'

List tools:

curl -s -X POST http://127.0.0.1:4433/mcp 
  -H "Content-Type: application/json" 
  -H "Authorization: Bearer <your-access-token>" 
  -H "Origin: hister://" 
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

Search:

curl -s -X POST http://127.0.0.1:4433/mcp 
  -H "Content-Type: application/json" 
  -H "Authorization: Bearer <your-access-token>" 
  -H "Origin: hister://" 
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"search","arguments":{"query":"python async","limit":5}}}'

Search with full text (no re-fetching):

curl -s -X POST http://127.0.0.1:4433/mcp 
  -H "Content-Type: application/json" 
  -H "Authorization: Bearer <your-access-token>" 
  -H "Origin: hister://" 
  -d '{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"search","arguments":{"query":"python async","limit":5,"fields":["text","language"]}}}'

Example Interaction

Once connected, you can ask the assistant things like:

“Search my history for anything about Rust error handling.”

The assistant calls the search tool with query: "rust error handling" and includes the results in its response, citing the specific pages you previously read.

Semantic search can be enabled per query by passing "semantic": true in the tool arguments. This requires semantic search to be configured on the server.

Protocol Details

The endpoint implements MCP specification version 2024-11-05 with the following methods:

Method	Description
initialize	Capability negotiation; required before any other call
ping	Liveness check
tools/list	Returns the list of available tools and their input schemas
tools/call	Executes a tool by name with the provided arguments
notifications/*	Acknowledged silently (202 response, no body)