> ## Documentation Index
> Fetch the complete documentation index at: https://geoptie.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Setup

> Connect Claude Code, Cursor, Codex or any other MCP client.

Every client needs the same three things.

| Setting       | Value                         |
| ------------- | ----------------------------- |
| URL           | `https://mcp.geoptie.com/mcp` |
| Transport     | Streamable HTTP               |
| Authorization | `Bearer YOUR_API_KEY`         |

Create the key first, in the dashboard under **API keys** in the sidebar. It is shown only once.
The same key works for the API and the MCP server, so if you already have one, use it.

<Warning>
  Keep the key out of source control. Every example below reads it from the
  `GEOPTIE_API_KEY` environment variable, so put it in your shell profile or a secret
  manager rather than in a file you commit.
</Warning>

<Note>
  Use the `https://` URL. Your key is sent with every request, and a client pointed at
  `http://` has already sent it in the clear before the redirect to HTTPS happens.
</Note>

## Claude Code

```bash theme={null}
claude mcp add --transport http geoptie https://mcp.geoptie.com/mcp \
  --header "Authorization: Bearer $GEOPTIE_API_KEY"
```

Add `--scope user` to make it available in every project rather than just the current one.

Check it worked:

```bash theme={null}
claude mcp list
```

The server should show as **Connected**. Inside a session, `/mcp` opens the same view with
more detail.

## Cursor

Add the server to `.cursor/mcp.json` in your project, or `~/.cursor/mcp.json` to use it
everywhere:

```json theme={null}
{
  "mcpServers": {
    "geoptie": {
      "url": "https://mcp.geoptie.com/mcp",
      "headers": {
        "Authorization": "Bearer ${env:GEOPTIE_API_KEY}"
      }
    }
  }
}
```

The `${env:...}` syntax reads the key from your environment, so the file stays safe to
commit.

## Codex

Add the server to `~/.codex/config.toml`:

```toml theme={null}
[mcp_servers.geoptie]
url = "https://mcp.geoptie.com/mcp"
bearer_token_env_var = "GEOPTIE_API_KEY"
```

Codex reads the key from that environment variable and sends it as the `Authorization`
header for you.

## Any other client

Any client that supports remote MCP servers with custom headers can connect with the three
settings at the top of this page.

If your client only supports local servers over stdio, put the `mcp-remote` proxy in front:

```json theme={null}
{
  "mcpServers": {
    "geoptie": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.geoptie.com/mcp",
        "--header",
        "Authorization: Bearer ${GEOPTIE_API_KEY}"
      ]
    }
  }
}
```

## Check the connection

Ask your assistant:

> List my Geoptie brands.

It should call `list_brands` and come back with your brands and their ids. That one call
proves the key works, the subscription is active, and the brands the key can reach. Most
other tools take a `brand_id`, so this is where every session starts.

From here, [Recipes](/docs/mcp/recipes) has the questions worth asking first.

## If it does not connect

| What you see                            | Cause                                                 | Fix                                                                                                                                          |
| --------------------------------------- | ----------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `missing_api_key`                       | The `Authorization` header is not reaching the server | Check the header name and the `Bearer ` prefix, and that your environment variable is actually set in the shell your client was started from |
| `invalid_api_key`                       | The key is unknown or revoked                         | Create a new key in the dashboard                                                                                                            |
| `subscription_required`                 | The subscription is not active or is past due         | Update billing in the dashboard                                                                                                              |
| `plan_not_eligible`                     | Your plan does not include API access                 | Upgrade, or contact support                                                                                                                  |
| Connects, but every brand returns `404` | The key is brand-scoped and does not cover that brand | Call `list_brands` to see its scope, or use a workspace key                                                                                  |
| Client reports a login or OAuth prompt  | The client is trying to authenticate the wrong way    | This server takes an API key in a header. Configure the header rather than a sign-in                                                         |

A restart of your client picks up config changes. If a key stops working immediately after
you revoke and replace it, allow a minute for the change to take effect.

## Need help

Email [support@geoptie.com](mailto:support@geoptie.com) with what you asked, the tool name if
you have it, and the request id from the error. Every failed call includes one.