Tool reference

The MCP gateway turns Geopera’s operation surface into roughly 188 callable tools. Each tool name is a dotted operation_id, its input schema is that operation’s typed request body, and it carries the same scope and side-effect tier the operation enforces on POST /v1/op/{operation_id}.

The surface now includes the read and list operations an agent uses to read back what it creates — list and fetch orders, collections, items, notifications, balances, usage, job lists, alert rules and events, API keys, analytics indices, STAC search, and more. Every read tool carries readOnlyHint, so a well-behaved client knows it is safe to call freely. The practical effect: an agent can place an order and then poll its status, or create a collection and then list its contents, without leaving the governed surface.

The gateway adds nothing the operation does not already declare: it names each tool by its operation_id and stamps safety hints derived from the operation’s scope and side-effect tier. For how to connect a client, see Hosted MCP and the local quickstart.

How an operation becomes a tool

Every Geopera operation is reachable as POST /v1/op/{operation_id} with a JSON body. The gateway exposes one tool per customer-facing operation. The mapping is direct:

The tool name is the canonical operation identity, not a slugified label. Calling the catalog.search tool with a body is exactly equivalent to POST /v1/op/catalog.search with that body, run as the identity behind the bearer token your MCP client presents. Scopes and authentication are unchanged from the HTTP surface — see Authentication and Scopes.

Side-effect tiers and safety hints

The gateway translates each operation’s x-side-effect tier into MCP ToolAnnotations so a client can reason about safety before it calls:

external_spend tools (money or external provider spend) are marked idempotent because their dedicated route honours an Idempotency-Key — a repeat with the same key is side-effect-free. See Idempotency and Errors. The scope and tier are also placed in each tool’s structured meta (x-required-scope, x-side-effect, x-produces) so a client can filter or route without parsing the description text.

Why some operations are not tools

A focused set of operations stays excluded. None of these are things an agent needs to work around — each is excluded for a concrete reason:

• Raster tiles and rendered images — map tiles and rendered PNG/JPEG/TIFF/WebP outputs (for example cog.tile.render, WMTS capabilities). These are frontend map plumbing meant for a tile-rendering map view, not a request-to-single-result tool.
• Binary downloads — file exports, generated reports (reports.generate), and clip downloads (clip.job.download) return large binary payloads. Those belong on a signed URL the agent can hand off, not inlined into a tool result, so the download operation itself is withheld.
• Streaming responses — NDJSON and server-sent-event listings and exports (for example catalog.search_stream) do not fit the MCP request → single-result model. Their paged, non-streaming siblings are exposed instead (the paged stac.search and catalog.search are tools; the streaming export is not).
• Admin, cron, and unsafe mutations — admin/internal/cron operations are scrubbed from the customer surface entirely, and a small set of untyped destructive or external-spend mutations is 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 (see the side-effect table above).

To enumerate the exact tools your gateway exposes at runtime, call list_tools from your MCP client and read each tool’s name, annotations, and meta.

Exposed tools by domain

The tables below list representative tools, grouped by operation domain — both the read/list tools an agent uses to inspect state and the governed mutations it uses to change it. Each row is callable as the tool of that name and as POST /v1/op/{name}. For the authoritative, up-to-the-minute set, call list_tools from your MCP client.

catalog

items

assets

collections

projects

orders

processing

clip

analytics

band_formulas

visualization

uploads

share

provenance

alerts

event_subscriptions

notifications

billing

payment_methods

api_keys

organizations

Worked example: the catalog.search tool

catalog.search (scope catalog:read, side-effect read) searches a commercial-imagery host’s STAC catalog and price-enriches the results. As an MCP tool it carries readOnlyHint=true, and its input schema is the operation’s typed request body, CatalogSearchInput:

The tool also exposes an optional x-api-key header field, mapped from the operation’s header parameter and forwarded with the request; in normal use your MCP client’s bearer token is the identity, so you leave it unset. See Pagination for the next cursor contract and Concepts for the operation model.

A tool call carries arguments matching that schema:

{
	"host_name": "umbra",
	"bbox": [-122.52, 37.7, -122.35, 37.83],
	"datetime": "2024-06-01T00:00:00Z/2024-09-01T00:00:00Z",
	"query": { "cloudCoverage": { "LTE": 10 } },
	"limit": 50
}

Because the tool maps directly to the operation, the same arguments are a valid HTTP request body. The equivalent direct call:

curl -X POST https://api.geopera.com/v1/op/catalog.search \
  -H "Authorization: Bearer gpra_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "host_name": "umbra",
    "bbox": [-122.52, 37.70, -122.35, 37.83],
    "datetime": "2024-06-01T00:00:00Z/2024-09-01T00:00:00Z",
    "query": { "cloudCoverage": { "LTE": 10 } },
    "limit": 50
  }'

Errors surface as RFC 9457 application/problem+json on the HTTP surface and propagate to the tool result — a missing scope, an invalid body, or a rate limit all carry a typed type and detail. See Errors and Rate limits.

See also

• Hosted MCP — connecting an MCP client with OAuth or a forwarded token
• Local quickstart — running the gateway over stdio with a static token
• Operations — the full operation index behind every tool
• Scopes — what each *:read / *:write scope grants