Skip to main content
Developer documentation

Spekboom MCP connector

An official Model Context Protocol connector that lets Claude, Gemini, and any MCP-compatible AI search Spekboom, check availability, and create booking links to regenerative stays across Southern Africa, each one directly funding a conservation or community cause.

Transport: Streamable HTTPAuth: optional OAuth (sign in to request bookings)Protocol: 2025-06-18

What it does

Spekboom is a regenerative travel platform for Southern Africa: every stay funds a conservation or community cause (wildlife protection, fynbos restoration, rural education, community upliftment). This connector brings that catalogue into Claude so users can plan trips and see conservation impact in a single conversation.

Discovery and planning tools work without signing in:

  • search_stays: find stays by location, dates, guests, experience type, cause, bird species, wildlife species, or wildlife highlights (e.g. Big Five).
  • find_experiences: find stays by theme (birding, stargazing, wine, regenerative farms, wildlife/safari, and more).
  • find_bird_species: look up a bird species (IUCN status, best months, top provinces) and the stays where hosts have recorded it.
  • find_species: look up a mammal, tree, plant, marine, or reptile species and the stays where hosts have recorded it.
  • compare_stays: compare 2 to 4 shortlisted stays side by side with a map.
  • get_property_details: full details for one property, including amenities, units, bird and nature species, biomes, wildlife highlights, and the causes it supports.
  • check_availability / get_availability_alternatives: real-time availability and indicative pricing, with nearby/date alternatives when a stay is full.
  • plan_trip, search_along_route, suggest_itinerary: build a multi-stop trip and route between points.
  • get_causes_supported: list the conservation and community causes on the platform.
  • create_booking_link: generate a direct booking URL on spekboom.org (no payment is executed here; the user completes the booking on the site).

Everything above needs no account or sign-in. Two tools are gated behind optional OAuth (see Authentication & scopes): create_booking_request sends a booking request on the signed-in guest's behalf, and list_my_bookings reads their own bookings. Spekboom is request-to-book: a request is never confirmed until the host accepts, and payment always completes on spekboom.org, never inside the connector. create_booking_link remains the no-sign-in path: it hands the user a prefilled URL to finish on the site.

Hosts have a separate, fully authenticated connector at https://mcp.spekboom.org/host for managing their own listings, calendars, and pricing (scopes host:read / host:write).

Add to Claude.ai

  1. Open Claude.ai → Settings → Connectors.
  2. Click Add custom connector.
  3. Name: Spekboom
    Server URL: https://mcp.spekboom.org/mcp
  4. Save. Claude will run the initialize handshake (should complete under 2s).
  5. In a new chat, try: "find spekboom stays near Prince Albert for 2 guests in May that support rhino conservation".

No OAuth, API key, or account is required for the discovery and planning tools; they use public accommodation data. If you ask Claude to send a booking request for you, it will offer a Spekboom sign-in and request the scoped permissions described under Authentication & scopes.

Add to ChatGPT

ChatGPT connects to the same endpoint. Until Spekboom is listed in the ChatGPT directory, add it yourself: in ChatGPT open Settings, then Apps, turn on developer mode under Advanced settings, and create an app with the URL https://mcp.spekboom.org/mcp and no authentication.

Start a new chat, pick Spekboom from the tools menu and try: "find a fynbos stay near Hermanus for two adults next weekend". Same rate limits and privacy rules apply as for Claude, see below.

Add to Gemini CLI

The Gemini CLI reads MCP servers from ~/.gemini/settings.json. Add Spekboom as an httpUrl entry:

{
  "mcpServers": {
    "spekboom": {
      "httpUrl": "https://mcp.spekboom.org/mcp"
    }
  }
}

Restart the Gemini CLI and the Spekboom tools appear alongside your other tools. Try: "use spekboom to find farm stays near Prince Albert for 2 guests". Same rate limits and privacy rules apply as for Claude, see below.

For Vertex AI Agent Engine or custom Gemini apps using the google-genai SDK, register https://mcp.spekboom.org/mcp as a streamable-HTTP MCP tool source, no auth headers required for the discovery tools.

Tools

search_stays: Search regenerative stays

Extract a concrete location (city, town, or region) from the user message. At least one semantic filter is required (location, query, cause, experience_type, bird_friendly, agri_tourism_attributes, amenity_slugs, or features). Calls without any of these return an empty envelope with a browse link. Thematic queries like birding, stargazing, wine farms have dedicated filters; free-text intent (e.g. 'off-grid retreat') is ranked by a local pgvector embedding search. Returns up to 25 matching stays with cause tags and direct URLs.

