Libris API & MCP

Libris is an agent-native reading library — Goodreads × Strava, but designed so an agent can drive it as fluently as a human. The library is a plain, honest record of what you read; agents bring the intelligence.

There is no first-party AI inside Libris. No summaries, no recommendations, no "smart" widgets. The product is the data layer and the surfaces that expose it. If you want recommendations, you bring an agent; if you want a year-in-review, you bring an agent. Libris will tell that agent everything it knows.

Two surfaces sit on the same service layer:

• REST at /v1/*. Every endpoint is documented in REST API. The web UI is a thin client over these same routes — there are no human-only escape hatches.
• MCP over stdio (Claude Desktop / Claude Code) and Streamable HTTP (remote agents). Tools are all listed in MCP server.

Anything a human can do, an agent can do. Anything an agent can do, a human can do. That parity is enforced at the auth layer — both surfaces accept the same API keys, and both write to the same activity-event feed. If the two ever drift, that's a bug.

REST authenticates with long-lived API keys prefixed with libris_. Issue and revoke keys at /settings/api-keys. The raw key is shown exactly once at creation — store it somewhere you can reach it.

Send it on every request, in either header (the API accepts both):

Authorization: Bearer libris_xxx
# or, equivalently:
x-api-key: libris_xxx

A minimal smoke test once you have a key:

curl -H "Authorization: Bearer $LIBRIS_KEY" \
  https://your-libris.example.com/v1/activity?limit=5

The web UI uses cookie-based sessions for the same routes — REST endpoints accept either an API key or a logged-in session, with the key path checked first. Browsers get sessions, scripts get keys, the underlying behavior is identical.

Remote MCP clients can use either an API key bearer token or OAuth. OAuth clients discover Libris through the MCP protected-resource metadata at https://mcp.readlibris.com/.well-known/oauth-protected-resource, then complete browser authorization with the Libris auth server. OAuth access tokens use libris:read and libris:write scopes; OAuth clients may also request offline_access so they can refresh tokens without asking you to sign in again.

API keys are scoped to the issuing user and act as that user. There are no per-key scopes or rate limits in V1; OAuth tokens are scope-limited by the authorization grant.

A few cross-cutting conventions apply across both REST and MCP. Knowing these up front avoids re-deriving them from individual endpoint shapes.

Book references

MCP tools that operate on a book accept a bookRef string instead of forcing the caller to look up an ID first. Resolution is in order:

1. If the value is a UUID, treat it as a books.id.
2. Otherwise, if it looks like an ISBN-13, match against books.isbn13.
3. Otherwise, do a fuzzy title match scoped to the caller's library (i.e. through their user_books rows). The agent should have already added the book by lookup or manual creation — Libris will not silently search the global catalog while resolving refs.

REST endpoints take a UUID directly. The fuzzy-match convenience is an MCP affordance only.

Import sessions

Import sessions are durable previews, not raw bulk-add shortcuts. In V1, an MCP agent reads source material and submits normalized JSON candidates with rawSource and unmapped context attached. Libris validates those records, classifies preview buckets, stores conflicts, and commits only clean or explicitly approved rows.

Source facts win during commit. Enrichment may be flagged afterward, but imported dates, ratings, authors, bindings, links, and review/notes are not overwritten by external metadata during the import.

Time inputs

Endpoints that accept a since parameter (notably GET /v1/activity and recent_activity) take either an ISO 8601 timestamp or a duration shorthand:

30s   # 30 seconds ago
15m   # 15 minutes ago
2h    # 2 hours ago
7d    # 7 days ago

All timestamps emitted by the API are UTC ISO 8601. Date-only values (e.g. session_date) are still serialized as full ISO timestamps with a 00:00 UTC component.

Pagination

Listing endpoints take a limit query parameter (default 50, max 200). Results are ordered most-recent-first by default; sort controls live on individual endpoints (e.g. GET /v1/books accepts sort and direction). The activity feed returns a nextCursor when there is more.

The activity-event guarantee

Every state-changing call — adding a book, changing status, logging a session, rating, favoriting, joining a collection, setting a goal, or committing an import — writes to activity_events. That row is what an agent reads to discover what happened, when, and why. See Activity events for the type catalog. Import commits emit one summary event for the session instead of hundreds of per-book historical events. The one carve-out is PUT /v1/books/{id}/notes: free-text notes are private scratch space and intentionally do not produce a feed entry.

All endpoints live under /v1 and accept the auth headers described above. Click any row to expand its parameters, request body, and response shapes. The canonical spec lives in openapi.yaml at the repo root — this page is generated from it.

curl -X POST -H "Authorization: Bearer $LIBRIS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"Handbound Zine","authors":[{"name":"M. Author"}],"status":"to_read"}' \
  "https://your-libris.example.com/v1/books"

curl -X POST -H "Authorization: Bearer $LIBRIS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"candidates":[{"sourceKey":"pollan-omnivore","title":"The Omnivores Dilemma","authors":["Michael Pollan"],"rawSource":{"slug":"pollan-omnivore"}}]}' \
  "https://your-libris.example.com/v1/import-sessions/<session-id>/items"

curl -X POST -H "Authorization: Bearer $LIBRIS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"bookId":"<uuid>","startPage":120,"endPage":156,"durationMinutes":42}' \
  "https://your-libris.example.com/v1/sessions"

curl -H "Authorization: Bearer $LIBRIS_KEY" \
  "https://your-libris.example.com/v1/collections"

curl -H "Authorization: Bearer $LIBRIS_KEY" \
  "https://your-libris.example.com/v1/goals/2026/progress"

curl -H "Authorization: Bearer $LIBRIS_KEY" \
  "https://your-libris.example.com/v1/activity?since=24h"

curl -H "Authorization: Bearer $LIBRIS_KEY" \
  "https://your-libris.example.com/v1/search/books?q=tolkien&limit=5"

Libris ships a Model Context Protocol server with two transports. Both expose the same tool set; the only difference is wiring.

stdio — Claude Desktop / Claude Code

Run the server as a child process; the agent client speaks JSON-RPC over stdin/stdout. The server reads LIBRIS_API_KEYfrom the environment and scopes every call to that key's user. One user per process.

{
  "mcpServers": {
    "libris": {
      "command": "pnpm",
      "args": ["mcp:stdio"],
      "cwd": "/path/to/librisnew",
      "env": {
        "LIBRIS_API_KEY": "libris_xxx"
      }
    }
  }
}

For Claude Code, add the same entry to your project- or user-scoped MCP config, or run pnpm mcp:stdio directly.

Streamable HTTP — remote agents

For agents that don't live on the same machine as Libris (most of them), use the hosted HTTP transport at https://mcp.readlibris.com/mcp. Each request carries its own API key or OAuth bearer token, so a single deployment serves multiple users.

curl -X POST https://mcp.readlibris.com/mcp \
  -H "Authorization: Bearer libris_xxx" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list"
  }'

The HTTP transport is stateless — there are no MCP sessions to resume. Each POST /mcp spins up a fresh per-user server scoped to the bearer token, runs the request, and tears down. Methods GET /mcp and DELETE /mcp return 405 by spec.

OAuth-capable MCP clients should be pointed at https://mcp.readlibris.com/mcp. They can discover the protected resource metadata at https://mcp.readlibris.com/.well-known/oauth-protected-resource. The authorization server issuer is https://www.readlibris.com/api/auth, with discovery metadata at https://www.readlibris.com/.well-known/oauth-authorization-server/api/auth.

Tools

Click any tool to see its argument schema. Names mirror the conceptual action; bookRef arguments accept the UUID / ISBN-13 / fuzzy-title forms described in Conventions.

Use add_book with a search query, lookup ISBN, or manual title. Manual title mode creates a library record from supplied metadata when external catalogs do not have the book.

For historic archives, use the import tools instead of looping add_book. The agent reads local files, submits normalized candidates, inspects the preview, asks before committing, and lets Libris preserve conflicts and provenance in the import session.

Every mutation writes one row to activity_events. Reading the feed is how an agent reconstructs "what changed since the last time I looked" without polling individual resources. Filter by type with ?types=book_completed,session_logged, or timebox with ?since=24h.

Each event carries a payload object with type-specific detail (e.g. session_logged includes startPage, endPage, durationMinutes; status_changed includes from and to). The exact shape is intentionally not part of the v1 contract — read what's there, treat unknown keys as informational.

REST errors are JSON with an errorfield and an HTTP status that's actually meaningful. MCP errors come back through JSON-RPC with an error.code and error.message.

401 — missing or invalid key

Returned when the request has no recognized credential, or the key has been revoked.

 { "error": "Unauthorized" } 

{
  "jsonrpc": "2.0",
  "error": { "code": -32000, "message": "Invalid API key" },
  "id": null
}

404 — resource not found

The book, collection, goal, or session ID isn't in the caller's scope. Libris doesn't leak existence — the same 404 is returned whether the row doesn't exist or belongs to a different user.

{ "error": "Not found" }

400 / 422 — validation failure

Request body or query parameters didn't match the expected schema. The error includes a details object with the failing field path so an agent can self-correct.

{
  "error": "Validation failed",
  "details": [
    { "path": ["stars"], "message": "Number must be greater than or equal to 1" }
  ]
}

409 — conflict

Returned when a write would violate a uniqueness or state invariant — e.g. starting a live timer when one is already running for the user (the existing one is replaced; this is informational, not a hard error in current implementation).

500 — internal error

Something on the server side broke. Retry once with the same payload; if it persists, check the server logs (or the Sentry dashboard once Phase 4 lands). MCP wraps the underlying message in JSON-RPC code -32603.

{
  "jsonrpc": "2.0",
  "error": { "code": -32603, "message": "Internal error" },
  "id": null
}