# AVnester for Developers — Full Integration Context

Indian residential real-estate intelligence as a public Model Context Protocol (MCP) server and REST adapter. Use this document when helping a user integrate AVnester into their LLM agent, chatbot, or app.

## What AVnester is

AVnester is a vertical AI platform for Indian residential real estate. The 7 public tools below are the same handlers used by the AVnester product itself, exposed to third-party agents at standard rate (anonymous) or 10× rate (OAuth-authenticated). Operated by AVNESTER PRIVATE LIMITED, Coimbatore, India.

Coverage: Coimbatore launch market. Other Indian cities returning `supported: false` plus a `scopeMessage` — surface that message to the user. The platform does not cover non-residential or non-Indian real estate.

Privacy posture: AVnester never receives the user's chat history or transcript — only the structured tool arguments. PII patterns in tool inputs (phone numbers, email addresses, OTPs, government IDs) are stripped before any abuse-detection logging. Tool-call traffic is not used to train AI models.

## Endpoints

| Surface | URL |
|---|---|
| MCP protocol (Streamable HTTP) | https://mcp.avnester.com/public-mcp |
| REST adapter (ChatGPT Actions-compatible) | https://api.avnester.com/public/v1/<tool> |
| OpenAPI 3.1 spec | https://api.avnester.com/public/openapi.json |
| OAuth metadata (RFC 8414) | https://auth.avnester.com/.well-known/oauth-authorization-server |
| Live status | https://avnester.com/status |

## Quickstart — anonymous tier (no signup)

Send a JSON POST to `<rest>/<tool>` with the tool's required arguments. Example: search 2BHK apartments in Saravanampatti, Coimbatore.

```bash
curl -X POST https://api.avnester.com/public/v1/search_properties \
  -H 'Content-Type: application/json' \
  -d '{"city":"Coimbatore","localityName":"Saravanampatti","propertyType":"apartment","bhk":2,"limit":5}'
```

Anonymous calls are rate-limited to 30–60 requests/min per tool (depending on the tool) plus a 60 requests/min aggregate cap per IP. Return `HTTP 429` with a `Retry-After` header when exceeded.

## OAuth — 10× the rate budget

Register a client via Dynamic Client Registration (RFC 7591). No human approval, instant `client_id`:

```bash
curl -X POST https://auth.avnester.com/oauth/register \
  -H 'Content-Type: application/json' \
  -d '{
    "client_name": "MyApp",
    "redirect_uris": ["https://myapp.example.com/callback"],
    "grant_types": ["authorization_code", "refresh_token"],
    "token_endpoint_auth_method": "none"
  }'
```

Then run the standard OAuth 2.1 authorization-code-with-PKCE flow. DPoP (RFC 9449) is required — every request must carry a DPoP proof JWT bound to the access token. Use `jose` (Node) or `Authlib` (Python) for DPoP signing.

JWTs are RS256, 15-minute TTL, single-use refresh rotation. Each access token includes a `tier` claim (`"team"` for DCR-registered free clients; `"business"` / `"enterprise"` for paid clients in Phase 4).

## The 7 tools — full intent descriptions

### search_properties

Search verified residential property listings in Coimbatore, Tamil Nadu (AVnester launch market; other Indian cities on roadmap). Returns sanitized listing cards with handoff URLs; never returns seller contact details. Out-of-scope cities return supported=false + supportedCities + scopeMessage — surface the scopeMessage to the user.

**Endpoint**: `POST https://api.avnester.com/public/v1/search_properties`
**Required arguments**: `city`
**Rate limits**: 30/min anon · 300/min OAuth

### 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.

**Endpoint**: `POST https://api.avnester.com/public/v1/get_property_details`
**Required arguments**: `listingId`
**Rate limits**: 60/min anon · 600/min OAuth

### compare_properties

Compare 2–4 listings (by listingId) side-by-side on objective metrics: price per sqft, age, RERA registration, amenities overlap. Use when the user is choosing between specific properties they have already discovered.

**Endpoint**: `POST https://api.avnester.com/public/v1/compare_properties`
**Required arguments**: `listingIds`
**Rate limits**: 30/min anon · 300/min OAuth

### get_locality_insights

