Connect AI Agents

Give your AI superpowers. Connect Claude, ChatGPT, or Gemini to the SansFiction library.

Quick Info

MCP Endpoint

https://sansfiction.com/api/mcp

Auth

OAuth 2.1 via Supabase. Public search is anonymous; personal library access requires consent.

Capabilities

Search books, authors, and series with filters
Get detailed book metadata, editions, and collections
Manage your library, progress, and stats (Auth required)

Setup Instructions

C
Claude Code / Desktop

The easiest way to connect using the Claude CLI.

claude mcp add --transport http sansfiction https://sansfiction.com/api/mcp

Then verify it works:

claude mcp list

Manual Token (Claude/Cursor)

API & Agent access token

One token for both the REST API (Authorization: Bearer … on /api/v1) and MCP clients that do not support OAuth.

Active tokens

Loading tokens...

JSON Config

Paste your token into the Authorization header.

{
  "mcpServers": {
    "sansfiction": {
      "type": "http",
      "url": "https://sansfiction.com/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  }
}

OAuth is recommended when available. Manual tokens are limited to your account.

REST API (v1)

Prefer plain HTTP over MCP? Every capability is available as a REST API under /api/v1, authenticated with the same access token. Great for agents, scripts, and Claude/OpenAI “skills”.

Public catalog — no auth

Search and read public metadata.

curl "https://sansfiction.com/api/v1/catalog/search?q=dune&limit=5"

GET /api/v1/catalog/search?q=
GET /api/v1/catalog/books/{bookId}
GET /api/v1/catalog/series/{seriesId}
GET /api/v1/catalog/collections

Personal library — bearer token

Read and update your own library.

curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://sansfiction.com/api/v1/library/books?status=reading"

GET/POST /api/v1/library/books
PATCH/DELETE /api/v1/library/books/{id}
GET /api/v1/library/collections
GET /api/v1/library/stats

Full machine-readable spec: /openapi.json · Agent skill: SKILL.md

Example Prompts

"Find books by Brandon Sanderson published in 2023."

"Get details for 'Project Hail Mary' including page count."

"Authorize SansFiction for my account."

"List my currently reading books."

"Log progress: 'Dune' is now at page 150."

"Move 'Dungeon Crawler Carl' to finished."

"Show me collections with 'Fantasy' in the name."

"Show my monthly reading stats."

Troubleshooting

Connection Failed?

Ensure your AI client can access the internet. SansFiction's MCP server is hosted at https://sansfiction.com/api/mcp and requires HTTPS.

401 Unauthorized

You tried to access a private tool without OAuth consent. Trigger the OAuth flow and approve access.

Tool List Empty

Verify you entered the correct URL without any trailing spaces or extra paths. It must end with /api/mcp.