AI agents (MCP)

Geopera exposes its operations to AI agents through the Model Context Protocol (MCP). The MCP gateway turns the kernel’s operation registry into a catalog of tools — one tool per operation — so an agent (Claude Desktop, an IDE assistant, your own MCP client) can search imagery, place orders, run analytics, and manage data with the same auth, scopes, validation, and provenance as any other client.

How it works

The gateway is a standalone process that reads the kernel’s reflected OpenAPI and projects each operation into an MCP tool. It imports nothing from the backend — it’s just another client of the same POST /v1/op/{operation_id} surface the REST API, the SDKs, and the portal use. Because the OpenAPI is a projection of the registry, the tool set tracks the registry by construction: add an operation, get a tool, with no extra wiring.

What the projection adds on top of the raw operations:

  • Tool name = operation_id. orders.archive.place is the tool name — the canonical kernel identity, so there’s no separate naming scheme to learn.
  • Safety hints from the side-effect tier. Each tool is annotated from the operation’s x-side-effect: read operations get a readOnlyHint, destructive operations get a destructiveHint. An agent can reason about whether a call is safe before it makes it.
  • Streaming operations excluded. Operations that return NDJSON or binary streams (x-raw-response) don’t fit the request → single-result tool model and are excluded; their non-streaming siblings are exposed instead.

Run the gateway

The gateway connects over stdio by default (how Claude Desktop and most MCP clients attach):

bash 
GEOPERA_API_URL=https://api.geopera.com \
GEOPERA_API_TOKEN=<your-jwt> \
python server.py

Set MCP_TRANSPORT=http to expose an HTTP endpoint instead of stdio. The token is a normal Geopera access token (obtain it via the OIDC token endpoint — see Authentication), so the agent acts as whatever principal that token represents, with exactly that principal’s scopes. An agent can do nothing the token couldn’t do directly.

What an agent can do

Because every operation is a tool, an agent can drive complete workflows:

  • Discover — catalog.search, items.search, analytics.operations.list (read, safe).
  • Estimate — orders.archive.estimate, orders.tasking.estimate (read, safe — get a price before spending).
  • Act — orders.archive.place, processing.create_and_dispatch, billing.topup (spend; flagged so the agent knows real money / credits move).
  • Analyse — analytics.execute (run change detection, zonal stats, indices over items).

The same scope and provenance guarantees apply. An agent calling orders.archive.place needs orders:write; the order it places is recorded with full lineage; a payment problem comes back as a 402 it can reason about. Nothing about the agent path is a lesser-governed shortcut.

Why this is safe by design

The governance lives in the kernel, not in the client. So an agent gets the same treatment as the portal or an SDK:

  • it can’t invoke an operation it lacks the scope for,
  • it can’t skip input validation or produce data without recording provenance,
  • and the side-effect tier is surfaced as a tool annotation, so a well-behaved agent surfaces destructive or money-moving actions for confirmation before calling them.

This is the practical reason the operation model matters for agents: the safety properties are intrinsic to the capability, so exposing capabilities to an autonomous caller doesn’t require a second, parallel safety system.