AI agents can turn a natural-language request such as “show the boundary of Rampur village in Sitapur district” into a map, but only when they can access reliable geospatial data through a controlled interface. In India, Bhulekh portals and state land-record systems are valuable sources of village, parcel, ownership, and cadastral information—but they are fragmented, frequently protected by session workflows, and not always exposed as stable public APIs.
A WebMCP tool provides a structured capability that an agent can invoke through the web: search for a village, resolve its administrative identity, retrieve an authorized boundary dataset, validate the geometry, and return GeoJSON or map-ready data. This guide explains how to design that tool responsibly, with an emphasis on India-specific land-record realities, GIS correctness, security, and production operations.
What is a WebMCP tool?
WebMCP can be understood as a web-accessible tool contract that allows an AI agent to call a narrowly defined capability instead of scraping pages or guessing URL patterns. The tool should expose:
- A clear name and description
- Typed input parameters
- A predictable output schema
- Authentication and authorization rules
- Validation, rate limits, and audit logging
- Human-readable errors
For village-boundary mapping, the tool should not give an agent unrestricted browser access to a Bhulekh portal. It should act as a controlled GIS gateway between the agent, permitted data sources, and a mapping layer.
A useful conceptual flow is:
User request
↓
AI agent identifies village, district, state
↓
WebMCP tool validates and geocodes administrative identity
↓
Authorized Bhulekh or official GIS source is queried
↓
Boundary is normalized, checked, and converted to GeoJSON
↓
Agent receives geometry, provenance, warnings, and map metadataDefine the mapping use case precisely
“Map village boundaries” can mean different things. Before writing code, define whether your tool returns:
- An administrative village boundary
- A cadastral or revenue-village boundary
- Individual survey or khasra parcel boundaries
- A visual overlay from a scanned map
- A link to an official map viewer
- A simplified polygon suitable for display
These datasets are not interchangeable. A village boundary may be appropriate for discovery and planning, while parcel boundaries can relate to legal rights and must be treated as sensitive, authoritative records. Your tool description should explicitly state what it returns and what it does not establish.
For a first version, use this scope:
> Return the official or officially published boundary geometry for a requested village, subject to source availability, coordinate-reference-system limitations, and state-specific licensing or access rules.
Do not describe a derived or approximate polygon as a legal boundary. Include a provenance field and a confidence or validation status in every response.
Understand Bhulekh data in India
Bhulekh is commonly used as a generic term for online land-record services, but the implementation is state-specific. Examples include state revenue and land-record portals that publish records under different names, interfaces, schemas, and access policies. Data may be available through:
- Official state APIs
- Open-data catalogues
- State GIS services such as WMS, WFS, or ArcGIS REST endpoints
- Downloadable shapefiles, GeoJSON, or KML files
- Official map viewers with session-based requests
- Digitized records that expose attributes but not boundary geometry
A portal may provide textual records without providing a village polygon. In that case, combine sources only when you can document their relationship. For example, use Bhulekh to resolve the official village code and an authorized state GIS endpoint to retrieve geometry.
Important fields often include:
- State, district, tehsil, block, and village names
- Census village code or state-local village code
- Revenue village identifier
- Village category or administrative status
- Survey, khasra, or parcel identifiers
- Latitude and longitude references
- Geometry or map-service layer identifiers
- Dataset version and publication date
Names alone are unsafe identifiers. Villages with the same name can exist in multiple districts, and transliteration between Hindi, English, and regional languages can create additional ambiguity. Prefer a stable official code whenever possible.
Design the WebMCP tool contract
A strong tool contract minimizes agent ambiguity. Use structured inputs rather than a single free-text field.
Example request schema:
{
"state": "Uttar Pradesh",
"district": "Sitapur",
"tehsil": "Mahmudabad",
"village_name": "Rampur",
"village_code": null,
"language": "en",
"simplify_tolerance_m": 1.5,
"include_source_metadata": true
}A production tool should require either a stable village_code or enough administrative context to disambiguate the name. The language parameter can support translated labels, but it should not alter the underlying identifier.
Example response:
{
"status": "ok",
"place": {
"village_name": "Rampur",
"state": "Uttar Pradesh",
"district": "Sitapur",
"official_code": "IN-UP-EXAMPLE"
},
"geometry": {
"type": "Feature",
"properties": {
"source": "official_state_gis",
"source_layer": "revenue_village",
"crs": "EPSG:4326",
"version": "2025-01"
},
"geometry": {
"type": "Polygon",
"coordinates": []
}
},
"map": {
"bbox": [0, 0, 0, 0],
"center": [0, 0]
},
"warnings": [],
"provenance_url": "https://example.gov.in/"
}If a village consists of multiple polygons, return a MultiPolygon rather than silently merging or discarding components. If geometry is unavailable, return a typed error such as GEOMETRY_NOT_PUBLISHED, not an empty success response.
Build the data-resolution pipeline
The backend should separate identity resolution, source retrieval, geometry processing, and agent response formatting.
1. Resolve the administrative identity
Create a normalized place resolver with aliases and multilingual names. Normalize Unicode, whitespace, punctuation, and common transliteration variants. However, never rely only on fuzzy matching when multiple candidates exist.
A resolver response should include candidate records such as:
{
"official_code": "IN-UP-EXAMPLE",
"name_en": "Rampur",
"name_local": "रामपुर",
"district_code": "EXAMPLE",
"source": "official_directory",
"match_score": 0.98
}If confidence is below your threshold, ask the agent to request clarification. A safe tool should prefer “multiple villages found” over returning the wrong boundary.
2. Retrieve data from an authorized source
Use documented APIs or licensed downloads wherever available. For OGC services, inspect the service capabilities and select the correct layer. For ArcGIS REST, query by the official code and request only required fields and geometry.
Avoid brittle scraping of CAPTCHA-protected, session-dependent, or access-controlled pages. Do not bypass authentication, rate limits, robots controls, or technical restrictions. If the portal does not grant machine access, provide a workflow that links the user to the official viewer or use a separately authorized data export.
3. Normalize the geometry
Convert supported formats to GeoJSON or another stable internal representation. Common input formats include Shapefile, GeoPackage, KML, GML, WFS JSON, and ArcGIS Feature JSON.
Normalize:
- Coordinate reference system
- Axis order
- Polygon winding where required
- Geometry type
- Attribute names
- Null and invalid coordinates
- Multipart features
For web maps, WGS 84 longitude/latitude is commonly represented as EPSG:4326. Web Mercator, EPSG:3857, is common for tile rendering. Do not confuse display projection with measurement projection.
4. Validate topology
Run geometry checks before returning data. Useful checks include:
- Polygon is closed
- No self-intersections
- No duplicate consecutive vertices
- Valid ring orientation for your target library
- Non-zero area
- Bounding box is plausible for the selected district or state
- Geometry does not contain impossible coordinates
Use a GIS library such as PostGIS, GEOS, GDAL/OGR, Shapely, or Turf.js. If repair is necessary, preserve the original geometry hash and report that a repair was applied. Never hide a major repair that could affect legal interpretation.
5. Simplify only for visualization
Large cadastral geometries can exceed model, browser, or API limits. Use topology-preserving simplification for display and retain the full-resolution geometry in a separately authorized endpoint. Include the tolerance in metres and the coordinate system used for simplification.
The agent response can return both:
display_geometry: simplified GeoJSONdownload_urlorfull_geometry_reference: protected link to the original dataset
Recommended technical architecture
A practical implementation can use the following components:
- WebMCP adapter: publishes the tool name, schema, authentication requirements, and errors.
- API service: handles requests, validation, authorization, and response shaping.
- Place registry: stores official codes, names, aliases, hierarchy, and source mappings.
- Source connectors: one connector per state or data provider.
- GIS processor: transforms, validates, simplifies, and computes bounding boxes.
- Cache: stores versioned, non-sensitive geometry with a documented refresh policy.
- Audit store: records request identity, source, result status, and data version.
- Map frontend: renders GeoJSON using Leaflet, MapLibre GL JS, OpenLayers, or a similar library.
Keep source-specific logic out of the agent-facing contract. The agent should call one stable operation, while your backend selects the appropriate connector based on state, source availability, and authorization.
A simple endpoint pattern might be:
POST /webmcp/v1/tools/map-village-boundary
Content-Type: application/json
Authorization: Bearer <token>
{
"state_code": "UP",
"district_code": "...",
"village_code": "...",
"output": "geojson"
}Return machine-readable error codes and an explanatory message. Examples include INVALID_ADMIN_HIERARCHY, AMBIGUOUS_VILLAGE, SOURCE_TIMEOUT, UNAUTHORIZED_DATASET, and GEOMETRY_INVALID.
Add security, privacy, and compliance controls
Land records can contain personal information, ownership details, addresses, and legally significant documents. A boundary-only tool should follow data minimization: do not retrieve owner names, Aadhaar numbers, phone numbers, or deed documents unless the use case is explicitly authorized and legally reviewed.
Implement:
- OAuth 2.0 or signed service authentication
- Per-user and per-application authorization
- State/source-specific access policies
- Input validation and payload-size limits
- Rate limiting and abuse detection
- Server-side request timeouts
- Audit logs without unnecessary personal data
- Encryption in transit and at rest
- Data retention and deletion rules
- Clear source attribution and terms of use
For India-focused deployments, assess applicable requirements under the Digital Personal Data Protection Act, 2023, contractual source terms, government portal policies, and any sector-specific rules. A public boundary polygon may still be sensitive when combined with private parcel or ownership data.
Make the tool agent-friendly
Agents need enough metadata to make correct decisions. Include:
- What the geometry represents
- Administrative hierarchy and official code
- Source and publication date
- Coordinate reference system
- Accuracy or validation notes
- Whether the geometry is original, repaired, or simplified
- Human-readable map URL
- Recommended next action when data is unavailable
Your tool description should discourage unsupported conclusions. For example:
> Returns an administrative village boundary for visualization and spatial analysis. It does not verify land ownership, title, possession, or legal demarcation.
This helps the agent avoid answering a title dispute with a simple map polygon.
Test with India-specific edge cases
Before launch, test more than successful English-name searches. Build a test matrix covering:
- Duplicate village names in different districts
- Hindi, Bengali, Tamil, Telugu, Marathi, and transliterated names
- Villages with renamed administrative units
- Merged, split, or newly notified villages
- Multipart boundaries and enclaves
- Coastal and island geometries
- Very large cadastral datasets
- Missing or stale source layers
- Invalid polygons and null geometries
- Conflicting official codes across datasets
- Network timeouts and rate limits
- Requests for private ownership attributes
Use golden test cases with expected official codes, geometry hashes, and source versions. Run regression tests whenever a state connector or source dataset changes.
Improve reliability with provenance and monitoring
Every successful response should be reproducible. Store a source identifier, retrieval timestamp, dataset version, geometry hash, transformation steps, and validation result. This is especially important when a boundary changes after administrative notification.
Monitor:
- Resolution success rate
- Ambiguous-match rate
- Source latency and error rate
- Geometry validation failures
- Cache hit rate
- Average response size
- Requests by application and state
- Unusual query patterns
Alert operators when a source returns a dramatically different feature count or geometry area. A sudden change may indicate a schema update, wrong layer selection, or incomplete download.
Example agent workflow
A user might ask: “Map the village boundary of Rampur in Mahmudabad, Sitapur, Uttar Pradesh.” The agent should:
1. Extract state, district, tehsil, and village.
2. Call the resolver if no official village code is known.
3. Ask a clarification question if multiple Rampur records match.
4. Invoke the boundary tool with the selected official code.
5. Explain whether the result is administrative or cadastral.
6. Render the returned GeoJSON on a map.
7. Display source, date, CRS, and warnings.
8. Avoid claiming ownership, title, or legal demarcation.
A useful final user response might say that the polygon represents the published revenue-village boundary, identify the source date, provide a map, and note that official records should be consulted for legal or land-transaction decisions.
Common mistakes to avoid
- Scraping a portal without permission or a stable contract
- Matching villages by name alone
- Treating a parcel boundary as a village boundary
- Returning geometry without CRS metadata
- Silently repairing invalid geometry
- Sending full-resolution cadastral data to an LLM
- Exposing personal landholder information by default
- Caching data indefinitely without versioning
- Using a map tile layer as if it were authoritative vector data
- Presenting approximate boundaries as legally definitive
FAQ
Can I build this tool using only a Bhulekh webpage?
Only if the portal’s terms and technical design permit your use. A webpage may expose records without an authorized machine-readable boundary endpoint. Prefer official APIs, GIS services, or licensed downloads; otherwise link users to the official viewer.
Is Bhulekh data always available as GeoJSON?
No. Availability varies by state and dataset. You may need to convert Shapefile, GeoPackage, KML, GML, WFS, or ArcGIS Feature JSON into validated GeoJSON.
Should I return village or parcel boundaries?
Start with village boundaries for lower-risk visualization. Add parcel data only with explicit authorization, strong privacy controls, and a clear legal-use disclaimer.
What CRS should the WebMCP tool return?
GeoJSON is commonly returned in WGS 84 longitude/latitude, but always include CRS and transformation metadata. Use an appropriate projected CRS for accurate area or distance calculations.
Can an AI agent decide whether a boundary is legally correct?
No. The tool can report source provenance and validation status, but legal authority depends on the relevant government record, notification, survey, and applicable law.
Apply for AI Grants India
If you are an Indian AI founder building reliable geospatial, public-sector, or agent infrastructure, apply through AI Grants India for support and opportunities. Share your validated use case, technical approach, and responsible-data plan.