CayIQ MCP Data API help

Regions vs counties

region is the MLS's MLSAreaMajor vocabulary, not a county field. Its roughly 65 values mix neighborhoods, towns, and some counties. It is useful for MLS area selection, but it is not a reliable county filter: most Beaufort County listings are tagged with a neighborhood rather than Beaufort.

County-level scoping belongs to CountyOrParish, exposed through the live county parameter. The production feed has the following Active counts:

Live The county parameter narrows results within your key's authorized counties; matching is case-insensitive. It can never widen your scope: counties outside your entitlement are ignored, and a request only for out-of-entitlement counties returns zero rows rather than an error. Your key sees only its authorized subset of the table above.

High-volume verified MLSAreaMajor examples

These are the production values and counts verified for this reference. Fetch the current complete vocabulary with get_area_taxonomies rather than hard-coding a static region list; taxonomy results are limited to your authorized counties.

Call the API from your server

Use the REST tool endpoint at https://api.cayiq.com/api/mcp/tools/<tool> from trusted server-side code. Send the one-time key in the Authorization: Bearer header. Do not put the key in browser JavaScript, a React client component, NEXT_PUBLIC_* environment variables, local storage, a URL, source control, a screenshot, or a support ticket.

Store the key in your deployment secret manager as CAYIQ_MCP_API_KEY. The examples query search_listings; replace the input object only with filters supported above. The county parameter can narrow a key’s scope but can never widen it.

Python

Install the dependency once

python -m pip install requests

Set the key in your server environment, then run this code

import os
import requests

BASE_URL = "https://api.cayiq.com/api/mcp"
API_KEY = os.environ["CAYIQ_MCP_API_KEY"]

def call_tool(tool: str, arguments: dict) -> dict:
    response = requests.post(
        f"{BASE_URL}/tools/{tool}",
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json",
        },
        json=arguments,
        timeout=30,
    )
    response.raise_for_status()
    return response.json()

result = call_tool("search_listings", {
    "status": "Active",
    "county": "Beaufort",
    "min_beds": 3,
    "page_size": 10,
})

# Log safe aggregates, not the credential.
print({"total": result.get("total"), "page": result.get("page")})

JavaScript (Node.js)

Create a local server-only .env file, add it to .gitignore, then run Node with --env-file

# .env (do not commit this file)
CAYIQ_MCP_API_KEY=<your one-time key>

# Run: node --env-file=.env search-listings.mjs

const BASE_URL = "https://api.cayiq.com/api/mcp";
const apiKey = process.env.CAYIQ_MCP_API_KEY;

if (!apiKey) {
  throw new Error("CAYIQ_MCP_API_KEY must be set in the server environment.");
}

async function callTool(tool, arguments_) {
  const response = await fetch(`${BASE_URL}/tools/${tool}`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${apiKey}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(arguments_),
  });

  if (!response.ok) {
    throw new Error(`CayIQ MCP request failed with HTTP ${response.status}`);
  }
  return response.json();
}

const result = await callTool("search_listings", {
  status: "Active",
  county: "Beaufort",
  min_beds: 3,
  page_size: 10,
});

// Log safe aggregates, not the credential.
console.log({ total: result.total, page: result.page });

For protocol-native clients, the same bearer key also works with the JSON-RPC MCP endpoint at https://api.cayiq.com/api/mcp. Start with initialize, then call tools/list or tools/call. The REST examples above are the simplest way to validate a server integration.

Field reliability in responses

Build address displays from StreetName (100% populated) plus City (99.97% populated), and include other address components when available. Do not use UnparsedAddress; it is 0% populated in this feed. For bedrooms use BedroomsTotal (about 80%). For baths use BathroomsFull (about 80%), represented by the API's normalized bathrooms_total; BathroomsTotalInteger is 0% populated. The server returns its normalized fields in lower snake case, including street_name, city, bedrooms_total, and bathrooms_total.

Search, map, and bulk-export rows include an absolute primary_image_url when image media exists. get_listing also includes ordered images[] entries with URL, order, caption, media type, MIME type, and suggested filename. Follow redirects when downloading. URLs always use the CayIQ media proxy; raw OAuth-protected Cotality/Trestle URLs are never returned.