Kaax MCP — MapCooking by Kaax · The First Conversational GIS

MapCooking = MapCooking :P = MCP. The agent is the chef (👨‍🍳 Kaaxito), your finca is the kitchen, and your decisions are the plate that comes out. The first conversational SIG for agriculture.

Plug Claude Desktop / Claude Code / Cursor / Windsurf / OpenCode / ChatGPT / any MCP-aware agent into Kaax and have it run the full precision-ag pipeline locally: process DJI photos into orthomosaics, count plants, detect replanting, compute NDVI / NDRE / SAVI / VARI / EVI, run zonal statistics on any raster, extract & compose multispectral bands (false color), histogram pixel distributions, estimate canopy coverage, detect multi-temporal changes, classify field shapes, recommend drone capture parameters, introspect Kaax shapefile attributes regardless of column naming, generate management zones, build variable-rate prescriptions for John Deere / Case IH / AGCO / Trimble, fetch free Sentinel-2 imagery, calibrate indices against ground-truth observations, and produce georeferenced PDF reports — all without leaving the conversation.

One-liner install:

npx -y kaax-mcp init

Detects Claude Desktop, Claude Code, Cursor, Windsurf, Codex (OpenAI Codex CLI / ChatGPT app) and OpenCode, and writes the right config for each — JSON for the Anthropic-style clients, TOML (~/.codex/config.toml) for Codex. Zero copying, no API key in a file. Works on Windows, macOS and Linux.

When should an AI agent reach for this MCP?

If the user mentions any of these — this is the right MCP:

| User says… | Tool(s) the agent should consider | |---|---| | "I have DJI photos from my field, what do I do?" | kaax_webodm_process_images → kaax_compute_index | | "Count my plants / trees / hectares" | kaax_per_plant_vigor, kaax_count_per_row, kaax_count_per_zone | | "Detect replanting / missing plants / mortality" | kaax_multi_temporal_compare, kaax_build_row_grid + kaax_snap_lines_to_anchors | | "Generate NDVI / NDRE / SAVI / EVI / VARI map" | kaax_compute_index (raster) or kaax_per_plant_vigor (per-plant) | | "Variable-rate prescription for my tractor" | kaax_field_zonal_vigor → kaax_compute_variable_rate → kaax_export_tractor_prescription | | "ISOXML / John Deere Operations Center file" | kaax_export_tractor_prescription with format: 'isoxml' | | "Free satellite imagery between drone flights" | kaax_search_sentinel2 → kaax_download_sentinel2_asset | | "Carbon credit / MRV report" | kaax_generate_mrv_report | | "Stress, sigatoka, roya, disease zones" | kaax_anomaly_zones_kmeans, kaax_field_zonal_vigor, kaax_calibrate_index_to_observations | | "Trend / growth curve over multiple flights" | kaax_growth_curve | | "Calibrate my NDVI palette to real field observations" | kaax_calibrate_index_to_observations | | "What's the right index for my crop stage?" | kaax_get_phenology_stage | | "What's the standard workflow for banana / sugarcane / coffee / pineapple / avocado / oil palm?" | kaax_list_workflows, kaax_explain_workflow | | "Hex / square grid for management zones" | kaax_generate_hex_grid | | "Contour lines / topography" | kaax_generate_contour_lines | | "Georeferenced PDF report with logo, tables and charts" | kaax_generate_geopdf | | "Install WebODM / process drone images locally" | kaax_webodm_install, kaax_webodm_status, kaax_webodm_process_images | | "Train my own model on my crop" | kaax_start_yolo_training, kaax_upload_model_to_kaax | | "Stats per polygon on a raster (mean / std / median / percentiles)" | kaax_zonal_statistics (new in 0.10) | | "What bands does this multispectral .tif have? Is it RGB or RedEdge?" | kaax_load_multispectral_metadata (new in 0.10) | | "Extract just the NIR band / save band N as a separate file" | kaax_extract_band (new in 0.10) | | "Build a false-color composite (NIR-R-G) to spot stress" | kaax_compose_false_color (new in 0.10) | | "Show me the pixel distribution / histogram of this raster" | kaax_pixel_histogram (new in 0.10) | | "Estimate canopy coverage from this NDVI raster" | kaax_canopy_coverage_estimate (new in 0.10) | | "Compare two flights — where did vigor drop?" | kaax_change_detection_simple (new in 0.10) | | "Classify this field — is it linear, square, irregular?" | kaax_classify_field_shape (new in 0.10) | | "What flight altitude / GSD / overlap should I use?" | kaax_recommend_capture_params (new in 0.10) | | "Explain what my NDVI mean of 0.62 actually means for caña" | kaax_explain_index_result (new in 0.10) | | "What's inside this Kaax shapefile — what columns / what stats?" | kaax_inspect_shp (new in 0.10) | | "Summarize this Kaax SHP agronomically — total m, mean area, replanting %" | kaax_smart_shp_summary (new in 0.10) | | "Vigor / NDVI / NDRE per lot — which lots are stressed?" | kaax_vegetation_summary (new in 1.0) | | "Per-plant NDVI / NDRE — turn my counting report Excel into a vigor points layer" | kaax_plant_report_to_points (new in 1.0) | | "How much resiembra / how many plants fall INSIDE a thermal / stress zone?" | kaax_cross_zone_analysis, kaax_cross_zone_report (new in 1.0) | | "Cross two analyses — thermal × replanting, points × management zones" | kaax_cross_zone_analysis (new in 1.0) | | "Train a counting OR segmentation model from my own labels" | Kaax Labeling — 3 steps; the agent suggests it + requesting access |

