# AVnester for Developers > Indian residential real-estate intelligence as a public Model Context Protocol (MCP) server and REST adapter. 11 tools covering listing discovery, locality insights, and deterministic financial calculators. Coverage: property listings from any city or town in Tamil Nadu; locality insights for the cities AVnester publishes guides for; calculators India-wide — anything else returns supported:false with a scopeMessage. No PII, no chat history, no training on your data. ## Endpoints - MCP protocol: https://mcp.avnester.com/public-mcp - REST adapter: https://api.avnester.com/public/v1/ - OpenAPI 3.1: https://api.avnester.com/public/openapi.json - OAuth 2.1 metadata: https://auth.avnester.com/.well-known/oauth-authorization-server - Source rights: https://api.avnester.com/api/v1/data/provenance/ (keys: rera-tn, tnreginet; guide: https://developers.avnester.com/data-sources) - Status: https://avnester.com/status ## Tools ### search_properties Search residential property listings anywhere in Tamil Nadu, India — any city or town. Use when the user names a place, locality, price band, BHK, or transaction type. Returns sanitized listing cards with handoff URLs and a per-listing verification summary (verified + caveats); never returns seller contact details. Places outside Tamil Nadu return supported=false + scopeMessage — surface it. - Required args: none - Endpoint: https://api.avnester.com/public/v1/search_properties ### get_property_details Fetch the public detail view for a single listing by listingId. Returns sanitized public fields only (no seller contact). Use when the user has selected a property from a search and wants the full picture before contacting. - Required args: listingId - Endpoint: https://api.avnester.com/public/v1/get_property_details ### compare_properties Compare 2–5 listings (by listingId) side-by-side on objective metrics: price per sqft, age, the RERA ID the seller listed, amenities overlap. Use when the user is choosing between specific properties they have already discovered. - Required args: listingIds - Endpoint: https://api.avnester.com/public/v1/compare_properties ### get_locality_insights Get aggregated insights for one locality: ₹/sqft, supply count, demand pulse, livability/investment grade, highlights, watchouts, monthly priceTrends, and strengthTags. Use when the user asks "what is X locality like". Covers cities AVnester publishes locality guides for; others return supported=false — surface the scopeMessage. Always surface the disclaimer field when returning livability or investment grade. - Required args: locality, city - Endpoint: https://api.avnester.com/public/v1/get_locality_insights ### compare_localities Compare 2–3 localities in one city side-by-side: price trends, livability, investment grade, strengths, and watchouts. Use when the user asks "X vs Y" or "which is better for buying/renting" about neighborhoods. Covers cities AVnester publishes locality guides for; others return supported=false — surface the scopeMessage. For specific LISTINGS by ID, use compare_properties instead. - Required args: city, localities - Endpoint: https://api.avnester.com/public/v1/compare_localities ### calculate_home_affordability Estimate the monthly home-loan EMI for a property value in India. Pure deterministic reducing-balance math — no advice, no loan-approval/eligibility claim. Defaults to 80% loan-to-value when loanAmount is omitted; returns EMI, total interest, total payment, and an assumptions block (LTV, down payment). Surface the disclaimer field. For an income-based "can I afford this" verdict, use get_property_decision_intelligence instead. - Required args: propertyValue - Endpoint: https://api.avnester.com/public/v1/calculate_home_affordability ### simulate_loan_prepayment Simulate the impact of prepaying an Indian home loan. Pure deterministic math — no advice, no loan-approval claim. Compares reduce_tenure (keep EMI, finish early — bigger saving) vs reduce_emi (keep tenure, lower EMI); supports one-time and/or recurring annual prepayment. Surface the disclaimer field. - Required args: outstandingPrincipal, remainingTenureYears - Endpoint: https://api.avnester.com/public/v1/simulate_loan_prepayment ### compare_balance_transfer Compare staying on the current home loan vs transferring (refinancing) to a lower rate. Pure deterministic math — no advice, no loan-approval claim. Returns new EMI, interest saved over the remaining tenure, switching cost, net saving, breakeven month, and a worthIt flag. Surface the disclaimer field. - Required args: outstandingPrincipal, currentRatePercent, newRatePercent, remainingTenureYears - Endpoint: https://api.avnester.com/public/v1/compare_balance_transfer ### optimize_home_loan_tax_regime Compare income tax under the OLD vs NEW regime (FY2026-27) for a home-loan borrower and recommend which saves more. Pure deterministic slab math — not tax advice. Models §24(b) interest + §80C principal (+ joint-loan doubling, senior-citizen exemptions via ageBand); lists property tax benefits it does NOT model. §80EE/§80EEA are sunset and never applied. Surface the disclaimer field. - Required args: annualIncome, homeLoanInterest, homeLoanPrincipal - Endpoint: https://api.avnester.com/public/v1/optimize_home_loan_tax_regime ### estimate_stamp_duty_and_registration Estimate stamp duty and registration charges for a property purchase in any of India's 28 states and 8 union territories, from state-published rates (the @avnester/india-tax-data table). Pass `buyerGender` (male, female, or joint — a man and a woman buying together). Women pay less stamp duty in 14 of the 36 states and UTs (largest cuts: Assam 5% instead of 8.25%, Chandigarh 3% instead of 5% and Delhi 4% instead of 6%), some within a limit (Himachal Pradesh up to ₹80 lakh, Maharashtra residential units only and Uttar Pradesh up to ₹1 crore (reported, not yet verified)). For a woman, Gujarat waives the registration fee, Madhya Pradesh charges 1% registration instead of 3% and Tamil Nadu charges 1% registration instead of 2% up to ₹10 lakh. The engine applies each state's own rule — do not restate a concession the response does not show. Pass `propertyType` (residential/commercial/plot/agricultural) — it changes the answer where a rule is scoped by type: Maharashtra's women's concession covers residential units only; Karnataka's first-sale rate covers a flat or apartment only; agricultural land is priced at the ordinary conveyance rate; no state prices commercial or agricultural property at a separate rate. Pass `city` or `localBody` where the state prices by where the property is (Maharashtra, Karnataka, West Bengal, Madhya Pradesh and Haryana), and `firstSale` for a new flat bought from the builder (Karnataka prices it lower). Registration is not always a percentage (Haryana: by value: ₹100 up to ₹50,000, rising to ₹50,000 above ₹90 lakh, plus ₹200; Maharashtra: 1% (capped at ₹30,000); Delhi: 1% plus ₹100): read registrationFee, never multiply a rate out. The surcharges[] array itemises every levy as a % of the property value, including those charged on the duty itself (Karnataka, Madhya Pradesh and Rajasthan). Every answer carries rateVerification (verified / partial / unverified, naming each rule not yet checked against the state notification) and assumptions[] (what was assumed, or is known and not priced) — show both beside the figure. A state outside India returns supported=false with every amount 0 (HTTP 200); a missing state is a 400. Surface the disclaimer exactly — this is a regulatory-rate estimate, not legal advice. - Required args: propertyValue, state - Endpoint: https://api.avnester.com/public/v1/estimate_stamp_duty_and_registration ### get_property_decision_intelligence Assess whether a buyer can afford a specific Indian home — ONE verdict (AFFORDABLE / STRETCH / NOT_YET / INELIGIBLE) combining indicative loan eligibility (FOIR/LTV/CIBIL), EMI, true cash-to-close (down payment + stamp duty + registration + charges), and regime-aware tax benefit. Mode A: pass an AVnester listingId. Mode B: pass propertyValue + state (any Indian state). Sensitive inputs (income, CIBIL) are transient — never cached or logged. NOT a loan approval, offer, or advice. Surface the disclaimer field. - Required args: monthlyNetIncome, (listingId) OR (propertyValue + state) - Endpoint: https://api.avnester.com/public/v1/get_property_decision_intelligence ## Rate limits Every tool carries the SAME per-minute ceiling for a given tier — identical on the MCP and REST transports. On OAuth tiers the per-minute budget is per tool: per authorising user for interactive OAuth calls, per application for server API keys. A call made without signing in is limited to 30 requests a minute per tool, 60 a minute across all tools, 10 new (uncached) queries a minute per tool, 100 tool calls a day and 50 new localities a day, per IP. Exceeding a limit returns HTTP 429 with a Retry-After header (seconds to wait). Every 429 carries error "rate_limited" and a reason naming the limit: rate_limit_per_tool, anon_aggregate, anon_daily, cache_miss_budget, locality_cardinality, usage_daily, usage_month, usage_ceiling, edge_rate_limit. Retry-After counts to the end of the one-minute window the first call opened for a per-minute limit, to 00:00 UTC for a daily one, to the month's reset for the monthly allowance or the ceiling, and 300 seconds for the 5-minute limit per network address our firewall checks first (edge_rate_limit); over MCP the refusal is a tool error whose message names the limit, except the per-IP limit across all tools for calls made without signing in, which answers before any tool runs with the same HTTP 429 as REST, and the 5-minute limit per network address (edge_rate_limit), which answers any caller, signed in or not, before AVnester does with the same HTTP 429. A browser page on another site cannot read that one: our firewall's answer carries no CORS headers, so the page sees a network error. ## Access tiers | Tier | Price | Requests/min per tool | Calls/month | Fair-use daily | Price history | Commercial use | Server API keys | |---|---|---|---|---|---|---|---| | Developer | ₹0 | 30 | 1,000 calls / month | 100 | 12 months | Evaluation only | No | | Business | ₹4,500/month | 600 | 10,000 calls / month included, then ₹0.45 per call + GST, up to 30,000 calls / month | 1,000 (alert only) | 36 months | Licensed | Yes | | Scale | ₹15,000/month | 1,200 | 50,000 calls / month included, then ₹0.30 per call + GST, up to 1,50,000 calls / month | 5,000 (alert only) | 36 months | Licensed | Yes | | Enterprise | Custom | 6,000 | No monthly cap — fair use | none | 36 months | Licensed | Yes | Developer is an EVALUATION tier: build, test and run personal projects, with visible attribution to AVnester. Redistributing the data, building a derivative dataset, or serving it inside a commercial product requires a Business licence (https://avnester.com/legal/ai-use). Business, Scale and Enterprise are arranged by invoice — contact partnerships@avnester.com; there is no self-serve checkout. On Developer, calls above the monthly allowance are refused with HTTP 429 (REST: error "rate_limited", reason "usage_month"; above the daily figure, reason "usage_daily"). On Business and Scale, calls above the allowance are served and billed per call at the tier's own rate, plus GST, up to a ceiling of 3× the allowance (raisable per contract); past the ceiling a REST call returns HTTP 429 with error "rate_limited" and reason "usage_ceiling" (an MCP tools/call returns a tool error naming the ceiling and the reset date) until the UTC month resets. Overage is billed on usage from October 2026 (UTC) onward; an earlier month stays at the flat monthly price, with no ceiling. Enterprise volume is set by contract. Active apps: Developer, 1 active app per account (its allowance is per app); a paid plan is set per app. Developer and above are metered monthly, per application. Every REST response carries X-AVnester-Usage-Limit, X-AVnester-Usage-Remaining and X-AVnester-Usage-Reset for the application's monthly allowance, so an agent can pace itself (a tier that bills overage adds X-AVnester-Usage-Overage and X-AVnester-Usage-Ceiling), plus the IETF RateLimit-Policy and RateLimit headers for the per-minute budget (RateLimit-Policy: "";q=;w=60, RateLimit: "";r=;t=); a REST call made without signing in also lists its per-IP budgets across all tools, per minute (w=60) and per UTC day (w=86400); a 429 carries Retry-After, error "rate_limited" and a reason (see Rate limits above). On MCP the transport commits the response headers before the tool runs, so an authenticated tools/call carries the X-AVnester-Usage-* allowance headers as they stood when the request started and no per-tool RateLimit-Policy/RateLimit pair, and an MCP call made without signing in carries only the per-IP aggregate RateLimit-Policy/RateLimit. A call made without signing in is NOT metered monthly and carries no monthly allowance — its limits are the per-IP ones under Rate limits above. ## OAuth (optional, recommended for production) Register a client via DCR (RFC 7591): POST https://auth.avnester.com/oauth/register. Token endpoint: https://auth.avnester.com/oauth/token. Authorization: https://auth.avnester.com/oauth/authorize. DPoP (RFC 9449) is supported as an optional uplift — send a DPoP proof to sender-constrain your token to your keypair; plain bearer tokens are equally accepted. The person signs in with their AVnester mobile number (a one-time code on avnester.com; a new number gets a free account). Store the refresh token each refresh returns and discard the old one: a public client that is not DPoP-bound gets a new one on every refresh, and reusing a replaced one revokes the grant. Walkthrough: https://developers.avnester.com/oauth Server-to-server (no user signed in): Business, Scale and Enterprise apps can create an API key (avn_live_…) in the developer console and send it as "Authorization: Bearer " to https://api.avnester.com/public/v1/ or as a tools/call to https://mcp.avnester.com/public-mcp. The key is shown once, carries the scopes chosen for it, can be limited to an IP allowlist, and stops working within a minute of being revoked. It is refused by the A2A (Ava) endpoint and from a browser page on a site we have not allowlisted. Docs: https://developers.avnester.com/server-credentials A server credential can also be OAuth client credentials — a signed key (private_key_jwt, the recommended method where you keep keys in a vault) or a client secret (client_secret_basic) — once the platform enables them: the developer console then offers them beside the API key, and https://auth.avnester.com/.well-known/oauth-authorization-server lists client_credentials in grant_types_supported. Exchange the credential at https://auth.avnester.com/oauth/token (grant_type=client_credentials, scope=) for a 15-minute access token, send it as "Authorization: Bearer " to the same endpoints (metered per application), and reuse it until a minute before it expires. A refusal is 400 unauthorized_client with the reason in error_description, or 401 invalid_client when authentication fails. A revoked OAuth credential gets no new token at once; tokens already issued stop within 15 minutes. A credential can be DPoP-bound as an opt-in. Docs: https://developers.avnester.com/server-credentials#tokens ## Policies - Acceptable use: https://avnester.com/legal/ai-use - Privacy (DPDPA + GDPR): https://avnester.com/privacy - Security posture: https://avnester.com/legal/security - Terms: https://avnester.com/terms ## Contact - Connector questions: connector-support@avnester.com - Security disclosure: security@avnester.com - Commercial / Enterprise: partnerships@avnester.com