Inputs
  • location: City, town, or region (e.g. "Prince Albert", "Western Cape"), one of the required semantic filters
  • check_in / check_out: YYYY-MM-DD (optional)
  • guests: integer 1 to 40 (optional)
  • cause: cause slug or category (wildlife, habitat, community, culture, climate)
  • experience_type: category slug (e.g. "farm-stays", "eco-retreat")
  • bird_friendly: true → BirdLife SA verified bird-friendly stays (use for any birding / avi-tourism query)
  • agri_tourism_attributes: string[]: e.g. ["wine-production"], ["apiculture"] (bee-keeping), ["horse-riding"], ["fly-fishing"], ["bird-friendly"]
  • amenity_slugs: string[]: overlaps match. e.g. ["pool", "fireplace", "self-check-in"]
  • features: string[]: visual/image-tag features. e.g. ["ocean_view", "mountain_view"]
  • max_price_per_night: Number in ZAR (optional)
  • limit: 1 to 25, default 10
Example request
POST https://mcp.spekboom.org/mcp
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "search_stays",
    "arguments": { "location": "Karoo", "guests": 2, "limit": 5 }
  }
}
search_along_route: Multi-stop trip planner

Plan a journey between two locations with optional waypoints. Returns bookable stays grouped by stop, each within a configurable radius. Great for road trips.

Inputs
  • start_location: City, town, or region, required
  • end_location: City, town, or region, required
  • waypoints: Up to 5 intermediate stops (optional)
  • radius_km: Search radius around each stop, 1 to 200, default 50
  • check_in / check_out: YYYY-MM-DD (optional)
  • guests: integer 1 to 40 (optional)
  • cause: cause slug or category (optional)
  • max_per_stop: 1 to 10 stays per stop, default 3
Example request
{
  "jsonrpc": "2.0", "id": 6, "method": "tools/call",
  "params": {
    "name": "search_along_route",
    "arguments": {
      "start_location": "Cape Town",
      "end_location": "Port Elizabeth",
      "waypoints": ["Prince Albert"],
      "guests": 2,
      "max_per_stop": 3
    }
  }
}
get_property_details: Full property details

Fetch every public detail for a single accommodation, including amenities, units, host, and supported causes. Provide property_id OR slug.

Inputs
  • property_id: UUID (prefer when known)
  • slug: URL slug (e.g. "karoo-cottage")
Example request
{
  "jsonrpc": "2.0", "id": 2, "method": "tools/call",
  "params": {
    "name": "get_property_details",
    "arguments": { "slug": "karoo-cottage" }
  }
}
check_availability: Real-time availability + price

Returns whether the property is bookable for the dates + guests, along with total cost breakdown. Dates must be YYYY-MM-DD, checkout strictly after checkin.

Inputs
  • property_id or slug: one is required
  • check_in / check_out: YYYY-MM-DD, required
  • guests: integer 1 to 40, required
Example request
{
  "jsonrpc": "2.0", "id": 3, "method": "tools/call",
  "params": {
    "name": "check_availability",
    "arguments": {
      "slug": "karoo-cottage",
      "check_in": "2026-05-10",
      "check_out": "2026-05-13",
      "guests": 2
    }
  }
}
get_causes_supported: Conservation & community causes

List the causes that Spekboom bookings fund, optionally filtered by category or location.

Inputs
  • category: animal-welfare | community | conservation | education | environmental | …
  • location: Free-text location filter (optional)
Example request
{
  "jsonrpc": "2.0", "id": 4, "method": "tools/call",
  "params": {
    "name": "get_causes_supported",
    "arguments": { "category": "conservation" }
  }
}
create_booking_link: Generate a booking URL

Constructs a direct URL to spekboom.org prefilled with property, dates, and guests. The user completes payment on the site. This tool does NOT move money.

Inputs
  • property_id or slug: one is required
  • check_in / check_out: YYYY-MM-DD, required
  • guests: integer 1 to 40, required
Example request
{
  "jsonrpc": "2.0", "id": 5, "method": "tools/call",
  "params": {
    "name": "create_booking_link",
    "arguments": {
      "slug": "karoo-cottage",
      "check_in": "2026-05-10",
      "check_out": "2026-05-13",
      "guests": 2
    }
  }
}

Host connector

Hosts manage their own listings from a separate connector at https://mcp.spekboom.org/host. Every user signs in with their Spekboom host account through OAuth before any tool is available (scopes host:read and host:write). Each tool acts only on listings the signed-in host owns or co-manages, and write tools also check that co-host's permissions on the listing. The connector cannot take payment from guests, send invoices, change payout details or listing ownership, or take a listing off Spekboom.

