# Hister MCP Integration: Enabling AI Assistant Features Through Model Context Protocol

> Learn how Hister integrates with Model Context Protocol MCP to enable AI assistant features. Discover its JSON-RPC 2.0 endpoint and secure tool dispatching.

- Repository: [Adam Tauber/hister](https://github.com/asciimoo/hister)
- Tags: how-to-guide
- Published: 2026-09-01

---

**Hister integrates with the Model Context Protocol (MCP) by exposing a JSON-RPC 2.0 endpoint at `/mcp` that dispatches AI assistant requests to specialized tools—`search`, `get_preview`, and `get_history`—while treating all external data as untrusted content to prevent injection attacks.**

The `asciimoo/hister` repository implements the Model Context Protocol to transform its personal search engine into an AI-accessible knowledge provider. By following the MCP specification, Hister allows compatible AI assistants to query indexed documents, generate page previews, and retrieve browsing history through a standardized interface. This integration centers on the [`server/mcp.go`](https://github.com/asciimoo/hister/blob/main/server/mcp.go) implementation, which handles protocol compliance and secure data serialization.

## MCP Endpoint Registration in [`server/api.go`](https://github.com/asciimoo/hister/blob/main/server/api.go)

The integration begins in [`server/api.go`](https://github.com/asciimoo/hister/blob/main/server/api.go) at lines 1053-1065, where the HTTP router registers the `/mcp` route. Hister registers two handlers for this path:

- **`serveMCPGet`** – Returns HTTP 405 *Method Not Allowed* because the implementation does not support server-initiated event streams for `GET` requests.
- **`serveMCP`** – Handles `POST` requests carrying JSON-RPC 2.0 payloads, serving as the main entry point for AI assistant interactions.

This dual-registration ensures protocol compliance while preventing invalid transport methods.

## Core MCP Request Processing Logic

The file [`server/mcp.go`](https://github.com/asciimoo/hister/blob/main/server/mcp.go) contains the full MCP implementation, beginning with a package comment explicitly stating its purpose: *"Package server MCP endpoint implements the Model Context Protocol (MCP)"*. The core dispatcher resides in `serveMCP`, which parses incoming JSON-RPC requests and routes them via a **switch statement** on `request.Method` (lines 101-108).

The dispatcher calls specialized tool handlers:
- `mcpToolSearch` for full-text queries
- `mcpToolGetPreview` for URL metadata extraction
- `mcpToolGetHistory` for browsing history retrieval

Each handler returns a standardized result structure that the MCP specification requires.

## Available MCP Tools for AI Assistants

Hister exposes three primary tools through its MCP interface, defined between lines 386-799 in [`server/mcp.go`](https://github.com/asciimoo/hister/blob/main/server/mcp.go):

### Search Tool (`search`)

Executes a full-text search against Hister's indexed documents. The tool returns results as an array of **indexed_document** records, each wrapped in the MCP structured result format. AI assistants can query the entire index without direct database access.

### Get Preview Tool (`get_preview`)

Retrieves a specified URL, extracts the page title and description, and generates a safe HTML excerpt. The tool returns the data as an **indexed_document** record, allowing AI assistants to summarize web content before presenting it to users.

### Get History Tool (`get_history`)

Supports two operational modes via the `params.mode` parameter:
- **`opened`** – Returns **opened_history** records containing URLs the user has recently browsed.
- **`indexed`** – Returns **indexed_history** records representing documents stored in the search index.

Both modes respect user privacy boundaries while providing contextual data to assistants.

## Security Model and Untrusted Content Handling

Security is enforced through the **untrusted records** pattern. In [`server/mcp.go`](https://github.com/asciimoo/hister/blob/main/server/mcp.go) at lines 554-620, the `newMCPStructuredResult` constructor builds a `mcpStructuredResult` containing an array of untrusted records created via `newMCPUntrustedRecord`. 

All content originating from the web or user-provided data is tagged with its source type. The `normalizeUntrusted` function (lines 567-681) performs sanitization by stripping invisible control characters to prevent injection attacks. This ensures AI assistants receive clearly labeled, sanitized data with explicit trust boundaries.

## Practical MCP Usage Examples

### Performing a Search

```bash
curl -X POST https://hister.example.com/mcp \
  -H "Content-Type: application/json" \
  -d '{
        "jsonrpc":"2.0",
        "id":1,
        "method":"search",
        "params":{"query":"golang tutorial"}
      }'

```

The response contains a `structured_result` with an array of `untrusted_content` records.

### Requesting a Page Preview

```bash
curl -X POST https://hister.example.com/mcp \
  -H "Content-Type: application/json" \
  -d '{
        "jsonrpc":"2.0",
        "id":2,
        "method":"get_preview",
        "params":{"url":"https://golang.org/doc/"}
      }'

```

Returns an `indexed_document` with `title`, `description`, and safe HTML excerpt fields.

### Fetching Recent History

```bash
curl -X POST https://hister.example.com/mcp \
  -H "Content-Type: application/json" \
  -d '{
        "jsonrpc":"2.0",
        "id":3,
        "method":"get_history",
        "params":{"mode":"opened"}
      }'

```

Returns `opened_history` records with URLs marked as untrusted.

## MCP Testing in [`server/mcp_test.go`](https://github.com/asciimoo/hister/blob/main/server/mcp_test.go)

The [`server/mcp_test.go`](https://github.com/asciimoo/hister/blob/main/server/mcp_test.go) file contains the test suite validating the integration. Tests verify that:

- Search results are correctly normalized and marked as untrusted.
- The `get_preview` tool returns rendered HTML while preserving metadata security.
- `get_history` respects the requested mode parameter (opened vs. indexed).
- The endpoint correctly advertises the MCP protocol version defined in [`server/server.go`](https://github.com/asciimoo/hister/blob/main/server/server.go).

These tests ensure that Hister maintains protocol compliance while preserving security guarantees across AI assistant interactions.

## Summary

- Hister exposes an MCP endpoint at `/mcp` using JSON-RPC 2.0 transport, registered in [`server/api.go`](https://github.com/asciimoo/hister/blob/main/server/api.go) at lines 1053-1065.
- The core implementation in [`server/mcp.go`](https://github.com/asciimoo/hister/blob/main/server/mcp.go) dispatches requests to three tools: `search`, `get_preview`, and `get_history`.
- All external data is wrapped in **untrusted records** via `newMCPUntrustedRecord` and sanitized by `normalizeUntrusted` to prevent injection.
- The endpoint rejects `GET` requests (returning 405) because server-initiated streams are not supported.
- Comprehensive tests in [`server/mcp_test.go`](https://github.com/asciimoo/hister/blob/main/server/mcp_test.go) validate security, protocol compliance, and tool functionality.

## Frequently Asked Questions

### What is the Model Context Protocol (MCP) endpoint URL in Hister?

The MCP endpoint is available at `/mcp` on the Hister server. According to the source code in [`server/api.go`](https://github.com/asciimoo/hister/blob/main/server/api.go), this path accepts `POST` requests containing JSON-RPC 2.0 payloads and rejects `GET` requests with a 405 status code.

### Which MCP tools does Hister expose for AI assistants?

Hister exposes three primary tools: `search` for full-text indexing, `get_preview` for URL metadata extraction, and `get_history` for retrieving browsing history in either `opened` or `indexed` modes. These are implemented in [`server/mcp.go`](https://github.com/asciimoo/hister/blob/main/server/mcp.go) between lines 386-799.

### How does Hister prevent injection attacks in MCP responses?

All content retrieved from external sources is treated as untrusted. The `normalizeUntrusted` function in [`server/mcp.go`](https://github.com/asciimoo/hister/blob/main/server/mcp.go) (lines 567-681) strips invisible control characters from responses, and the `newMCPUntrustedRecord` constructor explicitly tags data with its source type, creating a clear security boundary for AI assistants.

### Why does the Hister MCP endpoint reject GET requests?

The `serveMCPGet` handler returns *Method Not Allowed* because the MCP implementation in Hister does not support server-initiated event streams. The protocol requires client-initiated `POST` requests with JSON-RPC 2.0 payloads to the `/mcp` endpoint.