cart-mcp

This MCP server computes soil resource concern ratings for an area of interest (AOI) using the same SQL pipeline CART (Nemecek, J. & Peaslee, S., USDA NRCS) uses against the public USDA Soil Data Access (SDA) web service, and exposes the results as MCP tools, resources, and prompts for AI-assisted conservation planning.

What this is not: an official NRCS/CART ranking engine. CART's full ranking score combines five components (Vulnerability, Planned Practice Effects, Resource Priorities, Program Priorities, Cost Efficiency). This server computes only the soil-condition ratings (the vulnerability input) from published SSURGO soil data. Official program determinations come from your NRCS field office.

Install

Requires Python >= 3.12 and uv.

uv sync

Related MCP server: mireye-mcp

Run

uv run cart-mcp                 # stdio transport (default, for MCP clients)
uv run cart-mcp --transport streamable-http --port 8000   # Streamable HTTP (recommended for remote/HTTP clients)
uv run cart-mcp --transport sse --port 8000               # legacy HTTP+SSE transport

Or during development:

uv run python -m cart_mcp

Client configuration

Add to your MCP client config (opencode, Claude Desktop, etc.):

{
  "mcpServers": {
    "cart": {
      "command": "uv",
      "args": ["--directory", "/path/to/cart-assistant", "run", "cart-mcp"]
    }
  }
}

opencode users can preconfigure both servers in a root opencode.json; all other clients use examples/mcp_config.json as a template.

QGIS integration (external agent harness)

Drive QGIS Desktop and cart-mcp from one agent (e.g. opencode): ask the agent to extract an AOI from the QGIS canvas, rate it with cart-mcp, and map the result back into QGIS. Tools appear prefixed: cart_* (rating tools) and qgis_* (QGIS tools).

Setup (QGIS MCP plugin install, server registration for opencode and other MCP clients) and a fully worked run (T89 Fld1, step-by-step prompts, expected outputs, troubleshooting) are in examples/qgis_cart_harness_example.md.

Orchestration pattern

1. AOI: ask for the canvas extent or a layer's features → EPSG:4326 WKT in one call: qgis evaluate_expression with geom_to_wkt(transform($geometry, 'EPSG:4326')) (cart-mcp requires EPSG:4326).

2. Rate: cart_rate_aoi (or cart_rate_aois for several landunits) with concerns as an optional subset; maps via cart_get_aoi_soil_map / cart_get_aoi_risk_map.

3. Map: save the returned GeoJSON to a temp file → qgis add_vector_layer → set_layer_style → zoom_to_layer → render_map.

Caveats

• Ratings are advisory; keep the returned disclaimer and soils_metadata (survey dates).

• Each rating hits the public SDA web service (~10 s); avoid cart_validate_pipeline in chat.

• The QGIS socket binds localhost with no auth and qgis_execute_code runs arbitrary PyQGIS: on shared machines set QGIS_MCP_TOKEN in both the QGIS environment and the server's environment block.

• 117 QGIS tools bloat model context; on token-strapped models set QGIS_MCP_TOOL_MODE=compound (27 grouped tools) via the server environment, or gate with "tools": {"qgis_*": false} + per-agent re-enable.

Tools

Resources

Prompts

Data sources and public accessibility

All data used at runtime is public — no API keys, no credentials, no internal endpoints.

Notes:

• The SDA web service is a free public federal service without an SLA; the server makes one submission per rate_aoi call. Query.aspx (SOAP) is the documented fallback if the post.rest endpoint ever changes.

• Ratings are only as fresh as each survey area's last publication (saverest); the server returns these dates with every rating.

• Embedded data derives only from USDA NRCS federal publications; no third-party documents (e.g., journal articles) are redistributed.

• SDA request constraints (100k row cap, timeout/memory failure modes) are enforced by the server's request caps (landunits, AOI area, timeout).

• CART SQL queries, rating methodology, and domain tables are documented in the public CART reference repository: https://github.com/jneme910/CART (Nemecek, J. and Peaslee, S., USDA NRCS).

Development

uv run pytest                # offline tests (default)
uv run pytest -m network     # opt-in tests requiring live SDA access

License

MIT for the server code; embedded data is derived from public-domain US federal government works. See LICENSE.