Spatial intelligence, wired straight into your agent

What geog.ai over MCP is

An MCP client (or an agent runtime that speaks MCP) connects once, discovers the tool catalog with a free tools/list call, then calls tools with tools/call. Every tool is a thin, audited wrapper over a registered geog.ai capability — there is no duplicate business logic and the LLM in your agent never invents spatial numbers.

For a human developer: it is the fastest way to give an existing assistant terrain, flood, routing, siting, change-detection, and evidence tools without writing a REST client. For an autonomous agent's operator: the catalog is self-describing — cost, required scope, and sync/async + poll route are all visible from tools/list, so a planner can judge entitlement, budget, and polling before it commits.

Connect

Use a geog.ai API key as a bearer token. The same key's scopes gate which tools can execute (see Scopes).

Claude Code

Terminal

claude mcp add geog-ai --transport http https://api.geog.ai/v1/mcp \
  --header "Authorization: Bearer $GEOG_API_KEY"

Claude Desktop / generic MCP client config

JSON config

{
  "mcpServers": {
    "geog-ai": {
      "type": "streamable-http",
      "url": "https://api.geog.ai/v1/mcp",
      "headers": { "Authorization": "Bearer YOUR_GEOG_API_KEY" }
    }
  }
}

Raw JSON-RPC (curl)

List tools — free, unmetered

curl -s https://api.geog.ai/v1/mcp \
  -H "Authorization: Bearer $GEOG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Call a tool — metered per capability

curl -s https://api.geog.ai/v1/mcp \
  -H "Authorization: Bearer $GEOG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call",
       "params":{"name":"get_spatial_context",
                 "arguments":{"device_id":"sensor_h2s_023"}}}'

Tool catalog

Rendered live from the capability registry (/assets/capabilities.json). Each tool delegates to a deterministic capability. Cost is the metered MCP charge in DC (Decision-Credit units); where the equivalent REST ACU rate differs it is shown in parentheses — see the rate card. Async tools return a job id; poll the capability-specific REST route shown in the Kind column.

Scopes & the 403 wall

Tool calls enforce capability-aware API-key scopes before anything executes. A read-only key can use every discovery and read tool but receives HTTP 403 (insufficient_scope) the moment it calls a compute-job tool.

Error taxonomy & recovery

A failed capability returns a normal MCP result with isError:true. The payload carries a machine-readable code and a boolean retryable flag, so an agent branches on structure, not on message text. The full per-code taxonomy is also available over plain HTTP at GET /v1/capabilities (error_taxonomy).

Readiness, trust & provenance

Every successful tool result ships three honesty fields so an agent can decide how far to trust an answer before it acts on it.

• trust_level — a per-result grade that rolls up source quality and degradation. For multi-step plans, per-step trust levels roll up into a plan-level trust_level — a plan is only as trustworthy as its weakest step.
• provenance — the actual data sources used, including whether a real source (e.g. USGS 3DEP DEM, LANDFIRE FBFM40 fuel, Overture GERS entities) or a flagged synthetic fallback answered. Fallbacks are never silent.
• validation — input and geometry checks that passed, plus any quality gates (e.g. HLS minimum clean-scene count) that were enforced.

Async jobs & polling

Simulation, optimization, export, prediction, and calibration tools run as async jobs. The tools/call returns immediately with a job id; MCP itself has no generic job wrapper, so you poll the exact REST route listed in that tool's row — this varies by capability. Simulation and optimization use GET /v1/simulate/jobs/{job_id} (and its /result sub-route); predictions poll GET /v1/predict/zone_risk/{id}; GeoParquet exports poll GET /v1/export/geoparquet/{id} (and /download); calibration follows its admin calibration routes. Always use the poll route shown for the tool you called.

1 — submit (metered once, at submission)

curl -s https://api.geog.ai/v1/mcp \
  -H "Authorization: Bearer $GEOG_API_KEY" -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call",
       "params":{"name":"simulate_flood",
                 "arguments":{"bbox":[-105.1,39.0,-105.0,39.1],"rainfall_mm":100}}}'
# -> result contains a job id, e.g. "job_id":"sim_9f2a"

2 — poll status until terminal

curl -s https://api.geog.ai/v1/simulate/jobs/sim_9f2a \
  -H "Authorization: Bearer $GEOG_API_KEY"
# status: queued -> running -> succeeded | failed

3 — fetch the result on success

curl -s https://api.geog.ai/v1/simulate/jobs/sim_9f2a/result \
  -H "Authorization: Bearer $GEOG_API_KEY"

Metering & what is free

• Free & unmetered: initialize, ping, tools/list, and the discovery tools list_capabilities and discover_spatial_datasets.
• Metered: every tools/call to a compute capability, charged in Decision-Credit (DC) units — the per-capability step_cost shown in each tool's Cost column. This can differ from the corresponding REST endpoint's ACU rate (e.g. a flood simulation is 10 DC via MCP vs 80 ACU on REST); where they differ the REST ACU rate is noted alongside. See each tool's row for the exact charge.
• Once, at submission: async jobs meter only the submit call; polling and result fetch are free.

MCP charges are in DC (Decision-Credit units); see the rate card for the equivalent REST ACU rates and DC→USD conversion.

Related

• Search by problem: the Capability Explorer lets you type a problem ("flood risk", "sensor placement", "evacuation") and get the matching tool.
• Natural-language analysis without MCP: POST /v1/analyze — see the quickstart.
• Capability discovery over plain HTTP: GET /v1/capabilities (public).
• Full REST reference: the API Reference.