Connect via MCP

MCP (Model Context Protocol) is an open protocol that lets AI clients call external tools. The MaxAEO MCP server wraps the four API endpoints as tools, so once it’s connected you can tell your AI assistant something like “ask ChatGPT and Perplexity how they answer this question and check whether they cite our website” — and it handles submitting, waiting, and reading the results.

Item	Value
URL	https://maxaeo.ai/geoapi/geodata/developer/mcp
Transport	Streamable HTTP (stateless, JSON responses only)
Authentication	Authorization: Bearer <API key> header
Tools	list_platforms, submit_task, get_task, list_tasks — see MCP Tools Reference
Billing and rate limits	Exactly the same as the API: successful tasks use credits and share your account’s balance and limits

Your client must support custom headers

The server authenticates with an API key and doesn’t support OAuth. Your client needs to let you set an Authorization header for a remote MCP server. Clients that only support stdio can bridge through mcp-remote — see below.

Get an API key

Create a key on the API Keys page of the Developer Console. We recommend a dedicated key for MCP (for example, “MCP – my laptop”) so its usage shows up separately and you can disable it on its own. See Manage API Keys.

Configure your client

Claude Code

Run in your terminal:

claude mcp add --transport http maxaeo https://maxaeo.ai/geoapi/geodata/developer/mcp \
  --header "Authorization: Bearer $MAXAEO_API_KEY"

Run export MAXAEO_API_KEY="gdev_…" first. Afterwards, run claude mcp list and check that maxaeo shows as connected.

Cursor

Edit ~/.cursor/mcp.json (global) or .cursor/mcp.json in your project:

{
  "mcpServers": {
    "maxaeo": {
      "url": "https://maxaeo.ai/geoapi/geodata/developer/mcp",
      "headers": {
        "Authorization": "Bearer gdev_your_full_key"
      }
    }
  }
}

Save, then confirm on the MCP page of Cursor’s settings that maxaeo is enabled and lists four tools.

VS Code

Create .vscode/mcp.json in your project. Use inputs so VS Code prompts for the key on first start instead of storing it in the file:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "maxaeo-api-key",
      "description": "MaxAEO API key",
      "password": true
    }
  ],
  "servers": {
    "maxaeo": {
      "type": "http",
      "url": "https://maxaeo.ai/geoapi/geodata/developer/mcp",
      "headers": {
        "Authorization": "Bearer ${input:maxaeo-api-key}"
      }
    }
  }
}

Then enable the maxaeo tools in Copilot Chat’s agent mode.

stdio-only clients

For clients that can only launch local commands (such as Claude Desktop’s config file), use mcp-remote to bridge the remote server into a local process (requires Node.js):

{
  "mcpServers": {
    "maxaeo": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://maxaeo.ai/geoapi/geodata/developer/mcp",
        "--header",
        "Authorization:${MAXAEO_AUTH}"
      ],
      "env": {
        "MAXAEO_AUTH": "Bearer gdev_your_full_key"
      }
    }
  }
}

There’s no space after the colon in Authorization:${MAXAEO_AUTH}; the space lives inside the environment variable’s value. This sidesteps the way some clients handle spaces in arguments.

Other clients

Any client that supports the Streamable HTTP transport and custom request headers works the same way. When adding the MCP server, enter:

• URL: https://maxaeo.ai/geoapi/geodata/developer/mcp
• Header: Authorization with the value Bearer gdev_your_full_key

Protect your config files

A key written into a config file is effectively a plaintext password. Don’t commit an mcp.json that contains a key. When sharing configuration with a team, pass the key through environment variables or your client’s input prompts.

Verify the connection

The server checks your key as soon as the client connects: with an invalid key, the client reports a connection failure or “unauthorized” (HTTP 401). Once connected, try asking your assistant:

List the platforms MaxAEO supports and their prices.

The assistant calls list_platforms and shows the result. This doesn’t use any credits.

Example prompts

Once connected, just describe what you want in plain language, for example:

• “Ask ChatGPT: what are the best mechanical keyboards for programmers? When the answer is ready, list the web pages it cites.”
• “Ask ChatGPT and Perplexity ‘what’s the best CRM for a small team’ using P2, and compare which brands and sources each one cites.”
• “Ask ChatGPT the same question with thinking mode on, and tell me whether thinking was actually on.”
• “I lost the result of the task I just submitted. Find it among today’s tasks by searching for ‘mechanical keyboard’.”

When connecting, the server tells the assistant the recommended flow: call list_platforms first, then submit_task, then get_task repeatedly until the task finishes; and if a submission’s outcome is unknown, look it up with list_tasks instead of submitting again.

Tasks are asynchronous

AI platforms usually take tens of seconds to two minutes to generate an answer (longer with thinking mode on), plus any time spent queueing. After submitting, the assistant needs to call get_task several times to wait for the result. You can also have it set wait_seconds (up to 120) in submit_task, but that’s still subject to your client’s own tool-call timeout. Every submit_task call creates a new task that uses credits if it succeeds. If you don’t want the assistant submitting on its own, set submit_task to require confirmation before each call in your client.

Related

MCP Tools ReferenceParameters, output, and error format for the four tools, plus protocol details.

Billing & CreditsMCP calls share the same balance and billing rules as the API.