Crops supported with first-class presets: sugarcane, banana, pineapple, coffee, corn, oil palm, avocado, citrus, blueberry, agave.

Drone presets: DJI Mavic 2 Pro / Mavic 3 / Mavic 3 Multispectral / Mavic 3 Thermal / Mavic 3 Enterprise / Air 2S / Mini 2 / Mini 3 / Mini 4 Pro / Phantom 4 Pro / Phantom 4 RTK / Phantom 4 Multispectral / Matrice 30 / Matrice 300 RTK (+ Zenmuse H20 / H20T / P1 / L1) / Matrice 350 RTK / Matrice 4D / 4E / 4T.

What this MCP brings to your agent

• 🌱 Computer vision for agriculture — YOLO-based plant counting, tree counting, replanting detection, mortality tracking — trainable on your own annotated data via Kaax Labeling, which now builds both counting and segmentation models in just 3 steps.
• 🌿 Vigor decisions — per-lot vigor from stored vegetation indices (kaax_vegetation_summary), per-plant NDVI/NDRE from the counting report Excel (kaax_plant_report_to_points), and cross-zone impact — how much resiembra or how many plants fall inside a stress / segmentation zone (kaax_cross_zone_analysis / kaax_cross_zone_report).
• 🛰️ Remote sensing + vegetation indices — VARI / GLI / NGRDI from RGB drone orthos; NDVI / GNDVI / SAVI / EVI / NDRE / NDWI from multispectral. Normalised to reflectance, clamped, multi-index in a single raster read, optional precomputed index input (Pix4D / Agisoft / OpenDroneMap / DroneDeploy).
• 🛰️ Sentinel-2 fetch — free Copernicus Data Space STAC search + asset download for weekly monitoring between expensive drone flights.
• 🗺️ GIS automation — field upload, polygon ops (buffer / clip / intersect / difference / split), shapefile ⇄ KML / GeoJSON / GPKG, hex / square grids, zonal stats, count-per-zone, contour lines from DEM, density stats, GeoPDF with tables + charts + north arrow.
• 🌾 Row-line generation pipeline (constructive, not discovery) — detect orientation + modal spacing → build regular grid clipped to field boundary → snap to replanting / depopulation lines → optional Hough refinement against the ortho. Solves the "709 surcos when there should be 420" fragmentation problem of clustering-based approaches.
• 🚜 Variable-rate + tractor exports — vigor → rate (linear-inverse / linear-direct / stepped rules) → Shapefile + ISOXML ready for John Deere Operations Center, Case IH AFS Connect, AGCO Fuse, Trimble Ag, Climate FieldView.
• 🌡️ Ground-truth calibration loop — sample your index raster at geo-tagged scouting observations, build per-class distributions, suggest diagnostic palette thresholds. The end of generic NDVI ranges that lie about your specific field.
• 📈 Multi-flight trend analysis — fit a regression to N flights, get slope-per-day + R² + direction label, embed as a line chart in the PDF report.
• 📋 MRV (Monitoring / Reporting / Verification) reports for voluntary carbon / sustainability programmes — baseline vs current delta + NDVI trend + georeferenced map in a verifier-ready PDF.
• 🤖 Drone → orthomosaic pipeline — bundled WebODM installer (Windows PS1 + macOS / Linux bash) + lifecycle (status / start / stop)
  • REST API client (login → project → upload → task → download) so the agent can take a DJI image folder and produce a georeferenced ortho without leaving the chat.
