MCP Server

WedStay provides a remote MCP (Model Context Protocol) server that gives AI assistants direct access to wedding venue search, real pricing, vendor discovery, and booking — all without requiring an API key for read operations.

MCP Endpoint:

https://www.thewedstay.com/api/ai/mcp

Connect your AI assistant

Claude Desktop

Add WedStay to your Claude Desktop configuration:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "wedstay": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://www.thewedstay.com/api/ai/mcp"]
    }
  }
}

Restart Claude Desktop after saving. You should see WedStay tools in the tools list.

Claude Code

Add to your project's .mcp.json:

{
  "mcpServers": {
    "wedstay": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://www.thewedstay.com/api/ai/mcp"]
    }
  }
}

Cursor

Add to your Cursor MCP settings (.cursor/mcp.json in your project or global settings):

{
  "mcpServers": {
    "wedstay": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://www.thewedstay.com/api/ai/mcp"]
    }
  }
}

Streamable HTTP (modern clients)

If your MCP client supports Streamable HTTP natively (no mcp-remote bridge needed):

{
  "mcpServers": {
    "wedstay": {
      "url": "https://www.thewedstay.com/api/ai/mcp"
    }
  }
}

Available tools

The MCP server exposes 16 tools (plus 3 guided prompts) to AI assistants.

Every tool carries readOnlyHint, destructiveHint, openWorldHint and idempotentHint, so a client can tell a lookup from a send before it calls anything. The 14 read tools are marked read-only. The two write tools are marked not read-only, not destructive, not idempotent and open-world: each call creates a real lead that reaches people outside the conversation, and it deletes or changes nothing. Their descriptions start with "Creates a real lead; requires the user's explicit go-ahead."

Every tool also declares an outputSchema. A result that is not an error carries structuredContent that matches it, next to a text block. The text block of every tool is what it was before, so a client that reads only text sees no change.

A search that matches nothing returns an empty list in structuredContent, not an error. A lookup by a slug that does not exist (get_venue, get_vendor, get_blog_post) is an error result that says so in its own sentence.

Read tools (no authentication required)

Guided prompts

Clients that support MCP prompts (Claude Desktop, Claude Code, Cursor) can offer these as one-click workflows:

Write tools (require valid guest contact info)

Write tools create real leads in WedStay's pipeline. The AI assistant must collect valid guest name, email, and event details, and get the user's explicit go-ahead, before submitting.

Both write tools require sms_consent. Ask the couple: "OK if WedStay texts you about this request?" Send true only if they said yes. With false, WedStay replies by email. The answer is stored with the inquiry, with the time and the source.

Each guest email can submit up to 20 inquiries per hour across both tools. Sending the identical request again within 24 hours reports the first result again, creates no second inquiry, and does not count toward that limit.

Both tools answer in one shape, with a status that says what happened. See Inquiry results.

Example conversations

Once connected, you can ask your AI assistant things like:

• "Find wedding venues in California for 120 guests"
• "How much would a 3-night wedding at an estate in Texas cost for 80 guests?"
• "Show me photographers in the Los Angeles area"
• "What's the starting price for Sidpix Studios?"
• "Submit a booking request for Texas Wedding Village for October 2026"

The AI will use WedStay tools automatically to answer with real, up-to-date data.

Tool reference

search_venues

amenities and budget_max are applied before limit. Any other argument is an error result (isError: true) that names it and lists the valid arguments, for example "Unknown argument 'price_max'. Did you mean budget_max?". This tool is the only one that refuses an argument it does not declare; the other tools ignore one.

Each result includes: slug, name, city, state, country, latitude, longitude, property_type, venue_type, capacity_min (how many the venue sleeps), capacity_max (event capacity), bedrooms, beds, bathrooms, price_range (the base price for the whole minimum stay, not per night, in the venue's listed currency, for example "$5,000 to $6,000 for the 2-night minimum (base, before fees)"), pricing (the same price as structured data: currency, min_nights, weekday_base, weekend_base, extra_night, and starting_total, which is exactly the venue page's "Your WedStay starts at" figure), hero_image (an absolute CDN URL), description, amenities, and a bookable url. gathering_spaces is always null and kept only so the response shape stays stable.