To add it in Claude.ai: Settings → Connectors → Add custom connector, URL https://mcp.spekboom.org/host, then sign in with your Spekboom account and choose Allow.

Read tools (22)

  • list_my_listings

    List all accommodations the authenticated host owns or co-hosts, with their id, name, slug and published status.

  • list_units

    List the host's units with their current pricing — base nightly rate, additional-person fee, weekend rate, currency and pricing_mode ('guest_pays' is the price the guest sees; 'you_earn' is what the host nets).

  • get_bookings

    List the host’s bookings within a date range.

  • get_availability

    List the blocked and booked date ranges for one of the host’s accommodations (or a single unit) over a date window.

  • get_calendar_view

    Per-day calendar cells for the host's units over a date range (max 90 days).

  • list_blocks

    List the host's calendar blocks with their ids, dates, reason and source.

  • get_pricing_calendar

    Effective per-night price for each unit over a date range (max 90 days), read from the same rails the booking engine quotes and charges guests from.

  • list_special_pricing

    List the host's special-pricing overrides from the rail the booking engine actually charges (unit_rate_overrides — includes rows created via this MCP and via the host pricing UI).

  • get_pricing_rules

    Read the FULL pricing surface for an accommodation.

  • get_payment_stats

    Summarise the host’s payouts from Spekboom’s own payout records, the same figures as Your wallet on the Payouts page: what has been paid to them, what is still waiting to be paid (on_hold is the part of it being checked before release), the next payout day and amount, and each place’s share.

  • get_referral_stats

    Summarise the host’s referral performance: each referral link with its clicks, bookings and the booking revenue it brought in, the totals across all links, and the referral commission earned, split into paid and still owed.

  • get_impact_stats

    Summarise the conservation impact driven by the host’s bookings, total donated to causes, the number of donating bookings, and a per-cause breakdown.

  • get_channel_health

    Report the channel-sync health for one of the host’s accommodations — every connected calendar (Airbnb, Booking.com, etc.), its last sync time and health state.

  • list_channels

    List every channel connection on the host's accommodations — iCal feeds (Airbnb, Booking.com, VRBO, etc.) and channel integrations (RoomRaccoon, Nightsbridge, etc.) — with their ids, status and last-sync info.

  • list_sync_history

    Recent channel-sync events for the host (newest first) — each event records the channel, its accommodation/unit, timestamp, status, how many events were found/upserted/removed, and any error message.

  • list_photos

    Lists the gallery photos for one of the host's accommodations or units.

  • get_photo_upload_link

    Gives the host a link to add photos from their own phone or computer, for one of their accommodations or one room (unitId).

  • get_demand_insights

    Show what guests are searching for near the host’s listings — top searched locations, themes, and causes, plus UNMET demand (searches that found nothing available).

  • get_listing_visibility

    For one of the host’s listings, show guest demand in its area (nearby searches + how many found nothing available) and concrete, grounded improvement tips derived from the listing’s own data — photo count, amenities tagged, and price vs the nearby median.

  • get_website

    Get the accommodation website-builder config: template, sections (enabled/order), theme_config, SEO, publish status, and live/preview URLs.

  • list_website_templates

    List accommodation website templates available in the Spekboom website builder (editorial family).

  • get_website_subscription

    Check whether this accommodation can publish a website (active Standard/Premium subscription on the host or a co-owner).

Write tools (23)