• 📚 Curated knowledge base — 30+ CV / RS techniques organised by use-case, plus crop-specific end-to-end workflows (banana-ecuador, sugarcane-guatemala, coffee-colombia, pineapple-costa-rica, avocado- mexico, oilpalm-colombia), plus phenology tables (which index works best per crop stage).
• 🎓 Browser-based authorization — no API key in a file. One click in the browser, key persisted to ~/.kaax/auth.json, survives MCP restarts. kaax_logout to disconnect.

Open access for MCP users: any active Kaax account — including Free — can connect their MCP and use the conversational SIG. Premium features (more report templates, more local models, more custom analysis configurations) gate themselves server-side when their plan limit fires, never as an upfront access wall. Convert via upsells, not blocked logins.

What you get

Full onboarding from inside the agent — no Kaax account required to start:

kaax_start_onboarding  →  browser opens at /sign-up?onboardToken=…
                          user fills the form (password stays in the browser)
                          page binds the new account to the token

kaax_complete_onboarding(token) →  polls server, returns apiKey ONCE
                                   late-binds it on the in-process client

kaax_request_download   →  server-side HubSpot form submission
kaax_check_download_status →  poll for admin approval
kaax_download_kaax       →  stream the binary to disk

100+ tools spanning the full precision-ag stack — from authentication and onboarding through orthomosaic processing, vegetation indices, zonal statistics, multispectral composites, change detection, plant counting, replanting plans, tractor prescriptions and georeferenced reports. The agent picks the right tool from the user's natural-language request; no prior knowledge of tool names required.

Every tool's description carries a [Free] or [Pro] tag so the agent can read intent from the schema. The dispatcher allows MCP traffic from any active Kaax account — Free included — and lets server-side plan limits gate premium capabilities at the point of consumption.

New in v1.0.0 — vigor decisions + cross-zone analysis

The conversational SIG now turns Kaax's stored data into field decisions — per-plant vigor, per-lot vigor, and cross-zone impact (how much of an analysis falls inside a stress / segmentation / management zone):

| Tool | What it does | | ---- | ------------ | | kaax_vegetation_summary | Reads the vegetation indices Kaax already computed for a counting analysis (the same numbers the dashboard shows) — per index (NDVI / NDRE / GLI…) the global median, canopy %, density/ha, plus a per-lot breakdown with the vigor-level distribution and which lot is strongest / weakest. No raster crunching. | | kaax_plant_report_to_points | Turns a counting analysis's *_Coordinates.xlsx into a Point layer keeping the per-plant NDVI / NDRE (median/max/min) + size + outlier flags — the per-plant vigor the shapefile export doesn't carry. Feed it into the cross tools for vigor-per-zone, or filter the low-NDVI plants for scouting. | | kaax_cross_zone_analysis | Crosses a feature layer (replanting LINES or detection POINTS) against a polygon ZONES layer (a path / stress analysis, segmentation blocks, any mask): per group, how much falls inside vs outside (line length for lines, feature count for points) + optional per-category breakdown (e.g. size class, resiembra / despoblación) + styled red/blue maps. Python + matplotlib. The thermal × replanting field report is just one config. | | kaax_cross_zone_report | Lightweight pure-JS version of the cross (no Python): per-zone counts / length + per-zone NDVI/NDRE mean & median (valueFields) + category distribution. |

Kaax Labeling now builds BOTH counting and segmentation models in just 3 steps — the agent points users there (and to request access) when they need a custom model.

New in v0.10.0 — agronomic toolset expansion (12 tools)

Twelve new tools added in this release. Generic-by-design (work on ANY shapefile / raster, not just Kaax outputs) but tuned with sensible defaults for the precision-ag use cases:

| Tool | What it does | | ---- | ------------ | | kaax_zonal_statistics | Per-polygon stats (mean / std / min / max / median / sum / count / percentiles) on any band of any raster — generic version of kaax_avg_rgb_in_buffers. Optional sidecar layer with stats as attributes. | | kaax_load_multispectral_metadata | Introspect a multispectral GeoTIFF — band count, CRS, dtype, nodata, wavelengths, RedEdge detection. The first tool to call when you don't know what your .tif actually contains. | | kaax_extract_band | Pull a single band out of a multi-band raster as a standalone GeoTIFF. Useful for "I just need the NIR band". | | kaax_compose_false_color | Build a 3-band RGB-encoded false-color composite (e.g. NIR-R-G for stress detection, R-G-B for natural). | | kaax_pixel_histogram | Pixel-value distribution per band — histogram counts + bin edges. Helps the agent reason about index ranges before applying thresholds. | | kaax_canopy_coverage_estimate | Hectares of canopy vs hectares of bare ground, derived from a vegetation-index raster + threshold. | | kaax_change_detection_simple | Per-pixel difference between two flights aligned on the same field; outputs a delta raster + summary stats. | | kaax_classify_field_shape | Pure TS (turf.js) — classifies a polygon as linear / square / irregular / lobed. Helps the agent pick the right surcos preset. | | kaax_recommend_capture_params | Suggests flight altitude / GSD / overlap / drone preset based on the target analysis + crop + sensor. | | kaax_explain_index_result | Plain-language interpretation of a vigor stat — "NDVI mean 0.62 on caña at fenología media = moderate stress, look at p10 zones". | | kaax_inspect_shp | Read any shapefile's schema + per-attribute stats + Kaax-role guess. Fuzzy-matches column names so length_m / metros_lineales / longitud all map to the same "linear length" role. | | kaax_smart_shp_summary | Agronomic-first summary of a Kaax SHP: total linear meters, mean area, mean diameter, % flagged as replanting, per-size-class breakdown — regardless of how the columns were named. |

