--- title: "Use SFF Book Awards with an AI Assistant" description: "Connect an MCP-capable AI assistant to the public science fiction and fantasy book awards dataset endpoint." canonical: "https://sffawards.com/use-with-ai-assistant/" --- # Use SFF Book Awards with an AI Assistant Connect an MCP-capable assistant to the public science fiction and fantasy book-awards dataset. The server is read-only, needs no authentication or secret headers, and serves generated public artifacts rather than live source data. - **books:** 3,250 - **recognitions:** 4,449 - **page copy updated:** Jul 29, 2026 - **dataset metadata updated:** Aug 28, 2026 - **site export built:** Aug 28, 2026 ## Connect - **MCP endpoint:** https://sffawards.com/mcp - **Transport:** Modern Streamable HTTP on one endpoint. Requests use JSON-RPC over `POST` with JSON responses or request-scoped SSE when needed. - **Protocol version:** The endpoint serves only `2026-07-28`. Every request is self-describing and carries the same version in its HTTP header and reserved request metadata. - **Authentication:** None. Do not send OAuth credentials, API keys, bearer tokens, cookies, or user account state. ## Use with ChatGPT Follow OpenAI's current [Connect from ChatGPT](https://developers.openai.com/apps-sdk/deploy/connect-chatgpt) guide for developer-mode availability and the current interface. Use [https://sffawards.com/mcp](https://sffawards.com/mcp) as the public MCP server URL. This endpoint needs no authentication and no secret headers. UI labels and workspace controls can change, so this page does not duplicate the setup navigation or require optional app metadata such as an icon. ## Browser WebMCP The MCP endpoint above is the recommended integration for ordinary assistant clients. The interactive browser app also exposes experimental [WebMCP](https://developer.chrome.com/docs/ai/webmcp) tools when an agent opens [https://sffawards.com](https://sffawards.com) in a supported Chrome origin-trial or local-testing context. The homepage registers them through the current [document.modelContext.registerTool()](https://developer.chrome.com/docs/ai/webmcp/imperative-api) API; the tab must stay open while an agent discovers or executes them. These browser tools are separate from the remote `/mcp` endpoint and use only public generated data already loaded by the app. - **get_sff_awards_context:** Read-only dataset freshness, counts, top facets, current URL, and discovery links. - **search_sff_awards_books:** Read-only bounded search and filtering without changing the visible page. - **show_sff_awards_books:** Applies filters to the visible browser page and returns the matching public books. - **recommend_sff_awards_books:** Read-only deterministic recommendations for common reader intents. - **open_sff_awards_page:** Navigates the visible tab to a main site page. ## What You Can Ask - I liked award-winning space opera. What should I read next? - Compare three books I name and tell me which is the best entry point. - What recent fantasy winners have lots of reader engagement? - Which awards does a book I name have, and what else is similar? - Explain what the dataset covers before recommending anything. - Give me overlooked books recognized by awards in the 1990s. - Show me Hugo-winning novels since 2010 that work as entry points. - Find fantasy books that were recognized by more than one award family. - Recommend standalone science fiction with strong reader ratings. - What are good first books for exploring cyberpunk, high fantasy, or urban fantasy? - List recent nominees with lower Goodreads rating counts but strong award evidence. - Compare award recognition and reader engagement for books I am choosing between. ## Agent Instruction ``` Use the book_awards MCP server for public science fiction and fantasy award data. Start with native MCP discovery, then call get_dataset_info when you need freshness, facets, coverage, scoring notes, limits, or export links. Use search_books for filtered retrieval, recommend_books for reader intent, get_book for one work, get_award for one award category, get_subgenre for one taxonomy view, and compare_books for side-by-side choices. Ground recommendations in returned award recognition, years, win or finalist status, rating counts, score context, caveats, and stable work_key values. Do not infer live Goodreads or SFADB state; this endpoint serves generated public artifacts only. ``` ## Required HTTP Flow - Start with `server/discover`. There is no initialization or session lifecycle. - For every `POST`, include `MCP-Protocol-Version: 2026-07-28` and the matching reserved protocol value in `params._meta`. - Include `Mcp-Method` with the JSON-RPC method and `Mcp-Name` for named operations. - Include client capabilities in reserved request metadata; client identity is recommended but optional. - Browser clients must send a valid HTTPS origin or a local development origin. ``` POST /mcp HTTP/1.1 Host: sffawards.com Accept: application/json Content-Type: application/json MCP-Protocol-Version: 2026-07-28 Mcp-Method: server/discover Origin: https://your-client.example { "jsonrpc": "2.0", "id": 1, "method": "server/discover", "params": { "_meta": { "io.modelcontextprotocol/protocolVersion": "2026-07-28", "io.modelcontextprotocol/clientInfo": { "name": "your-client", "version": "1.0.0" }, "io.modelcontextprotocol/clientCapabilities": {} } } } ``` ## Native Discovery Use native MCP discovery. `tools/list` exposes tool descriptions, input schemas, output schemas, and read-only annotations. Use `resources/list`, `resources/templates/list`, and `prompts/list` for the resource and prompt catalog. `completion/complete` provides deterministic, bounded suggestions for resource templates and supported prompt arguments. There is no separate discovery tool. ``` { "jsonrpc": "2.0", "id": 2, "method": "tools/list", "params": { "_meta": { "io.modelcontextprotocol/protocolVersion": "2026-07-28", "io.modelcontextprotocol/clientInfo": { "name": "your-client", "version": "1.0.0" }, "io.modelcontextprotocol/clientCapabilities": {} } } } ``` ``` { "discovery_methods": [ "tools/list", "resources/list", "resources/templates/list", "prompts/list", "completion/complete" ], "schema_resources": [ "book-awards://schemas/manifest", "book-awards://schemas/tools", "book-awards://schemas/shared" ] } ``` ## Current MCP Tools - **get_dataset_info:** Coverage, metadata freshness, facets, scoring, exports, and limits, including explicit projection metadata for truncated facet groups. - **search_books:** Filtered book retrieval by normalized title/author text, award-recognition genre, award, subgenre, year, recognition status, score, audience size, and series mode. - **recommend_books:** Goal-oriented recommendations for entry points, recent winners, reader favorites, hidden gems, similar books, and selector-scoped shortlist or subgenre samplers. - **get_book:** One work by `work_key` or Goodreads book ID. - **get_award:** Award-category views with year, recognition, genre, sort, and limit filters. - **get_subgenre:** Subgenre views with award-year, recognition, series-mode, sort, limit, and offset filters. Returns up to 50 works per page from the complete filtered population. - **compare_books:** Compare 2 to 5 distinct works. Requested dimensions control the returned work fields, strongest values, and notes. ## Tool Call Example Tool calls return schema-valid canonical `structuredContent` plus a concise text summary rather than a full JSON mirror. `get_book`, `get_award`, `get_subgenre`, and `get_dataset_info` also return one natural `resource_link`. `genre` is an award-recognition genre filter, not a work-genre or subgenre-family filter. Award or family, award year, winner state, and genre are evaluated against the same recognition rows. `non-winners` means a qualifying row with `winner: false`; it does not mean the work has no wins elsewhere. Work `genre_keys` and taxonomy subgenre families remain separate evidence. ``` { "jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": { "_meta": { "io.modelcontextprotocol/protocolVersion": "2026-07-28", "io.modelcontextprotocol/clientInfo": { "name": "your-client", "version": "1.0.0" }, "io.modelcontextprotocol/clientCapabilities": {} }, "name": "search_books", "arguments": { "subgenre_keys": [ "space-opera" ], "recognition": "winners", "limit": 5 } } } ``` ``` { "jsonrpc": "2.0", "id": 3, "result": { "resultType": "complete", "content": [ { "type": "text", "text": "Found 1 of 1 matching award-recognized books." } ], "structuredContent": { "results": [ { "work_key": "work-gr-example", "title": "Example Award Winner", "award_keys": [ "hugo-novel" ], "subgenre_keys": [ "space-opera" ] } ], "page": { "limit": 5, "offset": 0, "total": 1, "has_more": false, "next_offset": null } } } } ``` ## Error Handling - Award, award-family, and subgenre keys are closed discovery vocabularies. Unknown values are rejected by input validation; use `get_dataset_info` facets or the full facets resource to choose a listed key. - Work keys remain open identifiers. Unknown keys return `isError: true` with schema-conforming structured miss data. `get_book` echoes the requested identifier; `compare_books` and `recommend_books(intent="similar_to")` additionally return `missing_work_keys`. - Missing intent selectors, reversed ranges, duplicate comparison keys, and incompatible comparison dimensions return actionable error tool results. - Only confirmed missing dynamic artifacts become resource-not-found protocol errors. Asset backend failures, malformed JSON, network failures, and cancellation remain internal server errors. - The current SDK exposes an unknown tool name as an error tool result. Malformed HTTP/JSON-RPC, invalid origins, content types, methods, and unsupported or mismatched protocol headers fail at the HTTP or protocol layer. ``` { "jsonrpc": "2.0", "id": 5, "result": { "resultType": "complete", "isError": true, "structuredContent": { "found": false, "intent": "similar_to", "requested": { "seed_work_key": "work-gr-unknown" }, "missing_work_keys": [ "work-gr-unknown" ], "results": [], "page": { "limit": 10, "offset": 0, "total": 0, "has_more": false, "next_offset": null }, "recommendation_reasons": {} }, "content": [ { "type": "text", "text": "No matching public work was found for work-gr-unknown." } ] } } ``` ## Resources And Prompts Resources expose dataset metadata, facets, scoring, exports, schemas, works, awards, and subgenres. Scoring and export resources are named projections. Award and subgenre resources are bounded summaries with tool hints; use tools for complete filtered retrieval. Prompts cover next-read recommendations, book comparison, and dataset explanation. Resource templates and supported prompt arguments provide deterministic completion with at most 25 suggestions. Completion for `compare_sff_books.work_keys` preserves selected keys while suggesting the next distinct stable `work_key`. ## Schema Artifacts `tools/list` is the live contract. The schema manifest hashes generated tool and shared schemas. The OpenAPI file describes the HTTP/JSON-RPC transport envelope, not each tool's live schema, and is not claimed by either hash manifest. - [Schema manifest](https://sffawards.com/data/mcp/schemas/manifest.json) - [Tool schemas](https://sffawards.com/data/mcp/schemas/tools.json) - [Shared schemas](https://sffawards.com/data/mcp/schemas/shared.json) - [Dataset freshness metadata](https://sffawards.com/data/mcp/dataset-info.json) - [MCP artifact manifest](https://sffawards.com/data/mcp/manifest.json) ## Limits, Freshness, And Caching - `metadata_updated_at` means the last semantic change to dataset metadata. The root artifact manifest and its per-artifact hashes identify the complete generated MCP snapshot. `awards.json.generated_at` records the latest site export/build time. - Search, recommendation, award, and subgenre tools use offset pagination. Follow `page.next_offset` while `page.has_more` is true. - Every `/mcp` response, including CORS preflight, uses `Cache-Control: no-store`. MCP list and read results separately carry bounded public protocol cache hints for supporting clients; the preflight max-age caches only the permission decision. - Every current `/data/mcp/*` path uses `Cache-Control: public, no-cache, must-revalidate`. Long-lived immutable caching is reserved for future fingerprinted URLs. ## Related Links - [Open the interactive award browser](/) - [Read the browser guide](/guide/) - [Browse award pages](/awards/) - [Browse subgenre pages](/subgenres/)