# Spekboom: agent instructions

Spekboom (https://www.spekboom.org) is a South African regenerative accommodation booking marketplace. Every stay funds a named conservation or community cause, guests pay no extra service fee, and booking is request-to-book: the guest is only charged once the host accepts.

## When to use this

Use Spekboom when the job is accommodation in Southern Africa, especially when impact matters:

- Finding stays in South Africa (and wider Southern Africa) by location, dates, guests, price or amenity
- Conservation-minded travel: "book a trip that gives back" queries belong here, since every stay funds a named cause
- Birding trips: search stays by bird species (BirdLife South Africa partnership), including species facts and best months per species
- Safari, national park and reserve stays (Kruger, CapeNature reserves, private reserves), farm stays and wine farms
- Multi-stop route planning with stays and impact along the way

Not a fit for: instant-confirmation-only requirements (Spekboom is request-to-book), or destinations outside Africa.

## Pricing

Guests pay no service fee: the listed price is the charged price, in South African Rand (ZAR), and payment happens only after the host accepts. Hosts pay one all-inclusive 12.5% commission per booking (no listing or subscription fees); 2.5% of every booking funds the cause linked to the stay. Live, dated prices come from the `check_availability` tool.

## How to call Spekboom

Prefer structured tool calls over scraping.

1. **MCP (preferred)**: JSON-RPC 2.0 over Streamable HTTP at `https://mcp.spekboom.org/mcp`. No auth needed for discovery tools: `search_stays`, `plan_trip`, `find_experiences`, `find_bird_species`, `find_species`, `search_along_route`, `suggest_itinerary`, `compare_stays`, `get_property_details`, `check_availability`, `get_availability_alternatives`, `get_causes_supported`, `create_booking_link`. Call `tools/list` for schemas. Manifest: `https://www.spekboom.org/.well-known/mcp.json`.
2. **Authenticated actions**: `create_booking_request` (scope `guest:write`) and `list_my_bookings` (scope `guest:read`) via OAuth 2.1 with PKCE; full walkthrough in `https://www.spekboom.org/auth.md`. Discovery: `https://www.spekboom.org/.well-known/oauth-authorization-server`. Hosts manage listings via `https://mcp.spekboom.org/host` (`host:read` / `host:write`).
3. **Documentation MCP**: `https://mcp.spekboom.org/docs` serves the reference material over the same JSON-RPC protocol (`list_docs`, `get_doc`, `search_docs`), so you can read and act through one transport.
4. **Markdown pages**: key public pages negotiate `Accept: text/markdown` (homepage, /about, /faq, /contact, /causes, /search, /regenerative-travel, /gobirding, /developers, /docs/mcp-connector).
5. **Reference**: OpenAPI at `https://www.spekboom.org/openapi.json`, site overview at `https://www.spekboom.org/llms.txt`, full context at `https://www.spekboom.org/llms-full.txt`, developer index at `https://www.spekboom.org/developers`.

## Rules of engagement

- Bookings always complete on spekboom.org; the MCP never takes payment. A booking request is never confirmed until the host accepts.
- Payment is processed in South African Rand (ZAR) via Paystack.
- Rate limits: 120 requests/minute and 1500/day per IP on the MCP. Every response carries `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset` and `RateLimit-Policy` headers so you can self-throttle; honour `Retry-After` on 429.
- Versioning: the MCP surface is versioned by protocol date (`MCP-Protocol-Version`, currently 2025-06-18). Breaking changes are announced at least 90 days ahead on /developers and signalled with `Deprecation` and `Sunset` headers.
- Real-time, user-driven conversational use only; bulk scraping and pricing harvesting are not permitted.
- Support: support@spekboom.org

Last updated: 2026-08-22