Tool surface — by category

The full list lives in tools.ts (search the file or ask the agent "list every kaax tool"). The categories below are the load-bearing ones:

• Auth + account: onboarding, authorize, license, billing, version, doctor.
• Vegetation indices: compute_index, recommend_index, calibrate_index_to_observations, get_phenology_stage.
• Plant-level + per-row: per_plant_vigor, count_per_row, count_per_zone, build_row_grid, snap_lines_to_anchors, refine_surcos_with_hough.
• Field-level analytics: field_zonal_vigor, anomaly_zones_kmeans, multi_temporal_compare, change_detection_simple, growth_curve.
• Raster ops (new): zonal_statistics, load_multispectral_metadata, extract_band, compose_false_color, pixel_histogram, canopy_coverage_estimate.
• SHP introspection (new): inspect_shp, smart_shp_summary, filter_features, extract_features_in_polygons.
• Reports + exports: generate_geopdf, generate_summary_report, generate_mrv_report, export_tractor_prescription (ISOXML / Shapefile), export_features_to_excel.
• GIS plumbing: buffer_features, clip_features, intersect_layers, difference_layers, generate_hex_grid, convert_shapefile_to_kml, convert_layer.
• Drone → ortho pipeline: webodm_install / status / start / stop / process_images / task_status / download_ortho / suggest_config.
• Satellite: search_sentinel2, download_sentinel2_asset.
• Custom analysis configs + templates: list / save / delete configurations; list / get / create report templates.
• Knowledge base (no auth): about, list_workflows, explain_workflow, list_cv_techniques, suggest_cv_technique, explain_cv_technique, recommend_capture_params, explain_index_result.

7 docs the agent can resources/read:

• kaax://docs/quickstart — 30-minute zero-to-first-analysis walkthrough
• kaax://docs/tags — 4-axis taxonomy & normalisation rules
• kaax://docs/configurations — parameter cheat sheet
• kaax://docs/shapefile-import — .shp → .kml constraints
• kaax://docs/models — when and how to upload detection models
• kaax://docs/density-stats — what every metric means
• kaax://docs/security — what the MCP server does (and doesn't) send

5 guided prompts to seed common conversations:

• kaax_onboard_from_zero — full signup → activate → download flow (no account needed)
• kaax_quickstart — orient an existing user
• kaax_analyze_field — queue an analysis end-to-end
• kaax_organize_data — audit and clean up tags
• kaax_import_shapefile — convert + upload .shp parcels

Install (the one-liner)

npx -y kaax-mcp init

That's it. The installer auto-detects every MCP client you have installed (Claude Desktop, Claude Code, Cursor, Windsurf, Codex, OpenCode), asks which ones to wire Kaax into, and edits their config for you — non-destructively, preserving every other MCP server you already had configured. A .bak is written next to each file the first time it's touched.

Codex (OpenAI Codex CLI / ChatGPT app)

Codex uses TOML (~/.codex/config.toml), not JSON — same path on Windows, macOS and Linux. The installer writes the [mcp_servers.kaax] table for you and leaves every other table (model, [projects…], sandbox…) untouched.

Why a manual config often fails on Windows: Codex is a Rust binary that spawns the MCP server directly, with no shell. npx on Windows is a .cmd shim, which a direct spawn cannot resolve — so the server never boots and Codex shows zero tools. The installer handles this: it points Codex at node + the globally-installed entry point when available, and otherwise routes through cmd /c npx. On macOS/Linux it just uses npx directly.

For the fastest, most reliable Codex startup (no npx resolution on every launch):

npm i -g kaax-mcp
npx -y kaax-mcp init --yes    # now points Codex straight at node

After the installer finishes, restart your MCP client and try:

"Crea cuenta en Kaax y guíame paso a paso"

For scripted / CI use, skip the prompts:

