Developer Resources

MCP Server for RealtyIQ Data

Machine-readable access to Kolkata’s RERA-verified project database for AI agents, IDE assistants and automations. Query live project, locality, market and lead data — or drive content and lead workflows — over the Model Context Protocol.

Endpoint

POST https://www.realtyiq.tech/api/mcp

JSON-RPC 2.0 over HTTP POST (Streamable HTTP transport) · Bearer auth · 27 tools

Quick Start

The server speaks JSON-RPC 2.0 over plain HTTP POST. Four methods are supported: initialize · ping · tools/list · tools/call. Single messages and batch arrays (up to 16) are accepted; notifications — messages without an id, e.g. notifications/initialized — are acknowledged with HTTP 202 and no body. Supported protocol versions: 2024-11-05, 2025-03-26, 2025-06-18.

Every request needs a Bearer key (see Authentication below). Start with a handshake:

bash — initialize handshake

curl -s https://www.realtyiq.tech/api/mcp \
  -H "Authorization: Bearer <YOUR_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-06-18",
      "capabilities": {},
      "clientInfo": { "name": "my-agent", "version": "1.0.0" }
    }
  }'

response (abridged)

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2025-06-18",
    "capabilities": { "tools": { "listChanged": false } },
    "serverInfo": {
      "name": "realtyiq",
      "version": "1.0.0",
      "title": "RealtyIQ — Kolkata real-estate intelligence"
    },
    "instructions": "RealtyIQ MCP server. Read tools query live project/locality/rate/keyword/lead data; …"
  }
}

bash — list the tools your key can see

curl -s https://www.realtyiq.tech/api/mcp \
  -H "Authorization: Bearer <YOUR_KEY>" \
  -H "Content-Type: application/json" \
  -d '{ "jsonrpc": "2.0", "id": 2, "method": "tools/list" }'

json — MCP client config (Claude Desktop, Cursor, etc.)

{
  "mcpServers": {
    "realtyiq": {
      "url": "https://www.realtyiq.tech/api/mcp",
      "headers": { "Authorization": "Bearer <YOUR_KEY>" }
    }
  }
}

Authentication

Two key tiers are issued by Vision Realtors — request one via contact@realtyiq.tech. Send the key with every request; keys are compared in constant time and key values are never published on this site. Scope is enforced server-side: read keys never see action tools in tools/list, and tools/call attempts against them are rejected and audited.

Key tier	Scope	Tools	Intended for
Full key	Read + write	all 27 tools	The owner’s autonomous agents — content pipeline, lead ops, alerts, SEO
Read key	Read-only	17 read tools	Chat and analysis agents — catalog, market, rates, amenities queries

http — the only auth header you need

Authorization: Bearer <YOUR_KEY>

Never embed a full key in client-side code or public repositories. Rate limit: 200 requests per hour per key — every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers, and every call (including rejections) is written to the audit log with its key scope.

Read Tools Reference

available to every key

Tool	Description
get_projects	Active projects with pricing, configurations, RERA and locality; filter by locality, config and price range (INR).
get_project	Full detail for one project by slug: pricing table, RERA, amenities, payment schedule, highlights, possession and editorial data.
get_localities	All localities with PSF data, growth metrics, zone and sub-localities.
get_locality	One locality by slug: PSF / growth / zone facts, amenities with distances and active projects.
get_market_data	Per-locality market data: PSF stats from live offerings, price ranges, rental-yield and appreciation notes, inventory counts.
get_rates	Current partner-bank home-loan rates plus West Bengal stamp duty and registration rules.
get_amenities	Amenities for a locality (schools, hospitals, malls, metro…) with a type filter; distances approximated from coordinates.
get_keywords	The 10,000+ keyword SEO universe: status, category, volume, difficulty and current ranking. Untargeted = the content queue.
get_seo_data	Search-performance data from GSC snapshots: impressions, clicks, average position, top movers and striking-distance quick wins.
get_leads	Recent leads with status, source, score, intent, budget and project; filter by age and status.
get_lead_stats	Lead analytics: counts by status / source / temperature, conversion rate and the hot-lead list.
get_content_performance	Article and content metrics: counts by status and category, views, top-viewed articles, recent publications.
get_content_gaps	Questions real visitors asked that the chatbot could not answer well — ranked opportunities for new articles.
get_question_clusters	Clustered visitor questions from the daily analytics run: counts, example phrasings and the intent currently matching.
get_user_preferences	Stored preferences for an anonymous chat session: budget, config, locality, viewed and shortlisted projects. No PII is ever stored.
get_site_health	Live site health: probes key public routes and sitemaps with status and latency, plus a database ping.
get_approval_status	Status of an approval-gated action: pending, approved, rejected, expired, executed or failed.

