Verify your setup

Once your MCP client is configured with GEOPERA_API_URL and GEOPERA_API_TOKEN, the fastest way to confirm everything works is to ask the agent to run one low-risk operation and check that it comes back with a result. If a read succeeds, your client is connected, your credentials reach Geopera, and the tools are exposed correctly.

Run a low-risk operation

Pick a read-only operation — a catalog search or a list — so there are no side effects and nothing to set up. From your MCP client, prompt the agent in plain language, for example:

“Search the Geopera catalog and show me the first few items.”
“List my organization’s items, limit 5.”

The agent will call the matching Geopera tool (for example items.search_org) with a small JSON argument object like {"limit": 5}. A successful call returns a structured result — typically an object containing items, features, or results. An empty list is still a success: it means the call reached Geopera and was authorized, even if your organization has no matching records yet.

For the full catalog of operations and each one’s request shape, see Operations.

What a good result looks like

A healthy round trip confirms three things at once:

Connected — the client found the Geopera tools and could call one.
Authenticated — your GEOPERA_API_TOKEN (a session token obtained by signing in to Geopera, or a minted gpra_ API key) was accepted.
Authorized — the credential carried the scope the operation requires (for example items:read).

Every operation is invoked as POST /v1/op/{operation_id} with a JSON body — there are no GET/PUT/DELETE verbs, and no path or query parameters. The agent’s tool arguments map directly to that JSON body, so a successful read is the same call any client makes. See Authentication for how to mint or rotate a key and Scopes for the scope each operation needs.

Troubleshooting

Symptom	Cause and fix
The agent reports no Geopera tools available	The MCP client isn’t connected. Recheck your client config: `GEOPERA_API_URL` should point at the hosted Geopera URL and `GEOPERA_API_TOKEN` must be set. Restart the client so it reloads the configuration.
The call fails with a `401`	Your token was rejected. Confirm `GEOPERA_API_TOKEN` is a valid session token or a `gpra_` API key, unexpired, and sent as the Bearer credential. See Authentication.
The call fails with a `403`	The credential authenticated but lacks the required scope (for example `items:read`). See Scopes.
The call succeeds but returns an empty list	This is normal — the operation reached Geopera and was authorized, but your organization has no matching records yet.

For the error envelope behind any non-2xx response, see Errors.