How to Connect the Geoapify MCP Server to an AI Client

Connect the Geoapify MCP Server to an AI client

You have an AI client that supports remote HTTP MCP servers and want it to use Geoapify location tools without building a separate REST integration. The client must be MCP-compatible and provide a protected way to configure the Geoapify API key. Add the remote endpoint to the client's MCP configuration, then confirm that the client discovers and can call the tools.

The endpoint is:

https://api.geoapify.com/v1/mcp

Task flow: compatible AI client + protected API key → remote MCP connection → discovered Geoapify tools → verified tool call.

Follow this workflow:

1. Confirm that the client supports remote HTTP MCP servers and an API-key authentication method.
2. Create or select a Geoapify API key and apply appropriate restrictions.
3. Add the endpoint and authentication explicitly through the client's settings, command, or MCP configuration file.
4. Allow the client to initialize the connection and discover tools automatically.
5. Run example location tasks and inspect the selected tools and results.
6. Troubleshoot the stage that failed, then review permissions, privacy, and credit usage.

Do not configure the endpoint as a local stdio process or an SSE server. Client interfaces may call the supported transport “HTTP,” “remote HTTP,” or “Streamable HTTP.”

Official client setup guides

Client configuration formats and settings locations can change independently. Use the appropriate first-party guide together with the Geoapify-specific configuration in this how-to:

ChatGPT is an AI client and can act as an MCP client in developer mode. However, its currently documented authentication choices are OAuth, no authentication, and mixed authentication; they do not include a custom static x-api-key header. Do not put a Geoapify API key in the server URL of a shared or published ChatGPT app. See the ChatGPT implementation page for compatible alternatives.

Check compatibility, create an API key, and configure the MCP connection

Geoapify MCP is a remote HTTP server. The AI client must support remote HTTP or Streamable HTTP MCP connections and at least one protected way to provide a Geoapify API key:

• A private custom x-api-key header.
• A private Authorization header.
• Environment-variable or secret substitution inside an HTTP header.
• A remote-server URL containing the apiKey query parameter.

If a client supports only local stdio servers, or supports only OAuth for remote servers without custom headers or a configurable URL, it cannot connect directly to this endpoint.

Create or select a project in Geoapify MyProjects, copy its API key, and apply restrictions that match the environment sending the MCP requests. Store the key in the client's secret store or in a private environment variable such as GEOAPIFY_API_KEY. Never place the real key in a committed project file.

Choose the strongest authentication method supported by the client:

Treat a URL containing apiKey as a credential. Keep it in private user-level configuration and exclude it from screenshots, shared configuration, exported settings, logs, and version control.

Use these common connection values, translated into the format required by the client:

The client normally sends initialize, negotiates the protocol, and calls tools/list automatically. Do not add an MCP-Protocol-Version header unless you are performing a manual diagnostic or the client explicitly requires it.

For clients without a private custom-header mechanism, use the apiKey query-parameter URL only in private user configuration. If the client publishes or synchronizes that URL, do not use that configuration method.

Use Geoapify MCP with ChatGPT

ChatGPT is an AI client and can act as an MCP client in developer mode. Unlike coding clients that read a local MCP configuration file, ChatGPT requires you to create a developer-mode app explicitly in its web interface. Asking ChatGPT in a normal conversation to connect an MCP server does not add the server.

ChatGPT supports remote streaming HTTP MCP servers, but its currently documented authentication choices are OAuth, no authentication, and mixed authentication. Geoapify MCP currently requires a Geoapify API key through an x-api-key header, an Authorization header, or the apiKey query parameter. ChatGPT does not currently document a protected custom-header field for a static API key.

Do not publish or share a ChatGPT app whose server URL contains a Geoapify API key. A URL such as https://api.geoapify.com/v1/mcp?apiKey=YOUR_API_KEY contains a credential even when ChatGPT labels the connection as having no authentication.

For a secure ChatGPT integration, use one of these approaches:

• Connect through a trusted remote MCP gateway that uses an authentication method supported by ChatGPT and adds the Geoapify API key only on the server side.
• Use an official Geoapify ChatGPT app when one becomes available.
• Use another MCP client that can protect and send a custom x-api-key header.

For current eligibility, developer-mode settings, supported transports, authentication choices, tool scanning, and app selection, see ChatGPT Developer mode.

Configure Geoapify MCP in VS Code with GitHub Copilot

