Quickstart: Hosted MCP (HTTP + OAuth)

The hosted MCP gateway is one public endpoint that any user can point an MCP client at; the client runs a browser sign-in once, and every tool call thereafter runs as that real signed-in user — their scopes, their audit trail, their provenance.

This is the product version of the MCP gateway. You do not run a process, supply a token in a config file, or manage a venv. You add a remote server URL to your MCP client, approve a sign-in prompt in your browser, and the agent inherits your identity. For the self-hosted, single-user, token-in-config alternative, see the local stdio quickstart.

The endpoint

https://mcp.geopera.com/mcp/

This is a streamable-HTTP MCP server. Every tool call is proxied to the Geopera API at https://api.geopera.com as POST /v1/op/{operation_id} — the same typed operation surface the REST API and SDKs use. The tool set is the customer-facing operation registry: one tool per operation, with admin and internal operations excluded. See Operations for the full catalog.

How sign-in works

When you add the remote server, the first tool call triggers a browser sign-in. You never paste a credential into your MCP client.

1. Your browser opens, you sign into Geopera, and you approve the requested access.
2. The client receives an access token bound to your real identity.
3. On every tool call, the client sends that token to the gateway, which runs the call as you against the Geopera API.

Because your own token is used per request, each call runs as you. The agent can do exactly what you can do — no more. Scopes, rate limits, audit log entries, and data provenance all reflect your account, not a shared service identity. See Authentication and Scopes for what a session token carries.

Connect from an MCP client

The exact UI differs per client, but the configuration is always the same: a single remote/HTTP server URL with no embedded credential. The credential is obtained interactively at first use.

Claude (Desktop / Code) and other clients with native remote support

Add a custom connector / remote MCP server pointing at the URL, then approve the sign-in prompt when it appears:

https://mcp.geopera.com/mcp/

Config-file clients

Clients that take a JSON config for HTTP servers use an mcpServers entry with a url (and no command/args/token — those are for the local stdio path):

{
	"mcpServers": {
		"geopera": {
			"url": "https://mcp.geopera.com/mcp/"
		}
	}
}

On the first tool call your browser opens for sign-in. The client stores the resulting token and refreshes it automatically; you will not be prompted again until it expires or you revoke access.

Verify the connection

After approving sign-in, ask the agent to call a read-only operation. Read operations are annotated with readOnlyHint so a well-behaved client treats them as safe to call without confirmation. For example, prompt the agent to search the catalog:

Search the Geopera catalog for Sentinel-2 imagery over Sydney in the last 30 days.

The agent invokes the catalog.search tool, the gateway calls POST /v1/op/catalog.search as you, and you get results scoped to what your account can see. If you have not yet signed in, this first call is what triggers the browser flow.

Acting as the real user

Every tool carries metadata derived from its operation descriptor so the agent — and you — can reason about a call before it runs:

Because the call runs as you, a spend operation such as orders.archive.place only succeeds if your account holds orders:write; the resulting order is recorded against you with full lineage. A billing problem comes back as an RFC 9457 problem document (for example 402) that the agent can read and explain. For money-moving operations, see Idempotency.

Headless fallback: API key passthrough

The hosted endpoint is built for interactive sign-in, but it also accepts a Geopera gpra_ API key for headless / non-interactive use (CI, a server-side agent, a script). When the MCP client sends its own Authorization header, the gateway uses that credential — so the call runs as whatever principal the key represents, per request.

Configure your client to attach a bearer header to the remote server:

{
	"mcpServers": {
		"geopera": {
			"url": "https://mcp.geopera.com/mcp/",
			"headers": {
				"Authorization": "Bearer gpra_your_api_key_here"
			}
		}
	}
}

When a credential is present on the request, the browser sign-in is skipped and the supplied key is used directly. Mint and manage gpra_ keys as described in Authentication; the key’s scopes govern exactly what the agent can do.

Edge cases and gotchas

• Trailing slash. Use the path exactly: https://mcp.geopera.com/mcp/. Some clients are strict about the trailing segment.
• Streaming operations are not exposed. Operations that return NDJSON or binary streams do not fit the request → single-result tool model and are excluded from the tool set. Their non-streaming siblings are available instead. Use the REST API directly when you need a raw stream.
• Admin and internal operations are never exposed. The hosted surface is the customer-facing operation set; admin.*, *_internal, and diagnostics operations are filtered out regardless of your account.
• Token expiry. Session tokens are short-lived and refreshed by the client. If tool calls suddenly fail with a 401, re-trigger sign-in (most clients re-prompt automatically). A freshly revoked token may remain valid for up to a few minutes.
• One identity per connection. In sign-in mode each connected client carries its own session token; there is no shared service identity. In API-key mode the call runs as the key’s principal per request.
• Scopes are enforced server-side. A missing scope returns a problem document from the API, not a gateway error — the agent sees a normal operation failure it can reason about. See Scopes and Errors.

What’s next

• Local MCP quickstart — run the gateway yourself over stdio with a single token, for one user.
• AI agents (MCP) overview — how to connect an agent and why it is safe by design.
• Operations — the full catalog of tools an agent can call.
• Authentication — session tokens vs. gpra_ API keys.