Geoapify MCP Server

The Geoapify MCP Server lets MCP-compatible clients access Geoapify location tools through a JSON-RPC endpoint. Use it to connect AI agents and developer tools to geocoding, place search, routing, and route-matrix operations without building a custom API integration layer.

Geoapify MCP is available through the following HTTP endpoint:

https://api.geoapify.com/v1/mcp?apiKey=YOUR_API_KEY

The endpoint accepts JSON-RPC requests. For example, use tools/list to discover the available tools:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list"
}

The server currently exposes seven tools. See MCP tools for the full list and the tool-specific references.

Quick start

The Geoapify MCP endpoint requires a Geoapify API key. You can use the same API key that you use for Geoapify Geocoding API requests.

How to get a Geoapify API key

1. Register or sign in on the Geoapify MyProjects page.
2. Create a project.
3. Open the API Keys section.
4. Copy an existing API key or generate a new one.
5. Optionally protect the API key with allowed IP addresses, HTTP referrers, origins, and CORS settings.

MCP endpoint

Use the MCP endpoint with your API key:

https://api.geoapify.com/v1/mcp?apiKey=YOUR_API_KEY

Replace YOUR_API_KEY with your Geoapify API key before sending requests.

Authorization methods

The Geoapify MCP endpoint accepts a Geoapify API key in three ways:

Query parameter example

curl -X POST "https://api.geoapify.com/v1/mcp?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list"
  }'

API key header example

curl -X POST "https://api.geoapify.com/v1/mcp" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list"
  }'

Authorization header example

curl -X POST "https://api.geoapify.com/v1/mcp" \
  -H "Content-Type: application/json" \
  -H "Authorization: ApiKey YOUR_API_KEY" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list"
  }'

Swagger usage

The OpenAPI specifications use the apiKey query parameter. Each tool reference has a tool-specific Swagger panel with the matching tools/call request schema and structured response schema. Enter your Geoapify API key in the apiKey parameter field before executing the POST /mcp request. Swagger omits the optional MCP-Protocol-Version header, so the endpoint uses its default protocol version, 2025-06-18.

Configuration

Geoapify MCP works through an HTTP JSON-RPC endpoint. Configure your MCP-compatible client to send JSON-RPC requests to the Geoapify MCP URL:

https://api.geoapify.com/v1/mcp?apiKey=YOUR_API_KEY

Request format

Send JSON-RPC requests with POST and the application/json content type.

curl -X POST "https://api.geoapify.com/v1/mcp?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list"
  }'

Non-browser MCP clients can optionally send the MCP-Protocol-Version: 2025-06-18 header. Browser clients, including Swagger UI, should omit this header because the endpoint's current CORS preflight response does not allow it. When the header is omitted, the endpoint defaults to version 2025-06-18; explicitly unsupported versions are rejected.

Initialize a client session

MCP clients can initialize the connection and read the server capabilities before listing or calling tools:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-06-18",
    "capabilities": {},
    "clientInfo": {
      "name": "example-client",
      "version": "1.0.0"
    }
  }
}

List available tools

Use the tools/list method to get the tools supported by the Geoapify MCP endpoint:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list"
}

The response contains the available tool names, descriptions, and input schemas. Use those schemas when calling a tool with tools/call.

Call a tool

Use tools/call with a tool name and an arguments object:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "geocode_address",
    "arguments": {
      "query": "1600 Pennsylvania Ave NW, Washington, DC"
    }
  }
}

Check the result of tools/list for the exact tool names, input schemas, and output schemas supported by your endpoint.

MCP tools

The Geoapify MCP endpoint exposes Geoapify location services as MCP tools. Call tools/list to get the current list of available tools and their input schemas.

Request URL

https://api.geoapify.com/v1/mcp?apiKey=YOUR_API_KEY

List tools request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list"
}

Available tools

Common arguments

The geocoding tools share several optional arguments:

Each tool schema sets additionalProperties to false, so requests should include only the arguments listed by tools/list.

The Places tools use the values returned by list_place_categories instead of accepting arbitrary category names. The routing tools accept coordinate objects with lat and lon; use a geocoding tool first when your input contains addresses rather than coordinates.

Calling a tool

Call tools with the tools/call method. The name value must match a tool name from tools/list, and arguments must match that tool's input schema.

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "geocode_address",
    "arguments": {
      "query": "1600 Pennsylvania Ave NW, Washington, DC",
      "limit": 1,
      "lang": "en"
    }
  }
}

Response format

MCP responses use JSON-RPC. A successful tool response contains a result object with text content, tool-specific structuredContent, and an isError flag. A JSON-RPC error response contains an error object with a code and message.

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {}
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32602,
    "message": "Invalid params"
  }
}

Pricing

Geoapify uses credits to calculate API usage. MCP requests are priced according to the action they perform:

There is no separate MCP surcharge. Each tools/call request uses the pricing rule of the Geoapify action performed by that tool.

Geocoding and Places operations are feature-based:

credits = max(1, ceil(returned_features / 20))

That means a geocoding or Places search tool call costs at least 1 credit.

If a feature-based tool returns more than 20 features, the cost increases by 1 credit for each additional group of up to 20 returned features.

Routing uses the following base calculation:

credits =
  waypoint_segments
  + barrier_count
  + bias_count
  + filter_count
  + avoid_cost
  + floor(route_distance_meters / 500000)

Stop optimization adds the route-matrix cost for the intermediate stops. Avoid options also add credits according to their type and count.

Route Matrix uses the following calculation:

matrix_cost = max(sources, targets) * min(sources, targets, 10)

credits =
  matrix_cost
  + avoid_cost
  + sum(floor(route_distance_meters / 500000))

Check Geoapify Pricing Plans and choose the plan that fits your expected daily credit usage.