Setup - Geoptie Docs

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.

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.

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.

Claude Code

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:

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:

{
  "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:

[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:

{
  "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 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 with what you asked, the tool name if you have it, and the request id from the error. Every failed call includes one.

​Claude Code

​Cursor

​Codex

​Any other client

​Check the connection

​If it does not connect

​Need help

Claude Code

Cursor

Codex

Any other client

Check the connection

If it does not connect

Need help