Open or create .vscode/mcp.json in the workspace and merge this configuration with any existing inputs and servers entries:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "geoapify-api-key",
      "description": "Geoapify API key",
      "password": true
    }
  ],
  "servers": {
    "geoapify": {
      "type": "http",
      "url": "https://api.geoapify.com/v1/mcp",
      "headers": {
        "x-api-key": "${input:geoapify-api-key}"
      }
    }
  }
}

Start geoapify from the MCP configuration editor, enter the key when VS Code asks for it, and approve the trust prompt. The password input keeps the API key out of mcp.json.

Optional: let Copilot prepare the configuration

Open Copilot Chat in Agent mode and send this request:

Add a remote HTTP MCP server named "geoapify" to this VS Code workspace.
Use https://api.geoapify.com/v1/mcp as the URL and send the API key in the
x-api-key header. Configure a password-type prompt input named
"geoapify-api-key" and reference it from the header so no real API key is
written to mcp.json. Preserve all existing inputs and MCP servers. Show me
the file and the exact changes when you finish, but do not call any tools yet.

Review the generated mcp.json before accepting it. It should define an HTTP server, reference ${input:geoapify-api-key} from the x-api-key header, and contain no real credential. If Copilot cannot edit the configuration, apply the JSON manually.

For configuration locations, server controls, input variables, and workspace trust behavior, see the official VS Code MCP server guide.

Configure Geoapify MCP in Claude Code

Set GEOAPIFY_API_KEY in the environment that starts Claude Code. Add this entry to the project's .mcp.json, preserving any existing MCP servers:

{
  "mcpServers": {
    "geoapify": {
      "type": "http",
      "url": "https://api.geoapify.com/v1/mcp",
      "headers": {
        "x-api-key": "${GEOAPIFY_API_KEY}"
      }
    }
  }
}

Restart Claude Code if you set or changed the environment variable, then run claude mcp get geoapify or open /mcp to review and approve the connection. The configuration must contain the environment reference, not the real key.

Optional: let Claude Code prepare the configuration

After setting the environment variable, send this request:

Add a project-scoped remote HTTP MCP server named "geoapify" to this project.
Use https://api.geoapify.com/v1/mcp as the URL and send the API key in the
x-api-key header. Reference the existing GEOAPIFY_API_KEY environment variable;
do not write its value into .mcp.json or any other file. Preserve all existing
MCP servers. Show me the resulting configuration and explain how I can verify
the connection, but do not call any Geoapify tools yet.

Review the generated .mcp.json. It should reference ${GEOAPIFY_API_KEY} and contain no real credential. If Claude Code cannot edit its own MCP configuration, apply the JSON manually.

For configuration scopes, environment expansion, managed settings, and authentication options, see the official Claude Code MCP guide.

Configure Geoapify MCP in Cursor

Set GEOAPIFY_API_KEY in the environment that starts Cursor. Add this entry to .cursor/mcp.json, preserving any existing MCP servers:

{
  "mcpServers": {
    "geoapify": {
      "url": "https://api.geoapify.com/v1/mcp",
      "headers": {
        "x-api-key": "${env:GEOAPIFY_API_KEY}"
      }
    }
  }
}

Restart Cursor after changing its environment, then open Customize → MCPs and enable geoapify. Confirm that the configuration contains the environment reference rather than the key.

Optional: let Cursor Agent prepare the configuration

Open an Agent chat and send this request:

Add a remote MCP server named "geoapify" to this project's .cursor/mcp.json.
Use https://api.geoapify.com/v1/mcp as the URL and send the API key in the
x-api-key header using Cursor's ${env:GEOAPIFY_API_KEY} environment-variable
syntax. Never write the real key into the file. Preserve every existing MCP
server and show me the exact changes before using any Geoapify tools.

Review the generated .cursor/mcp.json and confirm that it contains the environment reference rather than the key. If Cursor Agent cannot edit the configuration, apply the JSON manually.

For project and global configuration, environment variables, tool controls, and connection troubleshooting, see the official Cursor MCP guide.

Configure Geoapify MCP in Windsurf Cascade

Set GEOAPIFY_API_KEY in the environment that starts Windsurf. Add this entry to ~/.codeium/windsurf/mcp_config.json, preserving any existing MCP servers:

{
  "mcpServers": {
    "geoapify": {
      "serverUrl": "https://api.geoapify.com/v1/mcp",
      "headers": {
        "x-api-key": "${env:GEOAPIFY_API_KEY}"
      }
    }
  }
}

Restart Windsurf after changing its environment, open the MCP settings, and enable only the Geoapify tools required by the task. Confirm that the configuration contains the environment reference rather than the key.

Optional: let Cascade prepare the configuration

Open Cascade and send this request:

