Connect an assistant to find books and prepare purchases within bounded shopping windows.
Client connection
Streamable HTTP, MCP 2025-06-18. Use HTTP POST JSON and OAuth Authorization Code with PKCE S256. Endpoint: https://server.exlibrus.net/api/v1/mcp/customer/. Authorization metadata: https://server.exlibrus.net/.well-known/oauth-authorization-server.
Send initialize, notifications/initialized and tools/list. Register a public OAuth client. Sign in or register on the website, verify email and explicitly approve the selected scopes for that client. For an existing verified account, recover_customer_access sends a dedicated MCP code as plaintext SMTP email. The user may give only this requested MCP code to the agent for complete_customer_access with the original PKCE verifier/state. Existing cabinet approval remains an alternative. Never send account passwords, login/reset/2FA codes, card details or gift redemption secrets to tools.
Search and requests
search_books accepts query and publisher_ids, series_ids, periodical_series_ids and category_path. Results are limited to 10 per response and 30 per query window. Keep the query and page size unchanged when using the returned cursor. book_details requires a previously discovered book; resolve_filters finds filter values by name. Bulk export and arbitrary ID enumeration are unsupported.
create_book_request can include additional books. get_book_request, request item tools and send_request_message share the existing request dialogue. An anonymous request capability grants access to that request alone; verified owners can claim it in their account.
Purchases and payment
Cart tools, checkout_quote and prepare_gift_purchase return the exact quote_summary, quote_hash and version. The assistant presents every order obligation, including existing periodical terms, gift design and recipient. After explicit user assent in conversation, call confirm_purchase with quote_id and expected_quote_hash. No browser purchase-confirmation step is required. create_order, purchase_gift and purchase_status are read-only receipt polls. Changed or expired terms require a fresh quote and assent. The human pays through payment_url once an invoice is payable; a tool response is not proof of payment.
list_orders, order_status and gift_status expose only your own purchases. gift_config and gift_quote show current designs and quotes. gift_human_download opens the protected account gift section; generic status never returns the PDF or redemption words.
Permission and recovery
Scopes: catalog:read, requests:read, requests:write, cart:read, cart:write, orders:read, orders:create, gifts:read, gifts:purchase. Grants belong to one client. Revoke one or all in account AI access. Refresh and verified-email recovery preserve budgets; new secrets require human consent and a one-use PKCE exchange.
Retry and support
For 429 respect Retry-After. Do not rotate tokens to bypass quotas. Refresh invalid_token, request a new quote for stale_quote, and retry a timed-out mutation with the same idempotency_key and identical body. Contact [email protected]. Site navigation contains current privacy and terms links.
Semantic search and request costs
Use mode text, vector or hybrid. Vector/hybrid requires a verified customer with catalog:read; normal public filters still apply. vector_used reports whether vector results contributed to this response. An unavailable vector service returns 503; select text explicitly for lexical search. Defaults are 5 semantic calls and 10 prepared purchase quotes per minute per customer, with at most two concurrent operations of each purpose. Search uses a bounded candidate window and does not claim catalog completeness.
Example without account access
Send these messages sequentially by HTTP POST with Content-Type: application/json and Accept: application/json, text/event-stream. After initialize send MCP-Protocol-Version: 2025-06-18. notifications/initialized returns empty202; no SSE GET is provided. This example performs anonymous text search only.
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"shopping-client","version":"1.0.0"}}}{"jsonrpc":"2.0","method":"notifications/initialized"}{"jsonrpc":"2.0","id":2,"method":"tools/list"}{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"search_books","arguments":{"query":"rare books","locale":"en","limit":10,"mode":"text"}}}