Developers and AI Agents

Connect BookSignal to your AI agent

BookSignal exposes its catalog as both a REST API and an MCP (Model Context Protocol) server. Your AI agent can search, browse, and recommend books directly from the catalog in response to natural-language requests.

Available MCP tools

Tool	Auth required	Description
get_book	None	Fetch full details for a single book by its ID, including store links and reading-experience dimensions.
search_books	API key	Natural-language search across the catalog using vector embeddings. Returns ranked matches with similarity scores.
recommend_books	API key	Tailored for "what should I read next" prompts. Same semantic engine as search, optimised for preference descriptions.

Setup: Claude Desktop

These steps add BookSignal as an MCP server so Claude can search and recommend books during any conversation.

Create a free reader account at booksignal.app if you do not have one yet.

Generate an API key

Go to Dashboard → API Keys and click Create. Copy the key immediately — it is shown only once.

Open Claude Desktop config

Open your Claude Desktop configuration file. On macOS it is at ~/Library/Application Support/Claude/claude_desktop_config.json. On Windows it is at %APPDATA%\Claude\claude_desktop_config.json.

Add the BookSignal server

Paste the following into the mcpServers section, replacing YOUR_KEY with the key you copied:

{
  "mcpServers": {
    "booksignal": {
      "url": "https://booksignal.app/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_KEY"
      }
    }
  }
}

Restart Claude Desktop

Quit and reopen Claude Desktop. You will see a hammer icon in the chat toolbar — click it to confirm the three BookSignal tools are listed.

Try it

Ask Claude: "Find me a slow-burn romance with found family themes." Claude will call search_books and return real recommendations from the BookSignal catalog.

Setup: Cursor

Cursor's Agent mode supports MCP servers. Once connected, Composer can look up and recommend books without any extra prompting.

Generate an API key

Follow steps 1 and 2 above to get a catalog:read key from your dashboard.

Open Cursor MCP settings

In Cursor, open Settings → Cursor Settings → MCP and click Add new MCP server.

Paste the server config

Use the same JSON snippet as the Claude Desktop setup above, or add it directly to your project-level .cursor/mcp.json file.

{
  "mcpServers": {
    "booksignal": {
      "url": "https://booksignal.app/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_KEY"
      }
    }
  }
}

Enable and test

Toggle the server on. In Composer, ask Cursor Agent to "recommend three fantasy novels with morally grey protagonists" — it will invoke the BookSignal tools automatically.

REST API

Use the REST API to build your own integrations. Browse and get single books without any authentication; semantic search requires an API key.

Method	Path	Auth	Description
GET	/api/v1/books	None	Paginated list of published books
GET	/api/v1/books/{id}	None	Full detail for a single book
POST	/api/v1/books/search	API key	Natural-language vector search

List books (no auth)

curl "https://booksignal.app/api/v1/books?genre=Romance&limit=20"

Semantic search (API key)

curl -X POST https://booksignal.app/api/v1/books/search \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"cozy fantasy with found family and low stakes","limit":5}'

Full schema: booksignal.app/api/openapi.json

MCP server details

Streamable HTTPMCP SDK compatible

Server URL

https://booksignal.app/api/mcp

Pass your API key as an Authorization: Bearer header. The server uses the stateless streamable HTTP transport, compatible with any MCP client that supports the 2025-03-26 protocol version.

Ready to connect?

Get your API key View OpenAPI spec