<!-- Source: https://docs.geopera.com/api-reference/sdks/mcp/quickstart-local · Markdown for LLMs -->

# 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 — making it the fastest way to drive Geopera from an AI agent.

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)](/api-reference/sdks/mcp). For the multi-user, browser-sign-in alternative, see the [hosted quickstart](/api-reference/sdks/mcp/hosted).

## 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](/api-reference/authentication) and [Scopes](/api-reference/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:

| Client         | Platform | Location                                                          |
| -------------- | -------- | ----------------------------------------------------------------- |
| Claude Desktop | macOS    | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| Claude Desktop | Windows  | `%APPDATA%\Claude\claude_desktop_config.json`                     |
| Claude Code    | any      | `.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:

| Variable            | Required    | Meaning                                                                                                                                                                |
| ------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `GEOPERA_API_URL`   | recommended | The Geopera API the server proxies to. Set it to `https://api.geopera.com` for production.                                                                             |
| `GEOPERA_API_TOKEN` | yes         | The 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](/api-reference/operations).

## 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](/api-reference/errors); 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](/api-reference/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

- [AI agents (MCP)](/api-reference/sdks/mcp) — how the tools and safety hints work.
- [Authentication](/api-reference/authentication) — minting a `gpra_` API key and obtaining bearer tokens.
- [Operations](/api-reference/operations) — the full catalog of tools an agent can call.