Connect an AI agent to your books with MCP.

Leafhour documentation · Updated October 16, 2026

Leafhour’s Model Context Protocol (MCP) adapter lets a compatible AI host read a book you authorize. It uses the same reading service as the website. Access is limited to one book and the data types you select; installing the adapter alone grants no access.

This is a technical integration. The current reading interface is primarily Chinese and does not yet provide a complete grant-management screen. Use an existing compatible client or the authenticated service API to create and revoke grants. Contact support@leafhour.com if you need help.

Choose what the agent may access.

Start with content only. A grant expires after seven days and can be revoked earlier. A revoked grant fails subsequent service authorization; revocation cannot erase content already copied into your AI host.

Connect the adapter.

1. Run Leafhour locally using the repository instructions, or use the hosted reading service. Import a book or choose a public sample in your reading room.
2. Through a compatible client or the authenticated API, create a grant with a bookId and selected scopes using POST /api/library/grants. The token is returned once; keep it in your AI host’s private configuration.
3. Read GET /api/library/mcp-setup and use the configuration builder to create the host configuration. For a local source checkout, the adapter runs as node server/mcp.mjs. The hosted setup returns the deployed source commit, and the generated configuration pins that immutable source package with explicit HTTPS access; missing deployment provenance fails closed.
4. Enable the MCP server in your compatible AI host, and pass the authorized book ID with tool requests. Revoke access with POST /api/library/grants/{id}/revoke when you are done.

The adapter uses these environment variables:

READER_SERVICE_URL=http://127.0.0.1:8330
READER_AGENT_TOKEN=<your book-scoped grant>

# For your configured HTTPS service only:
# READER_SERVICE_URL=https://leafhour.com
# READER_ALLOW_REMOTE=true

Never put a login password, session cookie, Supabase key or grant token into a public document or repository. An MCP grant is separate from your website login. Use your host’s secret storage where available.

Ask for a passage, then go deeper.

reader_get_manifest lists the book’s source metadata and chapter identities. reader_get_context returns a passage with its adjacent passages and stable anchors. reader_get_chapter returns at most 20 passages at a time and a continuation cursor. reader_search searches the authorized book and returns up to 20 anchored matches.

With additional scopes, reader_get_notes reads comments and questions, reader_get_reading_activity reads position and sessions, and reader_add_comment saves explicitly supplied user text. Agent access does not add time to your reading calendar.

For example: “In my authorized book, find passages about friendship, show the source chapter and paragraph anchors, and help me compare the author’s wording.” The agent needs the book ID; it cannot infer permission to search your entire private library.

Know the current limits.

The adapter also exposes audio tools, but hosted audio generation is not enabled. Local audio needs separate configuration and permissions; generating audio can incur provider charges. MCP does not currently upload books, automatically translate a whole library, or schedule notifications by itself.

The built-in reading assistant has its own read-only boundaries and is separate from this external MCP grant. See the privacy notice for hosted processing details.

For exact tool definitions and current service behavior, inspect the adapter source, the service routes and the scoped MCP reading notes. This guide describes the current implementation, not planned capabilities.