These change the host's own data and are marked as write (and, where they overwrite or remove something, destructive) in their tool annotations.

  • trigger_channel_sync

    Force an immediate sync of one iCal channel by id (Airbnb, Booking.com, VRBO, etc.).

  • set_channel_enabled

    Pause or resume an iCal channel's syncing (Airbnb, Booking.com, etc.).

  • block_dates

    Block or unblock a date range for the host.

  • update_block

    Update a manual calendar block (start_date / end_date / reason / description / notes).

  • delete_block

    Delete a manual calendar block.

  • set_special_pricing

    Create a special-pricing override for a date range on the rail the booking engine actually charges (unit_rate_overrides — the same rows the host pricing UI edits and guest quotes/checkout read).

  • remove_special_pricing

    Delete a special-pricing override by id from the rail the booking engine actually charges (unit_rate_overrides).

  • set_discount_rules

    Upsert accommodation-level discount rules.

  • confirm_pending_booking

    Accept a pending booking request.

  • create_draft_booking

    Pencil in an UNCONFIRMED draft booking — it holds the dates on the host calendar but sends no guest email and takes no payment.

  • extend_booking

    Extend (or shorten) a confirmed booking's check-in / check-out dates.

  • move_booking_to_unit

    Move a confirmed booking to a different unit at the SAME accommodation.

  • edit_listing

    Edit allowlisted listing fields.

  • set_amenities

    Add or remove amenities on an accommodation or a specific unit, addressed by slug (e.g.

  • set_causes

    Replace the listing's featured conservation causes with the given set, addressed by slug.

  • set_birds

    Replace the listing's recorded bird species (Go Birding) with the given set.

  • set_nature

    Update the listing's nature section: `species` (non-bird wildlife/flora slugs or names → nature_species), `biome_slugs` (SANBI habitat slugs), and/or `wildlife_highlights` (aggregates like 'big-five').

  • manage_photos

    Changes the gallery photo order, cover photo or caption, or removes a photo, for one of the host's accommodations or units.

  • add_photos

    Adds photos to the gallery of one of the host's accommodations, or of one room (unitId), from web links: the host's own website, a Google Drive file shared with anyone who has the link, a Dropbox link, or any direct photo link.

  • create_draft_invoice

    Create a DRAFT invoice for a guest from an existing booking.

  • save_website

    Save (upsert) accommodation website-builder draft config.

  • publish_website

    Publish the accommodation website draft to a live Spekboom subdomain (Vercel deploy).

  • unpublish_website

    Take the accommodation website offline (deploys an unavailable page to the subdomain and sets is_published=false).

Authentication & scopes

The connector supports OAuth 2.1 with PKCE and dynamic client registration, so an agent can request exactly the access it needs and nothing more. Anonymous use covers all discovery tools; a bearer token unlocks the gated tools listed below.

  • guest:read

  • guest:write

  • host:read

    Read the host's listings, calendar and bookings (host connector)

  • host:write

    Edit listings, block dates and manage the host's calendar (host connector)

Standard discovery endpoints:

  • Authorisation server metadata (RFC 8414): https://www.spekboom.org/.well-known/oauth-authorization-server
  • Protected resource metadata (RFC 9728): https://mcp.spekboom.org/.well-known/oauth-protected-resource/host
  • Dynamic client registration (RFC 7591): https://www.spekboom.org/api/oauth/register
  • Token endpoint: https://www.spekboom.org/api/oauth/token

Tokens are short-lived (1 hour) with refresh tokens; clients are public (PKCE, no client secret). Requesting a scope outside the four above is refused rather than silently stripped.

Limits & fair-use

  • 60 requests per minute per IP.
  • 500 requests per day per IP.
  • A global daily quota also applies to protect service quality.
  • Exceeding a limit returns a 429 with a Retry-After header.
  • The connector is intended for real-time, user-driven conversational use with Claude. Bulk scraping, competitive pricing harvesting, and automated redistribution of listing data are not permitted and may result in your IP being blocked.
  • Abuse or sustained high-volume programmatic use may trigger the global kill switch; we'll restore service as soon as the pattern is mitigated.

Privacy

  • Discovery tools require no authentication and involve no account linkage. The two OAuth-gated tools act only on the signed-in guest's own data, within the scopes they approved, and access can be revoked at any time (email support@spekboom.org if you need a grant removed).
  • We log each tool call (tool name, salted hash of the input, salted hash of the IP, response time, success or error code, and the account ID on signed-in calls) for abuse detection and quality metrics, and delete the log after 90 days. Raw IPs and raw inputs are not stored in it.
  • Searches also record their shape (destination, dates, party size, cause or theme, result count) with no IP or account attached, so hosts can see demand in their area. The connector never receives your conversation or assistant memory.
  • See the full privacy policy and terms of service.

Troubleshooting

"Couldn't reach the MCP server" when adding the connector

The server may be warming up. Wait 30 seconds and retry. If it persists across several attempts, confirm the endpoint https://mcp.spekboom.org/mcp is reachable (POST only; a GET is refused with not-found or method-not-allowed, which is expected).

"The search tool is throwing errors"

Usually an over-specific query. search_stays now returns { results, count, message? }, an empty resultsarray with count: 0 and a message means the query was valid but matched nothing. Try a broader location or remove filters.

429 Too Many Requests

Rate limit hit. Honour the Retry-After header. If legitimate high-volume use is needed, email support@spekboom.org.

Bookings aren't going through

This connector doesn't process payments. create_booking_linkreturns a URL; users complete the booking and payment on spekboom.org.

Support

Questions, abuse reports, or integration help: support@spekboom.org.

This connector is operated by Spekboom. We control both the MCP endpoint and the underlying platform APIs it reads from.