get_venue

Returns the venue with description, seo_description, categories, capacity and room counts, price_range, pricing, amenities, hero_image, photos (up to 5 in gallery order, each { url, category, is_featured }), total_photos, testimonials (guest_name, rating, review, event_date), and the booking url. Photo URLs are absolute CDN URLs, medium-size WebP; the full gallery is on the venue page.

calculate_pricing

Returns typed structuredContent agents can render as comparison tables. Every result has source (venue_engine or regional_model), currency, total, nights, breakdown, summary, calculator_url and attribution.

With a slug (source: venue_engine):

• total is the venue page calculator's total for those inputs, in the venue's listed currency (euro venues in euros, never converted; Australian venues in Australian dollars, rounded up to the nearest 100 as on the page). Called with only a slug, it equals the venue page's "starts at" figure
• breakdown = { base, additional_nights, extra_guest_charges, cleaning_fee, service_fee, tax, security_deposit } (the deposit is refundable and not part of the total)
• venue = { slug, name, min_nights, url }, plus the event_type, event_guests, overnight_guests used and rate_date for converted prices
• A venue with no itemized pricing, or inputs past its capacity or minimum stay, returns an error that says so

Without a slug (source: regional_model, always USD):

• estimated_total (same as total), per_night_average (the total divided by nights: an average for comparison, not a nightly rate any venue charges; per_night is a deprecated alias with the same value until 2027-01-06)
• price_range = { low, high, label }
• breakdown = { base_venue, cleaning_fee, event_guest_charge, overnight_guest_charge, additional_nights, season_adjustment, service_fee, tax }
• comparison_vs_traditional = { traditional_estimate, savings_dollars, savings_percent, note }, or null for regions without a traditional-cost baseline (most international and some newer US markets)
• parameters (echoed inputs, includes region_id and venue_type_label)

search_vendors

