Quickstart: Local (stdio)

Run the Geopera MCP server as a local process that an MCP client launches over stdio, authenticated with one token you supply — a gpra_ API key or a bearer token.

You install the Geopera MCP server, then point your MCP client at it with your token. The server exposes each Geopera operation as a tool and proxies every tool call to POST /v1/op/{operation_id} as the principal behind your token. For the bigger picture, see AI agents (MCP). For the multi-user, browser-sign-in alternative, see the hosted quickstart.

Prerequisites

  • An MCP client — Claude Desktop or Claude Code.
  • A Geopera token. Either a minted API key (prefix gpra_) or a bearer access token. The server sends this token on every upstream call, so the agent acts as exactly that principal, with exactly that principal’s scopes — it can do nothing the token couldn’t do directly. See Authentication and Scopes.

1. Install the Geopera MCP server

Install the geopera-mcp package from PyPI:

bash 
pip install geopera-mcp

This installs the geopera-mcp command, which speaks the stdio transport that MCP clients attach to.

2. Verify it runs

Before wiring it into a client, confirm the server starts and can reach the API. It defaults to the stdio transport, which is exactly how an MCP client attaches.

bash 
GEOPERA_API_URL=https://api.geopera.com \
GEOPERA_API_TOKEN=gpra_your_key_here \
geopera-mcp

On startup the server reads the Geopera API at GEOPERA_API_URL and builds one tool per customer operation, then waits on stdin for an MCP client — there’s no interactive prompt, so this is expected. Press Ctrl+C to stop it; your MCP client will launch its own copy.

3. Wire it into your MCP client

Add a geopera entry under mcpServers. The command is geopera-mcp and env carries the two variables the server reads.

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

Replace gpra_your_key_here with your API key or bearer token. The token value may be either form — a raw gpra_ API key is accepted as-is, and a bearer token works too.

Config file location

The same mcpServers block goes in your client’s config file:

ClientPlatformLocation
Claude DesktopmacOS~/Library/Application Support/Claude/claude_desktop_config.json
Claude DesktopWindows%APPDATA%\Claude\claude_desktop_config.json
Claude Codeany.mcp.json in your project root (or run claude mcp add)

After editing the file, fully restart the client so it relaunches the server with the new config.

Environment variables

These are the only two variables the local stdio path reads:

VariableRequiredMeaning
GEOPERA_API_URLrecommendedThe Geopera API the server proxies to. Set it to https://api.geopera.com for production.
GEOPERA_API_TOKENyesThe token sent on every upstream call — a gpra_ API key or a bearer token. If unset, the server still starts but tool calls go out unauthenticated and are rejected.

Worked example: a token in a real config

Suppose you minted an API key. Your full Claude Desktop config on macOS would be:

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

Restart Claude Desktop, open a new chat, and you’ll see the Geopera tools available. Ask the agent to call a read-only operation first — for example, searching the catalog — to confirm the round trip. Each tool is named after its operation (catalog.search, orders.archive.place, and so on), so what you see in the tool list maps one-to-one to the operations reference.

Gotchas

  • Restart fully after editing the config. MCP clients read the server config at launch and reuse the spawned process; a window reload may not pick up changes.
  • The agent inherits your token’s scopes. A tool call that needs a scope the token lacks comes back as an error; a spend operation that hits a payment problem comes back as a 402. Mint a key with only the scopes the agent needs — see Scopes.
  • Token unset means unauthenticated calls. If GEOPERA_API_TOKEN is missing the server logs a warning and still starts, but every tool call is rejected upstream. Set the token.

Next steps