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–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).

Two tools require signing in with your Spekboom account (OAuth):

create_booking_request: send a booking request to the host. Spekboom is request-to-book: the booking stays pending until the host accepts it, and no payment is taken inside the connector.
list_my_bookings: list the signed-in guest’s own bookings.

Hosts have a separate, fully authenticated connector for managing their own listings, calendars, and pricing.

Add to Claude.ai

Open Claude.ai → Settings → Connectors.
Click Add custom connector.
Name: Spekboom
Server URL: https://mcp.spekboom.org/mcp
Save. Claude will run the initialize handshake (should complete under 2s).
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. The connector uses public accommodation data.

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.

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–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–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–200, default 50
check_in / check_out: YYYY-MM-DD (optional)
guests: integer 1–40 (optional)
cause: cause slug or category (optional)
max_per_stop: 1–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–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–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
    }
  }
}

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

No user authentication is required. There is no account linkage.
We log tool calls anonymously (tool name, salted hash of input, salted hash of IP, response time, success/error code) for abuse detection and quality metrics. Raw IPs and raw inputs are not stored.
No personally identifiable information passes through this connector.
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 will return a 404 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.

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 } } }

{ "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 } } }

{ "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 } } }

{ "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 } } }