Each result includes: slug, business_name, tagline, service_category, service_subcategories, primary_city/state, bio, starting_price, price_unit (per_person · per_event · per_hour · per_item), years_in_business, weddings_completed, specialties, featured_image_url (the vendor's primary photo), logo_url (reserved, currently null), is_affiliate_only, affiliate_link, and a profile url. get_vendor adds pricing_structure, service_areas, website, instagram, facebook, tiktok, photos (up to 5, primary first, each { url, category, alt_text }), total_photos, portfolio_description, vendor_policies (booking, payment, cancellation, timeline, insurance), average_rating, and review_count.

Vendor photo URLs are absolute CDN URLs: the medium-size WebP when one has been generated, otherwise the original image. The full portfolio is on the vendor's profile page.

Affiliate-only vendors: when is_affiliate_only is true, the vendor takes no inquiries through WedStay, and submit_vendor_inquiry creates no lead for it. structuredContent says status: "affiliate_only" and carries the vendor's affiliate_link. The text block, which older clients read, still carries the affiliate_only_vendor code as error. Direct the user to affiliate_link instead. When it is null, message points to the vendor's WedStay page.

get_vendor

list_vendor_categories

No parameters. Returns categories[], each { name, slug, vendor_count } for the active vendors in it. Use name as the exact category value for search_vendors.

search_inspiration

Returns photos[] (each with image_url, alt, the venue or vendor it was shot at as source_type, source_name, source_slug, city, state and source_url, plus its styles, settings, colors, moods and season tags), total, and next_offset (null on the last page).

submit_venue_inquiry

submit_vendor_inquiry

Inquiry results

Both inquiry tools answer in one shape. structuredContent always has these four fields:

No result carries the guest's name, email or phone.

Two outcomes are error results (isError: true) with their own sentence and no structuredContent, not statuses:

• submit_vendor_inquiry when WedStay's database refuses to store the inquiry: "Failed to submit vendor inquiry. Please try again." Nothing was stored, so trying again is a fresh attempt.
• A request that conflicts with a different one already recorded under the same request key: "A different booking request is already recorded for this guest and venue. Change the details or wait before retrying." or "A different inquiry is already recorded for this guest and vendor. Change the details or wait before retrying." The text block beside structuredContent is what it was before this release, for older clients that read only text. For submitted it is JSON with inquiry_id, status and message. For an affiliate-only vendor it is JSON with error: "affiliate_only_vendor", message and affiliate_link. For the other four statuses it is the message sentence.

search_blog_posts

Each result includes: slug, title, excerpt, feature_image, published_at, reading_time, tags[], primary_author, and url.

get_blog_post

Returns plaintext body for token-efficient agent consumption: slug, title, feature_image, excerpt, published_at, reading_time, word_count, tags[], primary_author, content_plaintext, url.

list_blog_tags

No parameters. Returns tags[], each { slug, name, post_count }, sorted by post count descending, plus total. Use to discover valid tag filters for search_blog_posts.

get_cost_benchmarks

Optional state, venue_type (estate, villa, ranch, mansion), and country. Returns benchmarks[] with scope, label, median_base_per_stay, typical_low_base_per_stay, typical_high_base_per_stay, converted_from, and listings, plus currency (always USD), fx ({ eur_to_usd, rate_date }, the rate applied to euro-priced listings), as_of, note and source_url. Called with no arguments, it returns the full national, per-state, per-venue-type, and per-country breakdown. Each figure is the base price for exclusive use of the whole estate covering its minimum stay (usually 2 nights), not per night, before cleaning, service fee, and tax. The median_nightly, typical_low_nightly and typical_high_nightly keys are deprecated aliases with the same values, kept until 2027-01-06; they were never nightly rates. A filter with too few live listings to report (a state or country needs at least 3) returns an empty benchmarks[] and says so in note.

get_regional_cost_ranges

Optional slug (an exact region slug such as california, los-angeles, costa-rica), state (a state name, a USPS code, or a destination country), city, season (spring, summer, fall, autumn, winter, a month name such as June, or a month number 01-12), and guests (1-2000). One of slug, state or city is required.

Returns the region's published whole wedding budget range (range), the guest count that range is built on (average_guest_count), its seasonal_multipliers and day_of_week_multipliers, the months in each season (popular_seasons), the resolved season, and scaled (that range moved by the guest count and season multipliers). coverage says how complete the data is: calculator (the region's own multipliers), parent_state (a city using its state's multipliers) or insights_only (a published range with national fallback multipliers).

basis says how the range was arrived at: modelled or authored. Ranges on different bases are not comparable, so do not rank or average one against the other. range.modelled is true on a modelled range and absent on a hand authored one. basis is absent when covered is false.

season.unclassified is true when none of the season's months appear in that region's own season lists, so the shoulder rate is a fallback rather than a classification. California is the live case: it names no summer month, so June, July and August price at the shoulder rate. Say so rather than implying summer was priced.

A region with no data returns covered: false and covered_regions, the full list of regions that do have data. It never substitutes a neighbouring region or a national average. A call with no region, or a season that is not a season or month, also returns covered: false, with the reason in note.

These figures are a market range for the region and an estimate, never a quote and never the price of a specific venue.

compare_venues

Requires slugs (an array of 2 to 4 venue slugs from search_venues). Returns a venues[] side-by-side of event capacity, sleeping capacity, bedrooms, bathrooms, price range, location, type, hero image, and booking URL, in the order requested, plus found and requested counts. Slugs that do not match a published venue are skipped; if none match, venues is empty and found is 0.

search_wedstay_knowledge

Requires query (3 to 300 characters, the question in the couple's own words). Optional limit (1 to 10, default 5). Returns data[] of the closest sections of WedStay's own authored planning notes, each with title (the note), heading (the section), body (verbatim), kind, slug and a fusion score, plus the echoed query, as_of and note. degraded is text_only when the semantic half of the search was unavailable and only word matching ran.

The notes cover how booking works, tours and the tour deposit, cancellations and refunds, property rules (noise, decor, alcohol, pets, children), insurance and the vendor certificate of insurance, the Collective vendor network and WedStay One. Quote what comes back rather than paraphrasing a policy into a promise. It is never a price for a specific venue (calculate_pricing) and never availability.

How it works

The WedStay MCP server uses the Streamable HTTP transport. One endpoint serves MCP protocol revision 2026-07-28 and the earlier revisions 2025-11-25, 2025-06-18, 2025-03-26 and 2024-11-05.

The server is stateless on every revision. It issues no session id, and each request is a separate HTTP POST that stands on its own. GET and DELETE answer 405 with a JSON-RPC error (-32000, "Method not allowed.") as application/json, because there is no stream to open and no session to close. The server advertises no list change notifications for tools or prompts, because its tool and prompt lists do not change while it runs.

Whichever revision a client speaks, read tools return structured JSON from WedStay's live venue, vendor, and pricing data, and write tools (inquiries) create real leads that flow into WedStay's booking pipeline.

Earlier revisions (2025-11-25 and before)

1. The client sends an initialize request that names its protocol revision
2. The server answers with the revision it will speak and its capabilities (tools and prompts)
3. The client lists and calls tools as needed

The handshake is not required. A tools/call sent with no initialize before it is answered too.

Replies come back as a server-sent event stream that carries one JSON-RPC message. A client whose Accept header does not list both application/json and text/event-stream gets that message as one plain JSON document instead.

Revision 2026-07-28

There is no handshake. Every request carries a _meta envelope inside params that names the protocol revision and the client's capabilities, and repeats the revision and the method in the MCP-Protocol-Version and Mcp-Method headers. A tools/call also repeats the tool name in an Mcp-Name header. Replies are plain JSON.

server/discover returns supportedVersions (the revisions served without a handshake) and the server's capabilities:

curl -X POST https://www.thewedstay.com/api/ai/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "MCP-Protocol-Version: 2026-07-28" \
  -H "Mcp-Method: server/discover" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "server/discover",
    "params": {
      "_meta": {
        "io.modelcontextprotocol/protocolVersion": "2026-07-28",
        "io.modelcontextprotocol/clientInfo": { "name": "my-client", "version": "1.0.0" },
        "io.modelcontextprotocol/clientCapabilities": {}
      }
    }
  }'

A tool call carries the same envelope, next to the tool's name and arguments:

curl -X POST https://www.thewedstay.com/api/ai/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "MCP-Protocol-Version: 2026-07-28" \
  -H "Mcp-Method: tools/call" \
  -H "Mcp-Name: calculate_pricing" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "calculate_pricing",
      "arguments": { "region": "Texas", "event_guests": 80 },
      "_meta": {
        "io.modelcontextprotocol/protocolVersion": "2026-07-28",
        "io.modelcontextprotocol/clientInfo": { "name": "my-client", "version": "1.0.0" },
        "io.modelcontextprotocol/clientCapabilities": {}
      }
    }
  }'