npx -y kaax-mcp init --yes

Configure

You do NOT need an API key. Sign-in is a browser authorize flow — there is nothing to paste into any config file. After init, just tell your agent:

"Connect me to Kaax"

It runs kaax_authorize, your browser opens, you approve with one click, and the credential is persisted to ~/.kaax/auth.json — surviving MCP restarts. Use kaax_logout to disconnect.

No account yet? Say "create my Kaax account and guide me step by step" — kaax_start_onboarding opens the signup form and kaax_complete_onboarding binds the new account to your session automatically. No web app needed.

Advanced / CI only: if you specifically want to pin a key (e.g. a headless pipeline), you can still set KAAX_API_KEY in the MCP client env. The installer no longer writes an empty placeholder, because the authorize flow is the supported path for humans.

Manual config (if you'd rather skip the installer)

Paste this block into your MCP client's config and restart:

{
  "mcpServers": {
    "kaax": {
      "command": "npx",
      "args": ["-y", "kaax-mcp"],
      "env": {
        "KAAX_API_KEY": "",
        "KAAX_LOCALE": "es"
      }
    }
  }
}

Config file locations:

• Claude Desktop: %APPDATA%\Claude\claude_desktop_config.json (Windows) · ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)
• Claude Code: ~/.claude.json (global) or .mcp.json (project root)
• Cursor: ~/.cursor/mcp.json
• Windsurf: ~/.codeium/windsurf/mcp_config.json
• Codex (OpenAI Codex CLI / ChatGPT app): ~/.codex/config.toml — TOML, same path on Windows / macOS / Linux

Zed

Add to ~/.config/zed/settings.json:

{
  "context_servers": {
    "kaax": {
      "command": { "path": "npx", "args": ["-y", "kaax-mcp"] },
      "env": { "KAAX_LOCALE": "es" }
    }
  }
}

Free vs Pro tier

The MCP works without a paid subscription — onboarding, downloading the desktop apps, converting shapefiles and getting tag/config suggestions all run on the Free tier. Tools that read or write account data (analyses, fields, models, etc.) are tagged [Pro] in their descriptions; calling one from a Free account returns a localized "necesitás Pro" message with the upgrade URL instead of failing with a raw 403.

The agent should run kaax_check_license first when the user wants to do anything beyond onboarding — that's a single cheap call that tells it exactly what's available. Free-tier limits (5 fields, 1 local model, 3 custom configs, no API access) are enforced server-side; the MCP just gives clearer messages than the raw 403.

Language (KAAX_LOCALE)

User-facing strings default to Spanish because that's Kaax's primary market. Set KAAX_LOCALE=en in your MCP client env to switch to English:

"env": {
  "KAAX_API_KEY": "…",
  "KAAX_LOCALE": "en"
}

The agent (Claude) translates the rest fluently on its own, so even without setting KAAX_LOCALE you can chat in either language and the user-facing answers will be in your language. The env var only affects the small set of stub messages that the LLM tends to copy verbatim (URLs, error codes, "this requires Pro").

Override the base URL (private deployments only)

"env": {
  "KAAX_API_KEY": "…",
  "KAAX_BASE_URL": "https://kaax.acme-internal.com"
}

Security

Read kaax://docs/security from inside the MCP itself, or the short version below:

• API key read from KAAX_API_KEY once, never logged, sent only over HTTPS.
• Every API call is scoped to the api-key owner — the server cannot fetch other users' data.
• kaax_peer_config_suggestions is the only tool that touches anonymised aggregate data; the server endpoint enforces a minimum sample size, excludes the caller, and rounds numeric values into natural quanta so a single contributor cannot be re-identified.
• All write endpoints (kaax_attach_field_tags, anything creating data) are rate-limited server-side (30/min/key) and audit-logged.
• Shapefile conversion is local file I/O — your .shp never leaves your machine.

Performance & resource use

The MCP is engineered to stay light:

• Stateless tools — no in-process caches that could grow unbounded.
• HTTP only — the MCP never opens a Mongo / Redis / S3 client. All DB access stays on the Kaax server, which already pools connections at maxPoolSize: 5 per instance with the shared dbConnect() cache.
• Bounded polling — kaax_complete_onboarding and kaax_check_download_status use exponential back-off with a hard wall (15 min for signup, configurable for downloads). They never spin.
• Streamed downloads — kaax_download_kaax pipes the response body directly to disk; binaries never live in memory.
• Detached child processes — openBrowser spawns + unrefs the browser so the MCP exits cleanly even if you leave the browser open.

Support

• Email: [email protected]
• Website: https://www.kaax-agritech.com

License

MIT.