Read tools never mutate data. Responses are shaped for LLM consumption — trimmed fields, capped result sizes, JSON columns parsed back into objects, payload capped so a tool response never explodes the context window.

Action Tools Reference

full key only

Tool	Description	Execution
create_article	Create an article draft in the Content Studio (title, body, category, keywords, internal links, FAQ schema).	Approval gate
update_article	Update an existing article's title, excerpt, body, tags, category or pipeline status.	Approval gate
update_page_seo	Update a page SEO title / meta description (quick-win optimisation) on supported pages.	Approval gate
suggest_data_update	Suggest a data correction (bank rate, PSF, possession date…) with current value, suggested value and source.	Approval gate
create_lead	Create a lead from a chat conversation (CREATE-only, same trust level as the public form; dedupes on phone + project).	Immediate
respond_to_lead	Send a personalised auto-response email to a lead through the email pipeline.	Immediate
queue_followup	Schedule a sales follow-up: creates a task for the team and sets the lead's next follow-up date.	Immediate
update_lead_score	Update a lead's quality score (0–100) with a reason.	Immediate
send_alert	Send an urgent Telegram alert to the owner: site down, hot lead, broken route, anomaly.	Immediate
publish_daily_report	Send the daily report to the owner on Telegram: SEO deltas, content, leads, health.	Immediate

Approval-gated tools never execute on call. create_article, update_article, update_page_seo and suggest_data_update create an approval request that is routed to the owner on Telegram — the side effect runs only after explicit approval. Poll get_approval_status with the returned approvalId for the outcome. The remaining action tools execute immediately (audit-logged), and no tool can delete anything — the surface is CREATE + UPDATE only.

Calling a Tool

tools/call takes a tool name and an arguments object (schema shown per tool in tools/list). Results follow the MCP shape — { content: [{ type: 'text', text }], isError? } — where text carries the JSON payload. Tool-level failures (bad input, not found) return isError: true with HTTP 200; protocol errors use JSON-RPC error objects.

json — request: get_project

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "get_project",
    "arguments": { "slug": "vinayak-21-acres" }
  }
}

json — response (abridged)

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{ \"project\": { \"slug\": \"vinayak-21-acres\", \"name\": \"Vinayak 21 Acres\", \"developer\": \"Vinayak Group\", \"locality\": \"New Town\", \"city\": \"Kolkata\", … }, \"offerings\": [ … ], \"rera\": { \"wbreraRegNo\": \"…\" }, … }"
      }
    ]
  }
}

Keyless Alternative — the Data API

Don’t need an MCP client? These public endpoints serve the same RERA-verified data with no authentication — good for lightweight integrations, spreadsheets and one-off scripts.

GET

/api/projects/{slug}/facts

Machine-readable project facts — pricing, RERA, geo, possession, FAQs — edge-cached for an hour. The same payload AI engines cite.

GET

/api/catalog

The full filterable project catalog: every active listing with pricing, configs, RERA and locality.

GET

/api/localities

Locality list and detail with zones, sub-localities and PSF facts (?zone=, ?q=, ?slug=).

bash — project facts, no key needed

curl -s https://www.realtyiq.tech/api/projects/vinayak-21-acres/facts

Operational Notes

Rate limits

200 requests/hour per key (sliding window). Exceeding it returns HTTP 429 with a retry hint; X-RateLimit-* headers are on every response.

No DELETE

The tool surface is CREATE + UPDATE only — no tool can delete projects, articles, leads or data, by design.

Audit trail

Every call is written to the audit log with tool, input, outcome, duration and the caller's key scope (full / read).

Auth errors

Missing or invalid Bearer keys get HTTP 401; the read key is rejected (tool error) on any action tool.