How to Add Geoapify MCP Tools to OpenClaw and Other AI Agents

Add location tools to an AI agent

This guide uses OpenClaw as the concrete AI-agent runtime. You will add the remote Geoapify MCP Server to OpenClaw, confirm that the agent can discover its tools, and then answer: “Find a restaurant within two kilometers of Alexanderplatz in Berlin.” The request contains a place name and a human category, while search_places requires coordinates and a supported Geoapify category identifier.

The same tool sequence works with other MCP-compatible agents and agentic clients, including Claude Code, Cursor, VS Code with GitHub Copilot, Windsurf Cascade, and Gemini CLI. Configure those clients with the dedicated Geoapify MCP client guide. ChatGPT can also act as an MCP client in developer mode, but its current authentication options require additional consideration for Geoapify's API-key-protected endpoint.

The agent therefore needs a deliberate tool sequence:

1. Geocode Alexanderplatz, Berlin, Germany.
2. Resolve the restaurant category when it is not already known.
3. Search around the returned coordinates.
4. Present only places returned by the tool.

Task flow: Geoapify MCP configuration → tool discovery → natural-language request → geocode_address → category selection → search_places → grounded answer.

The output of one call becomes the input of the next. Preserve lat as latitude and lon as longitude between calls. GeoJSON arrays elsewhere use [longitude, latitude]; the MCP tools in this workflow use named lat and lon fields instead.

Configure Geoapify MCP tools in OpenClaw

Set GEOAPIFY_API_KEY in the environment that starts OpenClaw. Add the geoapify server under mcp.servers in the OpenClaw configuration, preserving all existing settings and server definitions:

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

Keep the environment-variable reference in the configuration. Do not replace it with the real API key or put the key in the server URL.

Optional: let OpenClaw prepare the configuration

An OpenClaw agent can help configure the server when its active tool profile allows it to run commands and update the OpenClaw configuration. Set GEOAPIFY_API_KEY before starting OpenClaw, then send this request without including the key:

Add a remote MCP server named "geoapify" to my OpenClaw configuration.
Use https://api.geoapify.com/v1/mcp as the URL and streamable-http as the
transport. Send the existing GEOAPIFY_API_KEY environment variable in the
x-api-key header. Keep the value as ${GEOAPIFY_API_KEY}; never read, print,
or copy the real key into the configuration or conversation. Preserve every
existing setting and MCP server. Show me the exact proposed configuration
change before applying it. After I approve the change, run
openclaw mcp doctor geoapify --probe, but do not call any Geoapify tools yet.

Review the proposed change before approving it. The result must add only the geoapify entry under mcp.servers and must contain ${GEOAPIFY_API_KEY} rather than the credential. If the agent cannot update its own configuration, apply the JSON manually.

Whether you configure the server manually or with OpenClaw's help, run a live probe after saving it:

openclaw mcp doctor geoapify --probe

A successful probe connects to the server and reports the discovered tools. If the server is saved but its tools are not available to the agent, check that the server is enabled, the active OpenClaw tool profile exposes MCP tools, and bundle-mcp is not denied. Reload the MCP runtime or restart the process that owns it after changing the configuration.

OpenClaw is the MCP client in this setup. Do not use openclaw mcp serve; that command runs OpenClaw itself as an MCP server for external clients instead of adding Geoapify tools to OpenClaw-managed agent runs.

Define the MCP tool sequence

First call geocode_address:

{
  "query": "Alexanderplatz, Berlin, Germany",
  "limit": 1,
  "lang": "en"
}

Require exactly one confident origin before continuing. If the result is empty or several candidates are materially different, ask the user to clarify instead of choosing silently.

When the desired category is not known, call list_place_categories with an empty argument object and select the supported identifier catering.restaurant. Cache or reuse the discovered category list when appropriate; it does not need to be fetched before every place search.

Finally call search_places using the coordinates returned by geocoding:

{
  "category": "catering.restaurant",
  "lat": 52.52167,
  "lon": 13.41328,
  "radius_meters": 2000,
  "limit": 5,
  "lang": "en"
}

The coordinate values above illustrate the data flow. At runtime, pass the actual lat and lon from the selected geocoding result rather than copying fixed values. Return the place name, formatted address, and distance when available. Do not claim that the first result is “best” unless the application defines and applies its own ranking rule.

Add agent instructions and guardrails

Give the agent explicit rules for choosing and chaining tools:

Use Geoapify MCP tools for location facts.

- Read each tool's current input schema before calling it and never add undocumented arguments.
- Geocode user-provided place names before calling tools that require coordinates.
- If geocoding is empty or ambiguous, ask for clarification.
- Use list_place_categories when no supported Places category is known.
- Copy named lat and lon values without swapping them.
- Keep searches within the user's requested radius and result limit.
- Present only tool-returned places; label missing fields rather than inventing them.
- Stop after an authorization, quota, or repeated tool error and explain the failure.

Validate every call against the schema returned by tools/list. Set additionalProperties expectations strictly: Geoapify MCP tool schemas reject unknown fields. Limit result counts and geometry detail to what the response needs so the agent does not fill its context with unused data.

Log tool names, durations, status, and non-sensitive error categories for observability. Do not log API keys, authorization headers, complete credential-bearing URLs, or personal location inputs unless the application's privacy policy explicitly requires and protects that data.