Docs

MCP Reference

Plug your reading life into your AI agent.

The Spine MCP server exposes your bookshelf, your reading companion, and the full Spine catalog to any Model Context Protocol client — Claude Desktop, Cursor, Goose, and more. Thirty-six tools, one API key, and your agent can search, shelve, review, and ask your companion about any book on your behalf.

Overview

MCP is a standard from Anthropic for exposing tools and resources to AI models over a local stdio process. When you install the Spine MCP server, your AI client can see a catalog of tools it can call — each one hits the Spine API as you.

In practice, this means you can say things like "add Piranesi to my shelf," "what should I read next?", or "I just finished The Sparrow — loved it" and your agent will handle the entire flow without opening the app.

Install

The MCP server is a single-file TypeScript program that runs on Bun or Node 18+. 

# clone the Spine repo (private beta access required)
$ git clone git@github.com:Jbern16/spine.git
$ cd spine/apps/mcp
$ bun install

# verify it runs (it'll wait on stdio)
$ SPINE_API_KEY=sk_spine_... bun src/index.ts
i
Beta access. Like the CLI, the MCP server lives in the private Spine repo during beta. Ask for access in Discord (#developer-access).

Authenticate

The server reads two environment variables:

Generate your key in the Spine mobile app: Settings → API Key → Generate. Your key acts as you — same permissions as your mobile session, no scopes. Any MCP tool your agent calls runs on your account.

!
Treat it like a password. One key per user, rotated on regenerate. If you think your key is exposed, open Settings → API Key and generate a new one — the previous key stops working instantly.

Claude Desktop

Edit your Claude Desktop config file. On macOS that's ~/Library/Application Support/Claude/claude_desktop_config.json; on Windows it's %APPDATA%\Claude\claude_desktop_config.json. 

{
  "mcpServers": {
    "spine": {
      "command": "bun",
      "args": ["run", "/absolute/path/to/spine/apps/mcp/src/index.ts"],
      "env": {
        "SPINE_API_KEY": "sk_spine_your_key_here"
      }
    }
  }
}

Restart Claude Desktop. You should see a little tools icon in the input bar; click it to verify the Spine tools are loaded.

Cursor

Cursor reads MCP configs from ~/.cursor/mcp.json. Same shape as Claude Desktop: 

{
  "mcpServers": {
    "spine": {
      "command": "bun",
      "args": ["run", "/absolute/path/to/spine/apps/mcp/src/index.ts"],
      "env": {
        "SPINE_API_KEY": "sk_spine_your_key_here"
      }
    }
  }
}

Other clients

Any MCP client that supports stdio servers should work. The command is always bun run <path to index.ts> (or node dist/index.js if you build first), and the only required env var is SPINE_API_KEY.

The server identifies itself as spine version 0.1.0, so you'll see it under that name in most MCP UIs.

First prompt

Once the server is wired up, try prompts like these:

Your agent decides which tool to call based on the prompt. The tool reference below documents exactly what each one does.

Books & catalog

Look up books, authors, series, and browse by mood.

search_books

Search for books by title, author, or keyword. Returns up to eight matches from the Spine catalog and ISBNdb.

  • query string Search term — title, author, or keyword. required 
"Search for science fiction books about space travel"
get_book

Full book details — title, author, publisher, page count, year, series info, moods, ISBN, and description.

  • bookId string Book ID from search_books. required
resolve_book

Resolve a book by title (and optionally author) via AI search. Doesn't create anything — just tells your agent whether the book exists and returns its ID.

  • title string Book title. required
  • author string Author name (helps disambiguation).
get_similar_books

Up to ten books similar to a given book. Uses the rec model and catalog metadata.

  • bookId string Book ID to find similar books for. required
get_series

Series info for a book. Returns the series name and every book in reading order.

  • bookId string Any book in the series. required
get_author

Author profile — bio, photo, complete bibliography, and series.

  • authorName string Full author name. required
browse_mood

Up to ten books for a mood (Cozy & Comforting, Dark & Brooding, Thought-Provoking, and so on).

  • mood string The mood name. Use list_moods to see all options. required
list_moods

Returns every available mood you can browse by. Takes no parameters.

Shelf

Manage the books on your bookcase: status, rating, and written reviews.

get_shelf

Books on your shelf. Filter by status.

  • status enum read, reading, want, or all. Default: all.
  • limit number 1–100. Default: 20.
add_to_shelf

Add a book to your shelf. Call search_books first to get the book ID.

  • bookId string Book ID from search. required
  • status enum want, reading, or read. Default: want.
  • rating enum loved, liked, or disliked. Only valid when status is read.
update_shelf_entry

Change a shelf entry's status or rating. Use get_shelf to get the entry ID.

  • entryId string Shelf entry ID. required
  • status enum New status: want, reading, or read.
  • rating enum New rating: loved, liked, or disliked.
remove_from_shelf

Remove a book from your shelf entirely.

  • entryId string Shelf entry ID. required
write_review

Post a short review (max 280 characters) for a book.

  • bookId string Book ID. required
  • body string · max 280 Review text. required

Custom shelves

Curated sub-collections inside your bookcase — themed lists you can share or keep private.

list_shelves

All your custom shelves with book counts and visibility. No parameters.

create_shelf

Create a new custom shelf.

  • name string Shelf name. required
  • description string Optional description.
  • isPublic boolean Whether the shelf is visible to other users. Default: true.
view_shelf

List the books on a specific custom shelf.

  • listId string Shelf ID from list_shelves. required
add_book_to_shelf

Add a book from your bookcase to a custom shelf.

  • shelfEntryId string Shelf entry ID from get_shelf. required
  • listId string Custom shelf ID from list_shelves. required
remove_book_from_shelf

Remove a book from a custom shelf. The book stays in your bookcase.

  • shelfEntryId string Shelf entry ID. required
  • listId string Custom shelf ID. required
update_shelf_info

Update a custom shelf's name, description, or visibility.

  • listId string Custom shelf ID. required
  • name string New name.
  • description string New description.
  • isPublic boolean New visibility.
delete_shelf

Delete a custom shelf. Books remain in your bookcase.

  • listId string Custom shelf ID. required
create_shelf_from_titles

Create a shelf and populate it with books by title. Each title is searched, added to your bookcase if needed, and placed on the new shelf. Reports which titles were found and which weren't.

  • name string Shelf name. required
  • titles string[] Book titles to search for and add. required
  • description string Optional description.
  • isPublic boolean Visibility. Default: true.
build_shelf

Ask your companion to build a themed shelf from a natural-language prompt. Returns a shelf name and curated picks with reasoning.

  • prompt string Natural-language description (e.g. "literary horror with a grieving narrator"). required

Companion

Recommendations, explanations, and feedback loops with your reading companion.

ask_companion

Ask your companion about a specific book — why you might love it, how it fits your taste, any caveats.

  • bookId string Book ID to ask about. required
get_recommendations

Your current recommendations from your companion. No parameters.

dismiss_recommendation

Pass on a recommendation. Your companion uses the signal to refine future picks.

  • recId string Recommendation ID from get_recommendations. required
rec_feedback

Send specific feedback on a recommendation ("already read this," "not my vibe," etc.). More nuanced than dismiss_recommendation.

  • recId string Recommendation ID. required
  • feedback string Natural-language feedback. required
refresh_recommendations

Kick off a fresh rec generation. New picks show up within a minute. No parameters.

Social

Follow other readers, see what they're shelving, and interact with their reviews and lists.

toggle_like

Like or unlike a review, custom shelf, or shelf entry. Calling twice undoes the like.

  • targetType enum review, list, or shelf. required
  • targetId string ID of the target. required
follow_user

Follow another Spine user.

  • userId string User ID to follow. required
unfollow_user

Unfollow a Spine user.

  • userId string User ID to unfollow. required
get_friend_feed

Recent activity from readers you follow — reviews, shelf additions, likes. No parameters.

get_notifications

Recent notifications: likes on your shelves and reviews, new followers, new recommendations. No parameters.

mark_notifications_read

Mark every notification as read. No parameters.

Admin

enrichment_stats

Enrichment pipeline queue status: pending, done, failed. Useful when a book is missing metadata and you want to see whether the pipeline has processed it yet. No parameters.

report_book

Report a data issue with a book. Requires librarian status.

  • bookId string Book ID. required
  • issueType enum bad_cover, bad_data, wrong_author, or bad_shop_link. required
  • note string Optional note about the issue.