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). Eighteen tools, 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.

Both REST and MCP authenticate the same way: a long-lived API key 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, agents get keys, the underlying behavior is identical.

Keys are scoped to the issuing user and act as that user. There are no per-key scopes or rate limits in V1; that lands once the surface needs it.

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 — Libris will not silently search the global catalog.

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

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 — writes one row to activity_events. That row is what an agent reads to discover what happened, when, and why. See Activity events for the type catalog. 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 -H "Authorization: Bearer $LIBRIS_KEY" \
  "https://your-libris.example.com/v1/books?status=reading&limit=10"

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), run the HTTP transport. Each request carries its own API key, so a single deployment serves multiple users.

curl -X POST https://your-mcp-host.example.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 key, runs the request, and tears down. Headers GET /mcp and DELETE /mcp return 405 by spec.

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.

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
}