Skip to main content

MCP Server

The Smily MCP server exposes the read-only surface of API v3 over the Model Context Protocol (MCP). It lets AI agents — Claude Code, Claude Cowork, OpenAI Codex, and any other MCP-capable client — discover your account's resources and query them in natural language, without writing any HTTP code.

Think of it as API v3 over MCP: every record you can read through the REST API is reachable through a small set of generic tools, and the responses come back in exactly the same shape as the corresponding API v3 endpoints.

Experimental — tokens available on request

The MCP server is an experimental feature and may change without notice. Access tokens are issued on request — contact Smily to have an MCP token created.

Read-only

The MCP server is read-only. It can list and fetch records, but it cannot create, update, or delete anything. There is no risk of an agent mutating your account's data through it.

Endpoint​

PropertyValue
URLhttps://www.bookingsync.com/mcp
TransportStreamable HTTP (JSON-RPC 2.0)
Server namebookingsync-mcp
Server version1.0.0
Protocol versions2025-06-18, 2025-03-26, 2024-11-05
Health checkGET https://www.bookingsync.com/mcp/health (no auth)

What you get​

  • Four generic tools — api_v3_resources, api_v3_resource_schema, api_v3_list, and api_v3_get — that work across every exposed resource. See Tools.
  • 77 read-only resources — bookings, rentals, clients, rates, reviews, inbox messages, tasks, and more. See Resources.
  • The same filtering, sparse-fieldset, and pagination semantics as API v3, surfaced as tool arguments. See Querying: filters, fields & pagination.
  • Two ways to authenticate — an Authorization: Bearer header or a ?token= URL parameter for clients that cannot send custom headers. See Authentication.
  • Single- or multi-account tokens — a token is either pinned to one account (the common case) or able to operate across several accounts, selecting the active one per request (multi-account is in early access, limited to a few users for now). See Token types & account selection.
  • Scoped, read-only access — every query is scoped to the account it targets; a token can only ever reach accounts it is authorized for.

How an agent uses it​

A typical agent session follows the same discovery-then-query flow a developer would:

  1. Call api_v3_resources once to learn which resources exist.
  2. Call api_v3_resource_schema for a resource to learn its attributes, filterable fields, operators, and relationships.
  3. Call api_v3_list (with filters / sparse fieldsets / pagination) or api_v3_get (by id) to read the data.

You don't have to orchestrate this yourself — the tool descriptions guide the model through it.

Quick start​

  1. Request a token. MCP tokens are issued on request — see Authentication.
  2. Connect a client. Add the server to Claude Code, Claude Cowork, or Codex — or try it quickly with the MCP Inspector. See Connecting clients.
  3. Ask a question. For example: "List the bookings for rental 42 that start after June 2026, newest first, and show me the guest names and final price."
# Confirm the server is reachable (no auth required):
curl https://www.bookingsync.com/mcp/health
# => {"status":"ok","server":"bookingsync-mcp","version":"1.0.0","protocol_version":"2025-06-18"}

Relationship to API v3​

The MCP server is a thin layer over API v3. It reuses the same serializers, the same filtering engine, and the same authorization scoping as the REST API, so:

  • Response payloads are byte-for-byte the same shape as the matching API v3 index/show endpoint.
  • A resource's available attributes and filterable fields match its API v3 serializer.
  • Filtering operators behave identically to API v3's filter[...] query parameters.

If you already know API v3, you already know what the MCP server returns.

Limits​

  • Rate limit: 1,000 requests per hour per token (see Authentication).
  • Page size: limit defaults to 25 and is capped at 100 (see Querying).
  • Read-only: no write tools are exposed.