A request that sends the MCP-Protocol-Version: 2026-07-28 header without the envelope, or whose headers do not match its body, is refused with HTTP 400.

Access and rate limits

No API key and no sign in are required. Rate limits are applied per caller instead:

• Up to 600 requests per minute per IP address. Every request to the endpoint counts, not only tool calls. Over the limit, the server answers HTTP 429 with a JSON-RPC error (-32000). This is the only request limit on the endpoint, and its responses carry no X-RateLimit-* headers.
• Up to 20 inquiries per hour per guest email, across both inquiry tools.

A request may still carry a WedStay API key: a value that starts with ws_, sent as Authorization: Bearer, X-API-Key or X-WedStay-Key. The server checks a key it is given, and refuses an unknown or revoked one with HTTP 401 and JSON-RPC error -32001. A valid key changes neither the tools nor the limits. A bearer token that is not a WedStay key is ignored.

What changed in server version 2.0.0

The server now runs on a newer MCP library. Every tool keeps its name and its place in the list. A client may notice these differences:

• Protocol revision 2026-07-28 is served, next to the earlier revisions listed above.
• Three tools take new arguments: search_venues takes budget_max, calculate_pricing takes a venue slug, and both inquiry tools now require sms_consent.
• search_venues refuses an argument it does not declare, with an error result that names it and lists the valid arguments. Before, it ignored one. The other tools still ignore an argument they do not declare.
• Tool schemas declare JSON Schema draft 2020-12. They declared draft-07 before.
• Every tool carries readOnlyHint, destructiveHint, openWorldHint and idempotentHint.
• Every tool declares an outputSchema and returns structuredContent beside its text block. Eight of the 16 had neither before. The text block of every tool is unchanged, so an older client that reads only text sees what it saw before.
• Both inquiry tools return structuredContent with four fields: status, inquiry_id, message and affiliate_link. status is one of submitted, in_progress, rate_limited, not_found, affiliate_only and unconfirmed. For an affiliate-only vendor the structured field is status: "affiliate_only", and the text block still carries the affiliate_only_vendor code.
• Tools no longer list an execution key.
• Two inquiry answers that were plain text are now error results (isError: true), with the same sentences as before: a vendor inquiry that WedStay's database refuses to store, and a request that conflicts with one already recorded. A vendor inquiry whose outcome is unknown, for example because the connection was lost while it was being stored, now answers status: "unconfirmed" instead, as the venue tool does when it cannot confirm a request.
• The server no longer advertises list change notifications for tools or prompts, because its tool and prompt lists do not change while it runs. This holds on every revision: the initialize result of the earlier revisions advertised them before this release, and server/discover on 2026-07-28 does not advertise them either.
• A call to a tool name that does not exist is answered with a JSON-RPC error (-32602). It was an error result before. Arguments that a tool rejects are still an error result (isError: true).
• JSON that is not a JSON-RPC message is answered with -32600. It was -32700 before.
• A request body that is not JSON is answered with HTTP 400 and a parse error (-32700). Before, it got no answer.
• GET and DELETE still answer 405 with the same JSON-RPC error body, now sent as application/json.
• Responses from the MCP endpoint no longer carry the site's X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers, and the site's separate limit of 400 requests a minute, with its own 429 that was plain JSON rather than a JSON-RPC error, no longer applies to it. The endpoint's own limit of 600 requests a minute per IP address is the only one; its 429 is described under Access and rate limits.
• A tool that fails returns one fixed line as an error result (isError: true), the same for every tool: Something went wrong on our side. Please try again in a moment. The raw error text is no longer sent. Results a tool returns on purpose are not replaced: not found, rate limited and invalid arguments read as they did.
• The legacy paths /api/ai/sse and /api/ai/message are no longer served by the MCP server. The endpoint path /api/ai/mcp is unchanged.

Data attribution

Read tool results include an attribution notice. If you're building a product that surfaces WedStay data, please include visible attribution linking back to thewedstay.com.

Terms of use

By connecting to the WedStay MCP server, you agree to our Terms of Service, including Section 31 (API, MCP Server & Developer Access). Key restrictions:

• Real-time queries only — Each tool call must correspond to a specific end-user query. Batch processing and bulk extraction are prohibited.
• No AI training — Do not use WedStay data to train, fine-tune, or develop machine learning models or LLMs.
• No competing products — Do not use WedStay data to build competing venue search or booking services.
• No data harvesting — Do not scrape, store, or build databases from WedStay data.
• Attribution required — Display "Data by WedStay" when surfacing venue or vendor data to end users.