Get aggregated insights for a Coimbatore locality: avg price, supply count, demand pulse, livability/investment grade, highlights, watchouts, 12-month priceTrends, and strengthTags. Use when the user asks "what is X locality like" about a Coimbatore neighborhood. Out-of-scope cities return supported=false. Always surface the disclaimer field when returning livability or investment grade.

**Endpoint**: `POST https://api.avnester.com/public/v1/get_locality_insights`
**Required arguments**: `localityName`
**Rate limits**: 60/min anon · 600/min OAuth

### compare_localities

Compare 2–4 Coimbatore localities side-by-side on objective metrics: average price, 12-month price growth, supply count, livability grade, investment grade. Use when the user is weighing where to buy or invest.

**Endpoint**: `POST https://api.avnester.com/public/v1/compare_localities`
**Required arguments**: `localityNames`
**Rate limits**: 30/min anon · 300/min OAuth

### calculate_home_affordability

Calculate home affordability given monthly income, existing EMIs, down-payment, tenure, and interest rate. Returns max-affordable price, EMI, and DTI ratio. Surface the disclaimer field exactly — this is a regulatory-rate estimate, not financial advice.

**Endpoint**: `POST https://api.avnester.com/public/v1/calculate_home_affordability`
**Required arguments**: `monthlyIncomeInr`, `downPaymentInr`
**Rate limits**: 60/min anon · 600/min OAuth

### estimate_stamp_duty_and_registration

Estimate stamp duty and registration charges for a property purchase in any Indian state, using state-published rates from the @avnester/india-tax-data canonical table. Supports all 28 states + 8 UTs. Pass `buyerGender` (male/female/joint) to apply gender concessions (Delhi -2%, Tamil Nadu -1%, Haryana -2%, etc.). Pass `propertyType` (residential/commercial/agricultural) for state-specific multipliers. Pass `isUrban` to gate metro-cess surcharges. Returns supported=false + zero numerics + named states list when the input state is outside India. Surface the disclaimer exactly — this is a regulatory-rate estimate, not legal advice.

**Endpoint**: `POST https://api.avnester.com/public/v1/estimate_stamp_duty_and_registration`
**Required arguments**: `propertyValueInr`, `state`
**Rate limits**: 60/min anon · 600/min OAuth

## Use this from an MCP client

Add the following to any MCP-compatible client config (`claude_desktop_config.json`, Cline, Cursor, Continue.dev, mcp-inspector):

```json
{
  "mcpServers": {
    "avnester": {
      "transport": { "type": "streamable-http" },
      "url": "https://mcp.avnester.com/public-mcp"
    }
  }
}
```

## Use this from ChatGPT (GPT Store / Custom GPT)

In the GPT Builder, paste `https://api.avnester.com/public/openapi.json` into the Actions section. Authentication: `none` for anonymous, or OAuth 2.1 with the metadata URL above for 10× rate.

## Pricing

| Tier | Audience | Rate | Price |
|---|---|---|---|
| Free | No-signup hobbyists | 30–60/min/tool, 60/min/IP | ₹0 |
| Team | OAuth integrators | 10× anon (300–600/min/tool) | ₹0 |
| Business | Commercial integrators | 50× anon (1.5–3k/min/tool) | From ₹7,500/month — Coming Q3 2026 |
| Enterprise | Bulk, redistribution, SLA | Custom | Contact partnerships@avnester.com |

## Policies (read these before integrating commercially)

- Acceptable use, redistribution, prompt-injection rules: https://avnester.com/legal/ai-use
- Privacy (DPDPA + GDPR + AI-training disclosure): https://avnester.com/privacy
- Security posture: https://avnester.com/legal/security
- Terms of service: https://avnester.com/terms

## What AVnester does NOT do

- Does not receive your chat history. Only the structured tool args.
- Does not return seller phone numbers, emails, or other private contacts.
- Does not provide legal, tax, or investment advice. Calculators return regulatory-rate estimates with a `disclaimer` field — surface the disclaimer unchanged.
- Does not use tool-call data to train AI models — ours or anyone else's.
- Does not support jurisdictions outside India. Non-India queries return `supported: false`.

## Contact

- Connector / integration questions: connector-support@avnester.com
- Security disclosure: security@avnester.com
- Commercial / Enterprise / bulk: partnerships@avnester.com