AI agents (MCP)

The Geopera MCP server lets an AI agent (such as Claude) call Geopera operations as tools, so it can discover imagery, place orders, and run analytics with the same auth, scopes, and provenance as any other client.

Overview

The MCP server exposes a curated set of Geopera operations as Model Context Protocol (MCP) tools and proxies every tool call to POST /v1/op/{operation_id}. It is another client of the same typed surface the REST API, the Python SDK, the TypeScript SDK, and the CLI consume.

Each tool carries the canonical operation identity and safety hints:

• Tool name == operation_id. The tool for placing an archive order is named orders.archive.place — the same dotted operation id you call directly. There is no second naming scheme to learn.
• Safety hints from the side-effect tier. Each tool is annotated from the operation’s side-effect tier: read operations set readOnlyHint, destructive operations set destructiveHint, and external_spend operations set idempotentHint (they carry an idempotency contract). A client can reason about whether a call is safe before it makes it. See Safety and side effects.
• Structured metadata. Each tool’s meta exposes its side-effect tier, required scope, and produced outputs, so an agent can filter or route on them without parsing the description text.
• Customer-safe surface. The server exposes only customer-facing operations — admin, internal, cron, and diagnostics operations are never available as tools.

What gets exposed

The gateway exposes ~188 tools — the customer-facing operation surface, including the read and list operations an agent uses to read back what it creates. An agent can list and fetch your orders, collections, items, notifications, balances, usage, job lists, alert rules and events, API keys, analytics indices, and more — every such read tool carries readOnlyHint, so a client knows it is safe to call freely. This means an agent can place an order and then poll its status, or create a collection and then list its contents, all through the same governed surface. See the Tool reference for the full list.

A focused set of operations stays excluded, for reasons an agent never needs to work around:

• Raster tiles and images (map tiles, rendered PNG/JPEG/TIFF/WebP) — frontend map plumbing meant for a tile-rendering map view, not a request-to-single-result tool.
• Binary downloads (file exports, generated reports, clip downloads) — large egress payloads that belong on a signed URL, not inlined into a tool result.
• Streaming responses (NDJSON/SSE listings and exports) — a single-result tool does not fit a stream; the paged, non-streaming sibling is exposed instead.
• Admin, cron, and unsafe mutations — admin/internal/cron operations and a small set of untyped destructive or external-spend mutations are withheld for safety. The governed, typed mutations you need (place an order, create a collection, top up credits) remain available with their side-effect hints intact.

The server exposes only tools. It does not expose MCP resources or prompts. Every capability is a callable tool whose name is an operation id and whose input schema is that operation’s request body.

Connect or run locally

You reach the MCP server one of two ways:

• Run it locally over stdio. Your MCP client (Claude Desktop, Claude Code, or your own) spawns the server process and talks to it over stdin/stdout. You supply a single token — a gpra_ API key or a session token (obtained by signing in to Geopera) — and every tool call runs as that principal. See Run locally (stdio).
• Connect to the hosted server. Point your MCP client at the hosted streamable-HTTP endpoint. The client runs a browser sign-in flow, you sign into Geopera, and the server forwards your verified token upstream per request — so the agent acts as the real signed-in user, with that user’s scopes, audit trail, and provenance, and no keys are copy-pasted. See Hosted server.

Either way the agent’s reach is exactly the scopes on the token: it can do nothing the token could not do directly. Errors come back as RFC 9457 problem+json the agent can reason about.

Explore

A first look

To wire the MCP server into Claude Desktop, add the server to claude_desktop_config.json (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
	"mcpServers": {
		"geopera": {
			"command": "geopera-mcp",
			"env": {
				"GEOPERA_API_URL": "https://api.geopera.com",
				"GEOPERA_API_TOKEN": "gpra_your_api_key"
			}
		}
	}
}

Restart the client and the Geopera tools appear. Ask the agent to estimate an archive order and it will call orders.archive.estimate (a read-only tool, safe to call freely); ask it to place one and it will call orders.archive.place (an external_spend tool the client should surface for confirmation first). Full walkthroughs live in Run locally (stdio) and Recipes.

What a tool call resolves to

Every tool is a thin proxy. Calling the orders.archive.estimate tool with a JSON argument object resolves to exactly the same request a direct operation call would make:

POST /v1/op/orders.archive.estimate HTTP/1.1
Host: api.geopera.com
Authorization: Bearer gpra_your_api_key
Content-Type: application/json

{ "item_ids": ["sentinel-2:S2B_MSIL2A_20240115..."], "product": "analytic_sr" }

The tool’s input schema is the operation’s request-body schema, its output is the operation’s response, and a failure is the operation’s RFC 9457 problem document — there is no MCP-specific shape to learn. Geopera enforces scopes, validation, and provenance identically regardless of whether the caller is an agent, an SDK, or the portal.

Why this is safe by design

An agent gets the same treatment as any other client: it cannot invoke an operation it lacks the scope for, it cannot skip input validation or produce data without recording provenance, and the side-effect tier is surfaced as a tool annotation so a well-behaved client can require confirmation before a destructive or money-moving call. Exposing capabilities to an autonomous caller does not require a second, parallel safety system — the safety properties are intrinsic to each operation. The mechanics of acting on those hints are covered in Safety and side effects.