Add a remote MCP server named "geoapify" to my Windsurf MCP configuration.
Use https://api.geoapify.com/v1/mcp as serverUrl and send the API key in the
x-api-key header using ${env:GEOAPIFY_API_KEY}. Never copy the real key into
the configuration. Preserve every existing MCP server. If you cannot edit the
private user configuration, show me the exact JSON entry and where to add it.
Do not call any Geoapify tools yet.

Review ~/.codeium/windsurf/mcp_config.json and confirm that it contains the environment reference rather than the key. If Cascade cannot edit the private user configuration, apply the JSON manually.

For the configuration file, remote-server fields, tool limits, and MCP controls, see the official Windsurf Cascade MCP guide.

Configure Geoapify MCP in Gemini CLI

Open the private user configuration at ~/.gemini/settings.json and add this entry, preserving any existing settings and MCP servers:

{
  "mcpServers": {
    "geoapify": {
      "httpUrl": "https://api.geoapify.com/v1/mcp",
      "headers": {
        "x-api-key": "YOUR_API_KEY"
      },
      "trust": false
    }
  }
}

Replace YOUR_API_KEY directly in that private local file. Never send the key through a chat, commit the file, share it, or capture it in a screenshot. Keep trust set to false initially so Gemini CLI asks for confirmation before tool calls.

Restart Gemini CLI and run /mcp list to confirm that geoapify is connected and its tools are available.

Optional: let Gemini CLI prepare the configuration

Start Gemini CLI and send this request without including your real API key:

Add a remote MCP server named "geoapify" to my private user-level Gemini CLI
settings. Use https://api.geoapify.com/v1/mcp as httpUrl, add an x-api-key
header whose value is the placeholder YOUR_API_KEY, and set trust to false.
Preserve all existing settings and MCP servers. Show me the file path and exact
changes, but do not ask me to paste the real key into this chat and do not call
any Geoapify tools yet.

Review ~/.gemini/settings.json, then replace YOUR_API_KEY directly in that private local file. If Gemini CLI cannot edit its own settings, apply the JSON manually. For settings precedence, supported HTTP fields, tool filtering, and the /mcp commands, see the official Gemini CLI MCP guide.

Try example requests

After saving the configuration, check the client's MCP server or tools panel. A successful connection has these observable results:

• Geoapify appears as a connected and enabled remote server.
• Tools such as geocode_address, search_places, and calculate_route are available with input schemas.
• The client displays a tool approval when confirmation is enabled.
• A completed tool call returns isError: false and a structured result.

The client normally performs initialize and tools/list automatically. You do not need to send those protocol requests manually during normal use.

Try a minimal task:

Use Geoapify tools to geocode 20 W 34th St, New York, NY 10001, USA. Return the formatted
address and coordinates.

The successful result should contain a formatted address and numeric lat and lon values in structuredContent.results.

Confirm that the result matches the request and that the client does not expose the API key or a credential-bearing URL in its transcript. The client should read the current schemas returned by tools/list or the MCP tools reference, because the schemas reject undocumented arguments.

Use the following text requests to verify more of the available toolset. Copy a request into the AI client and allow it to select and chain the appropriate Geoapify operations. The examples start with real test addresses so the client must geocode each location before routing, searching, or working with geometry. Only the reverse-geocoding examples start with coordinates.

Troubleshoot and secure the connection

Identify the stage that failed before changing the configuration:

Protocol-version diagnostics

Let the MCP client negotiate protocol initialization and headers. For a manual non-browser diagnostic, the endpoint accepts MCP-Protocol-Version: 2025-06-18; when omitted, the endpoint currently defaults to that version. Browser-originated requests should omit the header because the endpoint's current CORS preflight response does not allow it. A web client may send MCP requests from its own backend, so determine where the network request actually runs instead of inferring it from the user interface.

Permissions, privacy, and credit usage

• Review the discovered tool names and schemas before trusting the server.
• Keep confirmation enabled initially, particularly for repeated routing, matrix, and place-search requests.
• Enable only the tools required by the current workflow when the client supports tool filtering.
• Remember that location input is processed by the AI client or provider and Geoapify. Avoid sensitive personal-location data unless the application's privacy policy permits it.
• Do not log API keys, authorization headers, or full URLs containing apiKey.
• initialize, tools/list, and notifications cost 0 credits. Each tools/call is priced as its underlying Geoapify API operation.

If the independent curl test succeeds but the client still fails, preserve only non-sensitive client logs and compare the configuration with the client's official guide. Never paste the API key, authorization header, or credential-bearing endpoint into a support request.